.pkg installer outside the Mac App Store without triggering Gatekeeper errors, build component packages with pkgbuild, assemble them into a product archive with productbuild --distribution, and sign the final .pkg using a Developer ID Installer certificate before notarizing it.Why this happens
When distributing a macOS application outside the Mac App Store as an installer package (.pkg), Gatekeeper inspects both the installer archive itself and the app bundle inside it. Legacy GUI packaging tools like Apple’s retired PackageMaker no longer exist in modern toolchains, and raw component packages or installers signed with the wrong certificate type (Developer ID Application instead of Developer ID Installer) will fail Gatekeeper verification.
Apple splits modern command-line packaging into three distinct tools shipped with macOS:
pkgbuildcreates individual component packages containing an app payload and installation scripts.productbuildwraps one or more component packages together with aDistribution.xmlfile (which controls welcome screens, licenses, and target requirements) into a final product archive.productsign(or the--signflag onproductbuild) signs the installer archive using aDeveloper ID Installercertificate.
Note that these steps apply strictly to direct distribution outside the Mac App Store. Mac App Store .pkg files use 3rd Party Mac Developer Installer (or Apple Distribution) certificates and different productbuild rules.
How to fix it
1. Build and sign a product archive with pkgbuild and productbuild
First, make sure your .app bundle is already signed with your Developer ID Application certificate and has the Hardened Runtime enabled. Then, package and sign the .pkg using a Developer ID Installer certificate installed in your Keychain.
Step 1: Stage your payload and generate a component plist
Avoid passing --root MyApp.app directly without a staging folder, or pkgbuild may place the contents of your app bundle directly at the root directory instead of keeping the .app folder intact. Create a clean staging directory first:
mkdir -p build/payload/Applications
cp -R "path/to/MyApp.app" build/payload/Applications/
Analyze the staged root to generate a component property list:
pkgbuild --analyze --root build/payload Component.plist
Open Component.plist and check BundleIsRelocatable. By default, pkgbuild sets BundleIsRelocatable to true, meaning the macOS Installer will overwrite an existing copy of your app anywhere on the user’s disk (such as a copy sitting in ~/Downloads) instead of installing into /Applications. Set BundleIsRelocatable to <false/> in Component.plist if you always want the app installed to /Applications.
Step 2: Build the component package
Run pkgbuild using your staging root, component plist, bundle identifier, and version:
pkgbuild \
--root build/payload \
--component-plist Component.plist \
--identifier "com.example.MyApp.pkg" \
--version "1.0.0" \
--install-location "/" \
MyApp-Component.pkg
If you need preinstall or postinstall shell scripts, place executable scripts with those exact filenames (no .sh extension) inside a folder and pass --scripts ./Scripts.
Step 3: Synthesize and customize Distribution.xml
Generate a baseline distribution definition from your component package(s):
productbuild --synthesize \
--package MyApp-Component.pkg \
Distribution.xml
If your project builds multiple targets—such as a main app and a helper app—pass multiple --package flags (--package Main.pkg --package Helper.pkg) to include both in the same Distribution.xml. You can edit Distribution.xml to add <title>, <welcome>, <license>, or <background> elements pointing to files in a resources directory.
Step 4: Build and sign the final .pkg
Combine the distribution file, resources, and component packages, signing directly with your Developer ID Installer identity:
productbuild \
--distribution Distribution.xml \
--package-path . \
--resources ./Resources \
--sign "Developer ID Installer: Your Name (TEAMID1234)" \
MyApp-Installer.pkg
If you have an unsigned .pkg that was already generated earlier in a build pipeline, you can sign it separately with productsign:
productsign \
--sign "Developer ID Installer: Your Name (TEAMID1234)" \
Unsigned-Installer.pkg \
MyApp-Installer.pkg
Verify the signature before distributing:
pkgutil --check-signature MyApp-Installer.pkg
Step 5: Notarize and staple the installer
On modern macOS releases, a Developer ID signature alone is not enough—Gatekeeper also requires notarization. Submit the signed .pkg with notarytool and staple the ticket:
xcrun notarytool submit MyApp-Installer.pkg \
--keychain-profile "AC_PASSWORD" \
--wait
xcrun stapler staple MyApp-Installer.pkg
2. Automate packaging in an Xcode Archive script or CI step
If you want to build the .pkg automatically from Xcode build settings during an Archive/Install build, add a dedicated Package directory to your repository containing Distribution.xml, Component.plist, Resources, and Scripts.
In a post-archive script or Run Script build phase configured with Run script: For install builds only, read CFBundleShortVersionString or CFBundleVersion from the built app and invoke pkgbuild and productbuild:
set -euo pipefail
APP_PATH="${BUILT_PRODUCTS_DIR}/${FULL_PRODUCT_NAME}"
VERSION=$(/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "${APP_PATH}/Contents/Info.plist")
SAFE_NAME=$(echo "${PRODUCT_NAME}" | tr ' ' '_')
STAGE_DIR="${TEMP_DIR}/pkg_stage"
rm -rf "${STAGE_DIR}"
mkdir -p "${STAGE_DIR}/Applications"
ditto "${APP_PATH}" "${STAGE_DIR}/Applications/${FULL_PRODUCT_NAME}"
pkgbuild \
--root "${STAGE_DIR}" \
--component-plist "${SRCROOT}/Package/Component.plist" \
--scripts "${SRCROOT}/Package/Scripts" \
--identifier "com.example.pkg.${SAFE_NAME}" \
--version "${VERSION}" \
--install-location "/" \
"${TEMP_DIR}/${SAFE_NAME}-Component.pkg"
productbuild \
--distribution "${SRCROOT}/Package/Distribution.xml" \
--package-path "${TEMP_DIR}" \
--resources "${SRCROOT}/Package/Resources" \
--sign "Developer ID Installer: Your Name (TEAMID1234)" \
"${BUILT_PRODUCTS_DIR}/${SAFE_NAME}-${VERSION}.pkg"
Using ditto instead of cp -R preserves extended attributes, symlinks inside frameworks, and code signatures inside the .app bundle.
3. Inspect existing .pkg archives with pkgutil
If your installer behaves unexpectedly or you want to inspect how another standard macOS installer structures its Distribution.xml and scripts, expand the flat package into a folder using pkgutil:
pkgutil --expand MyApp-Installer.pkg ExpandedPackage
Note that modifying files inside an expanded package and running pkgutil --flatten invalidates any existing cryptographic signature. Always re-sign with productsign after flattening.
4. Alternative: Use the third-party “Packages” GUI/CLI tool
If maintaining hand-written Distribution.xml files, localization folders, and component plists becomes tedious, many macOS developers use Packages by Stéphane Sudre. It provides a native macOS GUI for configuring payloads, installation scripts, requirements, and custom installer steps, while also installing a packagesbuild command-line tool that fits directly into Xcode build phases and CI scripts. Even when building with packagesbuild, sign the resulting .pkg with productsign and notarize it with notarytool.
How to prevent it
- Keep certificate types straight: Sign
.appbundles, binaries, and frameworks with Developer ID Application, and sign.pkgarchives exclusively with Developer ID Installer. - Disable bundle relocation unless needed: Always verify
BundleIsRelocatableisfalseinComponent.plistso macOS Installer does not silently update an old copy of your app in~/Downloadsor a build folder. - Preserve symlinks when staging: Use
dittorather than plaincpwhen copying.appbundles into your staging directory so framework symlinks remain valid. - Notarize the outer container: When distributing a
.pkg, notarize and staple the signed.pkgitself—not just the.appinside it.
FAQ
Do I need a .pkg if my macOS app doesn’t need root scripts or system extensions?
Usually no. If your app is a self-contained .app bundle that goes straight into /Applications, a signed and notarized .dmg or .zip is simpler to maintain. Use a .pkg when you need preinstall/postinstall scripts, LaunchDaemons, audio plug-ins, or multi-location payloads.
Why does productsign fail with could not find appropriate signing identity?
You likely only have a Developer ID Application certificate in your Keychain. Open Xcode’s Settings > Accounts > Manage Certificates (or the Apple Developer portal) and create a Developer ID Installer certificate—only the Account Holder role on an Apple Developer Team can generate Developer ID certificates.
Can I submit a Developer ID signed .pkg to the Mac App Store?
No. App Store Connect rejects packages signed with Developer ID Installer. Mac App Store packages must be signed with Apple Distribution or 3rd Party Mac Developer Installer and built without custom Distribution.xml install scripts.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
