The Deployment Problem
In enterprise macOS management, you frequently need to distribute custom software or configuration scripts to employee laptops.
For example, you might have written a Bash script that installs a specific corporate font, sets the desktop wallpaper to the company logo, and injects a custom Wi-Fi profile. If you hand that raw .sh script to an employee, they won’t know what to do with it, and macOS Gatekeeper will likely block it from executing anyway.
Apple provides a native terminal utility called pkgbuild that allows administrators to take raw scripts, files, and applications, and package them into a professional, double-clickable .pkg installer file. This file can then be silently pushed via an MDM (like Jamf) or sent directly to end-users.
1. The Basic Payload Installer
Suppose you have a folder on your Desktop containing three custom corporate fonts, and you want them installed directly into the /Library/Fonts directory on every employee’s Mac.
You use pkgbuild to define the source folder (the “root”) and the intended destination on the target computer (the “install location”).
pkgbuild --root ~/Desktop/MyFonts --install-location /Library/Fonts ~/Desktop/CorporateFonts.pkgHow it works:
The command grabs everything inside the MyFonts folder, compresses it, and wraps it in Apple’s installer framework. When a user double-clicks CorporateFonts.pkg, they will see the standard macOS installation wizard (asking for their admin password). Upon clicking “Install,” the fonts will be silently dumped exactly into /Library/Fonts.
2. The “Payload-Free” Script Installer
Sometimes you don’t actually have any files to install; you just want to run a script. For instance, you want to run a script that permanently disables the macOS Guest Account.
You can create a “payload-free” package. Instead of providing a root folder of files, you provide a Scripts directory.
- Create an empty folder called
MyScripts. - Inside that folder, create your bash script and name it exactly
postinstall(with no extension). - Ensure the script is executable (
chmod +x postinstall).
Now, run the pkgbuild command using the --nopayload flag.
pkgbuild --nopayload --scripts ~/Desktop/MyScripts --identifier com.corp.disableguest ~/Desktop/DisableGuest.pkgWhen the user runs this installer, no files are copied to their hard drive. The macOS Installer framework simply extracts the postinstall script, executes it with root privileges in the background, and reports a successful installation.
3. Identifying Your Packages
Notice the --identifier com.corp.disableguest flag in the previous command.
Apple requires every package to have a unique, reverse-DNS identifier. When the package is installed, macOS logs this identifier in its internal receipts database (/var/db/receipts/).
This allows MDM systems to query the Mac later and ask, “Did the DisableGuest package install successfully on Tuesday?” by checking the receipts database for that exact identifier.
4. Signing the Installer (Avoiding Gatekeeper)
If you create a .pkg file and email it to an employee, macOS Gatekeeper will block it, throwing an error that says, “This package cannot be opened because it is from an unidentified developer.”
To bypass this, you must cryptographically sign the package using an Apple Developer Certificate provided by your company.
You simply add the --sign flag to your command.
pkgbuild --root ~/Desktop/MyFonts --install-location /Library/Fonts --sign "Developer ID Installer: Your Company Name (TEAMID)" ~/Desktop/CorporateFonts_Signed.pkgThe resulting package will bypass Gatekeeper smoothly and display a verified lock icon in the top right corner of the installation wizard.
Conclusion
The pkgbuild command is the engine behind macOS software distribution. By allowing administrators to wrap raw files, complex bash scripts, and cryptographic signatures into standard Apple installer packages, it enables seamless, automated configuration of enterprise Mac fleets.