Apple requires all software distributed outside the Mac App Store to be notarized by Apple’s automated notary service. To ensure that users can install and launch your application even when their Mac is offline or behind an enterprise firewall, the notarization ticket issued by Apple must be attached directly to the software bundle. The built-in stapler command-line utility in macOS Terminal handles this process by querying Apple servers, downloading the ticket, and embedding it into your binary, disk image, or installer package.
Understanding Notarization and Ticket Stapling
When an application is notarized, Apple generates a cryptographic ticket that certifies the executable has been scanned and verified for malicious components. While macOS Gatekeeper can query Apple’s servers over the internet upon initial launch, network timeouts or offline environments can trigger security blocks. “Stapling” embeds this ticket directly into the Mach-O application bundle (.app), Apple disk image (.dmg), or flat installer package (.pkg), allowing Gatekeeper to validate the software completely offline.
Syntax and Available Commands
stapler action [options] targetstaple: Attaches a cryptographic notarization ticket to the specified target.validate: Inspects a target and verifies whether a valid notarization ticket is already stapled.-v(Verbose): Displays detailed debugging output and network communication details during processing.-q(Quiet): Suppresses standard status messages, ideal for automated continuous integration (CI) pipelines.
Step-by-Step Practical Implementation
Step 1: Verify Prerequisites
Before stapling a ticket, ensure your application has been successfully submitted and approved by the Apple Notary Service via xcrun notarytool. Stapling will fail if Apple has not yet generated a ticket for your software’s specific cryptographic code hash.
Step 2: Staple an Application Bundle (.app)
- Open Terminal from
/Applications/Utilities/. - Run the
stapler staplecommand pointing to your signed and notarized application bundle:xcrun stapler staple /path/to/YourApplication.app - Terminal queries Apple’s CloudKit servers. Upon success, you will see:
Processing: /path/to/YourApplication.app The staple and validate action worked!
Step 3: Staple an Apple Disk Image (.dmg)
If you distribute your application inside a disk image, both the inner application bundle and the outer DMG container should be stapled:
xcrun stapler staple /path/to/DistributionImage.dmgStep 4: Validate the Stapled Ticket
To confirm that the notarization ticket is properly embedded and valid for offline execution, run:
xcrun stapler validate /path/to/YourApplication.appIf the ticket is present and uncorrupted, the utility returns The validate action worked!
Comparison of macOS Software Validation Tools
| Tool / Command | Primary Function | Offline Capable | Target Artifacts | Key Use Case |
|---|---|---|---|---|
stapler staple |
Embeds notarization ticket | No (Requires Apple query) | .app, .dmg, .pkg | Final deployment preparation for external distribution |
stapler validate |
Verifies embedded ticket integrity | Yes | .app, .dmg, .pkg | Pre-release QA to verify offline Gatekeeper compliance |
spctl --assess |
Assesses Gatekeeper policy acceptance | Yes (if stapled) | Executables, .app | Testing launch approval under macOS security rules |
codesign --verify |
Verifies signature seal integrity | Yes | Mach-O binaries, bundles | Ensuring code has not been tampered with or modified |
Troubleshooting Common Stapler Errors
- “Could not find a ticket for this item”: The upload to Apple Notary Service either failed, is still in progress, or the local binary was modified after submission. Re-check notary status with
xcrun notarytool history. - Unsupported File Format:
stapleronly supports Mach-O application bundles, DMGs, and flat packages. It cannot staple raw ZIP archives or tarballs directly. - Read-Only File Permissions: Ensure your build user has write permissions to the target bundle directory; otherwise, embedding the ticket will result in a permission denied error.