How to Use the macOS pkgbuild Command to Create Custom Installer Packages

The Power of macOS Installers

If you have ever downloaded a piece of professional software for a Mac (like Microsoft Office or Adobe Creative Cloud), it likely came in a .pkg file. Unlike a standard macOS application bundle (.app) that you simply drag and drop into the Applications folder, a PKG file runs through the macOS Installer app.

System Administrators and developers love PKG files because they can run pre-install scripts (like checking for incompatible software), install files into protected system directories, set specific file permissions, and run post-install scripts (like launching a background daemon).

If you are managing a fleet of Macs or distributing your own software, you don’t need expensive third-party tools to create these installers. You can use the native command-line tool built right into macOS: pkgbuild.

Step 1: Preparing Your Payload

Before you run the command, you need to gather all the files you want to install into a single folder on your Mac. This is known as the “payload root.”

For example, let’s say you have a custom font (CompanyFont.ttf) and a custom screensaver (CompanyScreensaver.saver) that you want to deploy to every Mac in your office.

1. Create a folder on your Desktop named MyPayload.
2. Inside that folder, recreate the exact directory structure of where you want these files to end up on the target Mac.
   • Create a folder named Library.
   • Inside Library, create two folders: Fonts and Screen Savers.
3. Place your CompanyFont.ttf into the Fonts folder, and your CompanyScreensaver.saver into the Screen Savers folder.

Your payload folder now acts as a miniature, perfectly structured replica of the target hard drive.

Step 2: Running the pkgbuild Command

Open the Terminal (Applications > Utilities).

The basic syntax for pkgbuild requires you to specify the root folder (your payload), an identifier (a unique name for your package, written in reverse-DNS format), and the output filename.

Run the following command:

pkgbuild --root ~/Desktop/MyPayload --identifier com.yourcompany.customsetup --version 1.0 ~/Desktop/CustomSetup.pkg

When you press Enter, the tool will analyze your payload folder, compress the files, write the necessary installation metadata, and generate a CustomSetup.pkg file on your Desktop.

Step 3: Adding Scripts (Advanced)

The true power of pkgbuild lies in its ability to run scripts.

Let’s say you want to force the Mac to restart immediately after the user installs your package. You can create a simple shell script named postinstall.

1. Create a new folder on your Desktop called MyScripts.
2. Using a text editor, create a file named exactly postinstall (no extension).
3. Write the following code in the file:
   #!/bin/bash
shutdown -r now
exit 0
4. Save the file and make it executable by running: chmod +x ~/Desktop/MyScripts/postinstall

Now, rebuild your package, adding the --scripts flag to tell pkgbuild to include that folder:

pkgbuild --root ~/Desktop/MyPayload --scripts ~/Desktop/MyScripts --identifier com.yourcompany.customsetup --version 2.0 ~/Desktop/CustomSetup_v2.pkg

When a user double-clicks this new PKG file, the macOS Installer will safely copy your fonts and screensavers into the correct system Library folders, and then immediately execute your postinstall script, rebooting their machine to apply the changes.