Skip to main content
The top-level pkg key contains options for building PKG (macOS installer component package) installers.

​
Basic Example

{
  "pkg": {
    "installLocation": "/Applications",
    "allowAnywhere": true,
    "allowCurrentUserHome": true,
    "allowRootDirectory": true,
    "license": "license.txt"
  }
}

​
Configuration Options

​
Installation Settings

​
installLocation
string
default:"/Applications"
The install location. Do not use it to create per-user package./Applications would install it as expected into /Applications if the local system domain is chosen, or into $HOME/Applications if the home installation is chosen.
Mostly never you will need to change this option.
​
allowAnywhere
boolean
default:"true"
Whether can be installed at the root of any volume, including non-system volumes. Otherwise, it cannot be installed at the root of a volume.Corresponds to enable_anywhere.
​
allowCurrentUserHome
boolean
default:"true"
Whether can be installed into the current user’s home directory.A home directory installation is done as the current user (not as root), and it cannot write outside of the home directory. If the product cannot be installed in the user’s home directory and be not completely functional from user’s home directory.Corresponds to enable_currentUserHome.
​
allowRootDirectory
boolean
default:"true"
Whether can be installed into the root directory. Should usually be true unless the product can be installed only to the user’s home directory.Corresponds to enable_localSystem.

​
Installer Behavior

​
isRelocatable
boolean
default:"true"
Install bundle over previous version if moved by user?
​
isVersionChecked
boolean
default:"true"
Don’t install bundle if newer version on disk?
​
hasStrictIdentifier
boolean
default:"true"
Require identical bundle identifiers at install path?
​
overwriteAction
'upgrade' | 'update'
default:"upgrade"
Specifies how an existing version of the bundle on disk should be handled when the version in the package is installed.upgrade: The bundle in the package atomically replaces any version on disk; this has the effect of deleting old paths that no longer exist in the new version of the bundle.update: The bundle in the package overwrites the version on disk, and any files not contained in the package will be left intact; this is appropriate when you are delivering an update-only package.
Another effect of update is that the package bundle will not be installed at all if there is not already a version on disk; this allows a package to deliver an update for an app that the user might have deleted.

​
Scripts

​
scripts
string
default:"build/pkg-scripts"
The scripts directory, relative to build (build resources directory).The scripts can be in any language so long as the files are marked executable and have the appropriate shebang indicating the path to the interpreter.
Scripts are required to be executable (chmod +x file).
See Scripting in installer packages.

​
Signing and License

​
identity
string
The name of certificate to use when signing. Consider using environment variables CSC_LINK or CSC_NAME instead of specifying this option.
​
license
string
The path to EULA license file. Defaults to license.txt or eula.txt (or uppercase variants).In addition to txt, rtf and html supported (don’t forget to use target="_blank" for links).

​
Customization

​
background
object
Options for the background image for the installer.Properties:
​
background.file
string
Path to the image to use as an installer background.
​
background.alignment
string
default:"center"
Alignment of the background image.Options are: center, left, right, top, bottom, topleft, topright, bottomleft, bottomright
​
background.scaling
string
default:"tofit"
Scaling of the background image.Options are: tofit, none, proportional
​
welcome
string
The path to the welcome file. This may be used to customize the text on the Introduction page of the installer.
​
conclusion
string
The path to the conclusion file. This may be used to customize the text on the final “Summary” page of the installer.
​
mustClose
string[]
Identifies applications that must be closed before the package is installed.Corresponds to must-close.Example:
{
  "mustClose": [
    "com.example.myapp"
  ]
}

​
Advanced Options

​
extraPkgsDir
string
The extra component packages directory (relative to build resources directory) for MacOS product archive.Autoscans directory for any .pkg files and adds to productbuild command as --package-path and --package accordingly.

​
Example with Custom Scripts

Create a build/pkg-scripts directory with the following scripts:

​
preinstall

#!/bin/bash

echo "Running preinstall script"
# Close running instances
pkill -x "MyApp" || true

exit 0

​
postinstall

#!/bin/bash

echo "Running postinstall script"
# Set permissions or perform cleanup
chmod -R 755 "/Applications/MyApp.app"

exit 0
Make them executable: 
chmod +x build/pkg-scripts/preinstall
chmod +x build/pkg-scripts/postinstall

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us