Clavem

How to notarize and distribute a Mac app outside the App Store

To notarize a Mac app, sign it with a Developer ID Application certificate, the hardened runtime and a secure timestamp, upload it with xcrun notarytool submit --wait, then attach the ticket with xcrun stapler staple. Nearly every rejection comes from one of seven causes, listed below with the exact message Apple returns.

What notarization is, and what it is not

Notarization is an automated scan. You upload a signed build to Apple’s notary service, which checks it for malicious content and code-signing problems and returns a verdict, usually within minutes. Apple says most software finishes in 5 minutes and 98 percent within 15. If the build passes, Apple issues a ticket that tells Gatekeeper, the macOS check that runs when a downloaded app first opens, that Apple has seen this exact build.

It is not App Review. Nobody judges your features, your pricing or your licensing scheme. That matters for sellers: an app distributed outside the Mac App Store can use license keys, device limits and its own update mechanism. Apple’s App Review Guidelines forbid license keys inside Mac App Store apps, a trade-off covered in selling Mac apps outside the App Store.

Since November 1, 2023, the notary service rejects uploads from altool and from Xcode 13 and earlier. The tool today is notarytool.

The requirements, from Apple’s documentation

Apple’s page lists what the notary service enforces:

  • A valid code signature on every executable you ship.
  • A Developer ID certificate. Use a Developer ID Application certificate for apps and bundles, and a Developer ID Installer certificate for installer packages. Mac Distribution, Apple Development, ad hoc and self-signed certificates fail.
  • The hardened runtime enabled on app and command-line targets.
  • A secure timestamp in the signature.
  • No com.apple.security.get-task-allow entitlement set to true. Xcode adds it for debugging.
  • A link against the macOS 10.9 SDK or later.
  • Entitlements files that are ASCII-encoded, well-formed XML.

You also need an Apple Developer Program membership, because only the Account Holder of the team can create a Developer ID certificate.

Step by step

1. Sign, inside out

Sign nested code first (frameworks, helper tools, XPC services), then the app. The codesign manual page marks --deep as deprecated for signing as of macOS 13.0 and warns that it applies the same options to everything nested, so sign each piece yourself.

IDENTITY="Developer ID Application: Example Ltd (ABCDE12345)"

codesign --force --options runtime --timestamp --sign "$IDENTITY" \
  MyApp.app/Contents/Frameworks/Helper.framework

codesign --force --options runtime --timestamp --sign "$IDENTITY" \
  --entitlements MyApp.entitlements MyApp.app

--options runtime turns on the hardened runtime. --timestamp asks Apple’s timestamp server for a secure timestamp, so it needs an internet connection. Xcode’s Archive and Export workflow does both for you; the commands matter when you build in CI or in a script.

2. Check the signature before you upload

codesign -vvv --deep --strict MyApp.app
codesign -dvv MyApp.app
spctl -vvv --assess --type exec MyApp.app

--strict applies the stricter validation notarization needs. In the -dvv output, a secure timestamp shows up as a Timestamp= line. Apple notes that a Signed Time= line instead means the signature has no secure timestamp.

The output below comes from a macOS 27.2 Mac and a throwaway app signed ad hoc (codesign --sign -), because that machine has no Developer ID identity. It shows what a build that would fail looks like:

CodeDirectory v=20500 size=305 flags=0x10002(adhoc,runtime) hashes=3+3 location=embedded
Signature=adhoc
TeamIdentifier=not set
Demo.app: rejected          # spctl

The runtime flag is present, but Signature=adhoc, TeamIdentifier=not set and the rejected verdict tell you this build has no Developer ID identity behind it. With a real certificate the Authority= lines name your Developer ID and the team identifier is filled in.

3. Package it

The notary service accepts ZIP archives, disk images (UDIF format) and signed flat installer packages. It cannot take a bare .app.

# ZIP
ditto -c -k --keepParent MyApp.app MyApp.zip

# Disk image: build it, sign it, then submit that file
hdiutil create -volname "MyApp" -srcfolder dist -ov -format UDZO MyApp.dmg
codesign --force --timestamp --sign "$IDENTITY" MyApp.dmg

# Installer package: sign with the Installer certificate
productbuild --component MyApp.app /Applications \
  --sign "Developer ID Installer: Example Ltd (ABCDE12345)" MyApp.pkg
pkgutil --check-signature MyApp.pkg

For a custom third-party installer, Apple describes two rounds: notarize the payload first, staple it, package it, then notarize the installer.

4. Save credentials once, then submit

Create an app-specific password for your Apple ID, then store it in the keychain so scripts never contain it:

xcrun notarytool store-credentials "notary-profile" \
  --apple-id "you@example.com" --team-id ABCDE12345 --password "app-specific-password"

xcrun notarytool submit MyApp.zip --keychain-profile "notary-profile" --wait

--wait makes the command exit only when processing is done. The result prints status: Accepted or status: Invalid along with a submission id. Keep the id.

5. Read the log, even on success

xcrun notarytool log SUBMISSION-ID --keychain-profile "notary-profile" log.json

The log is JSON. An issues array lists each problem with a message, the path of the offending file and a severity. Apple advises reading it even when the status is Accepted, because it may hold warnings you can fix before the next submission.

6. Staple and test

xcrun stapler staple MyApp.app
xcrun stapler validate MyApp.app
spctl -vvv --assess --type exec MyApp.app

Stapling attaches the ticket so Gatekeeper finds it with no network. Staple the app, then ZIP it for distribution. Disk images and installer packages can be stapled directly. Standalone binaries get a ticket online but cannot be stapled.

Errors and fixes

These are the messages Apple documents for the most common failures.

Message in the notary log Cause Fix
The signature of the binary is invalid. Unsigned, or the bundle changed after signing Sign again as the last step; check with codesign -vvv --deep --strict
The binary is not signed with a valid Developer ID certificate. Signed with Mac Distribution, Apple Development or a self-signed certificate Use Developer ID Application (installers: Developer ID Installer)
The signature does not include a secure timestamp. A custom signing flow left out --timestamp Add --timestamp, or add it to OTHER_CODE_SIGN_FLAGS in Xcode
The executable requests the com.apple.security.get-task-allow entitlement. The debug entitlement was injected at build time Export from Xcode, or set CODE_SIGN_INJECT_BASE_ENTITLEMENTS to NO for the release build
The binary uses an SDK older than the 10.9 SDK. A very old build toolchain Rebuild against a current SDK; the deployment target is separate
The executable does not have the hardened runtime enabled. --options runtime missing Add it, or enable Hardened Runtime in the Xcode Signing and Capabilities pane
Embedded entitlements are invalid: syntax error near line 1 The entitlements file is a binary property list plutil -convert xml1 MyApp.entitlements, then plutil -lint

Two more details from Apple’s documentation save time. First, a bundle full of non-executable data inside Contents/MacOS slows scanning, so keep data in Contents/Resources. Second, notarizations are limited to 75 per day, which matters if CI submits every commit. Submit release candidates only.

If the hardened runtime breaks a feature, such as loading third-party plug-ins, add the specific entitlement it needs. Do not turn the runtime off: notarization requires it.

Running it in CI

A build server needs a few things that a laptop already has.

  • Network access. Apple’s documentation says notarytool uploads through Amazon S3 Transfer Acceleration by default, and stapler fetches tickets from a set of Apple address ranges on port 443. If your firewall blocks the acceleration host, pass --no-s3-acceleration. Secure timestamps come from timestamp.apple.com, the only timestamp server macOS accepts.
  • Credentials. Run store-credentials once on the runner, or write the keychain profile in a setup step. Keep the app-specific password in your CI secret store, never in the repository.
  • Waiting. notarytool submit --wait blocks until Apple finishes. The tool also has info, wait, history and log subcommands (listed by xcrun notarytool --help on a current Mac), so a pipeline can submit, go on with other work and call notarytool wait SUBMISSION-ID later. --timeout caps how long --wait blocks.
  • Failing loudly. Exit codes alone are not enough: save the log JSON as a build artifact on every run, accepted or not. When a release candidate is rejected, the issues array names the file.

Keep the submission count in mind. Apple limits notarizations to 75 per day, so notarize release candidates and tagged releases, not every commit.

If you sell plug-ins or extensions

Apple’s documentation adds a rule that matters to anyone selling add-ons: in macOS 10.15 and later, an app can load a quarantined plug-in, one that was downloaded from the internet or arrived by AirDrop, only if the plug-in is notarized. Otherwise the user has to approve it manually in System Settings. So a plug-in you sell from your site should be signed with Developer ID and notarized on its own, even when the host app is not yours.

The reverse also holds. Plug-ins do not declare their own entitlements. They inherit those of the host process, so a host app running under the hardened runtime must declare every entitlement its plug-ins need. If you sell the host app, test with real third-party plug-ins before you ship.

After notarization: release files and updates

The notarized and stapled file is what customers download. Clavem stores release files per product and serves them from the buyer’s order page with signed links that expire after an hour. In the dashboard, create a release, upload the DMG or ZIP, give the file the platform label macos, and publish it. Your app can then ask for the newest version:

curl "https://clavem.io/v1/releases/PRODUCT_ID/latest?platform=macos" \
  -H "X-License-Key: YOUR-LICENSE-KEY"

On the demo product, which has no published release, the live API answers 404 with {"error":{"code":"not_found","message":"This product has no published release yet."}}. With a release published and a valid key, the response carries version, notes and a files array whose entries have a one-hour url. The details are in Releases and downloads. Clavem does not sign or notarize anything. Your build pipeline does that before you upload.

If you use the Sparkle update framework instead, its appcast is a separate mechanism, and Sparkle signs update archives with its own EdDSA key in addition to your Developer ID signature. Whichever you pick, the sequence in checking for updates in a desktop app applies.

Questions

Do I have to notarize a Mac app I sell from my own website?

Apple's documentation says software built after June 1, 2019 and distributed with Developer ID must be notarized to run on macOS 10.15 and later. Apple's support page adds that macOS Catalina and later requires notarization by default. Apps in the Mac App Store are exempt because App Review already covers it.

Is notarization the same as App Review?

No. Apple describes notarization as an automated service that scans for malicious content and code-signing problems. It is not a review of what your app does, and it usually finishes in minutes.

Can I staple a ticket to a ZIP file?

No. You can submit a ZIP for notarization, but the stapler cannot attach a ticket to it. Staple the app inside, then build the ZIP again, or distribute a disk image or installer package and staple that.

Can I still use altool?

No. Apple's notary service stopped accepting uploads from altool and from Xcode 13 and earlier on November 1, 2023. Apple's guidance is to move to notarytool or upgrade to Xcode 14 or later.

Sources

  1. Apple, Notarizing macOS software before distribution (as of November 2026)
  2. Apple, Customizing the notarization workflow (as of November 2026)
  3. Apple, Resolving common notarization issues (as of November 2026)
  4. Apple Support, Safely open apps on your Mac (as of November 2026)
  5. Apple, Signing Mac software with Developer ID (as of November 2026)
  6. Apple, App Review Guidelines, section 2.4.5 (as of November 2026)
  7. Sparkle documentation, publishing an appcast and EdDSA signatures (as of November 2026)