How to Use the macOS productbuild Command to Create Mac App Store Installers

When macOS developers finish compiling an application, they cannot simply hand a raw .app file to an enterprise client or upload it to the Mac App Store. Applications often require pre-flight installation scripts, custom licensing agreements, and cryptographic signatures to pass Apple’s strict Gatekeeper security checks. To mathematically package an application into a professional, flat .pkg installer that the macOS Installer application can native execute, systems engineers and developers use the productbuild command.

Why Use the productbuild Command?

While the older pkgbuild command is excellent for packaging raw payload directories, productbuild is the modern, high-level wrapper required for professional distribution. productbuild takes an existing component package (or a raw application bundle) and synthesizes it into a fully-fledged \”Product Archive.\” This archive is the exact mathematical format required by the Mac App Store. Furthermore, productbuild allows you to synthesize a custom Distribution XML file, enabling you to build complex installers that present custom EULA text, restrict installations based on macOS version, or dynamically offer the user optional sub-components during the install wizard.

Step 1: Synthesize a Distribution File

Before you build the final package, you should generate a Distribution XML file. This file controls the graphical layout of the Installer application.

1. Open the macOS Terminal.
2. Assuming you already have an application bundle named MyApp.app on your Desktop, run the command to mathematically generate a Distribution template:

productbuild --synthesize --component ~/Desktop/MyApp.app ~/Desktop/Distribution.xml

This command creates a raw XML file. You can open this file in a text editor to add custom logic, such as forcing the installer to only run on macOS 13 or newer, or linking to a License.rtf document that the user must mathematically accept.

Step 2: Build the Product Archive

Once your Distribution XML is configured, you can build the final, flat .pkg file.

1. Run the productbuild command, pointing it to both the Distribution file and the source application:

productbuild --distribution ~/Desktop/Distribution.xml --package-path ~/Desktop/ ~/Desktop/FinalInstaller.pkg

The compiler will ingest the application, parse your XML logic, and output a professional FinalInstaller.pkg file that is ready for deployment via MDM (Mobile Device Management) solutions like Jamf.

Step 3: Cryptographically Sign the Installer

If you intend to distribute this package outside of an MDM environment (e.g., as a direct download from a website), Gatekeeper will block it unless it is mathematically signed with an Apple Developer ID.

1. You must append the --sign flag, followed by the exact name of your Developer ID Installer certificate (found in your Keychain Access app):

productbuild --sign \"Developer ID Installer: Your Name (TeamID)\" --component ~/Desktop/MyApp.app /Applications ~/Desktop/SignedInstaller.pkg

The command will invoke the macOS security framework, attach a cryptographic hash to the flat package, and ensure that the payload cannot be mathematically tampered with by malware during transit.

By mastering the productbuild command, developers can move beyond simple drag-and-drop .dmg files and engineer secure, compliant, and highly customized installation experiences for their macOS applications.