When should I use a PKG instead of a DMG?
Use a PKG installer package when you need scripted installation, receipts, managed deployment, or a guided installer flow. DMGs are a better fit for drag-and-drop app delivery.
Guide
How to create a macOS installer package (PKG)
If you need a macOS installer package for customer releases, internal deployment, or CI packaging, the core workflow is simple: build a package payload, add installer metadata, then sign and notarize it.
Quick answer
The lowest-level way to create a macOS installer package, usually distributed as a.pkg file, is with Apple'spkgbuild andproductbuild tools. That works well for basic packages, but teams usually outgrow hand-maintained commands once scripts, versioning, signing, and repeatable release builds start to matter.
- 1Prepare a signed app bundle or payload folder.
- 2Build a component package with pkgbuild.
- 3Optionally wrap it with productbuild for a distribution-style installer.
- 4Sign the resulting installer with a Developer ID Installer certificate.
- 5Notarize the PKG before distribution outside your organization.
Start with the manual workflow
Use pkgbuild for a simple component package
For a straightforward installer package, place the files you want to install in a payload directory, then point pkgbuild at that directory. This is the usual starting point when you want an app installed into/Applications or need a package for MDM distribution.
Example pkgbuild command
pkgbuild \ --root "./payload" \ --identifier "com.example.myapp" \ --version "1.0.0" \ --install-location "/Applications" \ "./build/MyApp.pkg"
Use pkgbuild when
You have one payload, one install location, and limited installer customization.
Add productbuild when
You need a richer distribution installer, custom choices, or multiple component packages.
Common friction points
- Versioning drift
- Shell commands are easy to copy forward with the wrong identifier, version, or install path.
- Scripts and package metadata
- Preinstall and postinstall scripts, requirements, and package settings are awkward to maintain in ad hoc command history.
- Signing and notarization handoff
- Once release steps move into CI, teams usually need clearer logs and a stable project definition.
Best practice
Move to a project-based build
After the first working package, the main improvement is not a different command. It is storing installer settings in a JSON-based project file that can be reviewed, diffed, versioned, and rebuilt consistently by other people or automation.
Why PKGSmith fits here
PKGSmith gives you a native macOS workflow for PKG and DMG projects, then exposes a build-only CLI for repeatable local and CI builds from the same JSON-based.pkgsmith file.
Repeatable build example
Build the installer from a saved PKGSmith project
Once the installer definition lives in a project file, the actual build command becomes short and predictable. That is easier to trust in CI than a long handwrittenpkgbuild invocation copied between jobs.
PKGSmith CLI example
pkgsmith build \ --reference "./MyApp.pkgsmith" \ --output "./build/releases" \ --json
Before you ship
1. Sign
Use the correct Developer ID Installer identity for the package you distribute.
2. Notarize
Submit the installer with Apple's notarization workflow before public release.
3. Verify
Test on a clean machine or VM so installer behavior matches the real first-run experience.
FAQ
Do I need productbuild for every installer?
No. A simple component package can be enough. productbuild becomes useful when you need a distribution installer, custom choices, or multiple component packages.
Do I still need signing and notarization?
Yes for most public distribution. Users and Gatekeeper expect macOS installers to be signed, and external distribution generally also requires notarization.