Stapling attaches Apple's notarization ticket to your app, disk image or installer package, so Gatekeeper can confirm notarization without a network connection. You can skip it, because the ticket is also published online. But then users with no connection at first launch lose that check.
Definitions
Notarization is an automated check by Apple's notary service. It scans your Developer ID signed software for malicious content and code signing problems, then returns a result. If nothing is wrong, the service generates a ticket.
Stapling is the step that attaches that ticket to your software, using Apple's stapler tool. Apple's documentation says the ticket is also published online where Gatekeeper can find it, so stapling is about the offline case and about future copies.
What happens with and without a staple
| Situation | Not stapled | Stapled |
|---|---|---|
| User is online at first launch | Gatekeeper finds the ticket online | Gatekeeper reads the attached ticket |
| User is offline at first launch | Gatekeeper cannot find the ticket | Gatekeeper still finds the ticket |
| User downloaded before you notarized | Works once notarization completes, if online | Not applicable to old copies |
Apple says that after notarization completes, the next time any user runs your app on macOS 10.14 or later, Gatekeeper finds the ticket online, including users who downloaded before notarization. It also says you should attach the ticket so future distributions include it and Gatekeeper can find it with no network.
What you can and cannot staple
Apple's documentation gives specific rules.
- You can staple tickets to apps, bundles, disk images and flat installer packages.
- You can notarize a ZIP archive but you cannot staple to it directly. Instead, staple each item you put in the archive, then create a new ZIP containing the stapled items.
- Tickets are created for standalone binaries, but it is not currently possible to staple them.
The ZIP rule trips up many release scripts. A script that zips an app, notarizes the zip, and ships that same zip produces a notarized but unstapled app. To staple, you need the order to be: notarize, staple the app, then zip.
Nested tickets and custom installers
Apple notes that the notary service generates a ticket for the top-level file you submit and for each nested file. A disk image holding an installer package that holds an app produces three tickets.
If you use a custom third-party installer, Apple describes two rounds. First notarize the payload, then package the notarized and stapled items into the installer and notarize that as well. With a network installer, notarize both the installer and the items it downloads.
A release step you can test
Add a check to your release job, so a missing staple fails the build instead of reaching users:
xcrun stapler validate MyApp.app
Run it on the exact artifact you upload to your website, not on an earlier build output. Then open the shipped file on a test Mac with networking off and confirm it launches with the notarized dialog.
Where Safeguard fits
A stapled ticket says Apple checked the build. It does not list the dependencies inside it. Safeguard scans dependencies and creates SBOMs for each release, and you can try a free scan at gold.safeguard.sh/scan.
Quick check
Is stapling required for notarization?
No. Apple publishes the ticket online, so notarization works without it. Stapling adds offline support and makes future distributions carry the ticket.
Can I staple a ticket to a ZIP file?
No. Apple says you cannot staple to a ZIP directly. Staple the items first, then build a new ZIP from the stapled items.
Do users who already downloaded my app need a new copy?
Per Apple, Gatekeeper finds the ticket online for them once notarization completes, so they do not need a new copy as long as they are online.
Sources
- Apple Developer: Customizing the notarization workflow
- Apple Developer: Notarizing macOS software before distribution
Last reviewed: 19 October 2026.
