MacAdmin 101: Using createOSXinstallPkg to build OS X and macOS installer packages
Providing new installs of macOS, or upgrading to newer versions, can be a challenge in many Mac environments. Apple’s OS distribution model is focused around the Mac App Store (MAS), which may not be an option for a number of managed Mac environments. The MAS-distributed OS installer also does not include the option of adding additional third-party packages to the OS installation process; it only installs the software that Apple itself includes in the OS installer.
To address these needs, an open-source tool named createOSXinstallPkg is available. createOSXinstallPkg allows you to create an Apple installer package from an “Install macOS.app”. You can use this package for the following:
- Installing OS X or macOS onto an empty drive
- Upgrading existing OS X or macOS installations to a newer version of the operating system
The advantage of using this tool is that a number of system deployment tools for Macs can deploy the installers created by this tool, allowing OS installations or upgrades to be performed by the system management tool already in use by a particular IT shop. One great thing about using this tool is that createOSXinstallPkg will create an installer package that either installs a stock copy of either OS X or macOS, or you can add additional packages to the stock OS install.
When adding packages, there are a couple of guidelines to keep in mind:
- There is about 350 megabytes of free space available in the OS installer. This is sufficient space for configuration or bootstrapping packages, but it’s not a good idea to add Microsoft Office or similar large installers.
- The limitations of the OS install environment mean that there are a number of installers that won’t install correctly.
In particular, packages that use pre-installation or post-installation scripts may fail to run properly when those packages are run as part of the OS installation process. To help work around this limitation, I’ve developed a solution which I’ll be discussing later in the post. For more details, see below the jump.
Building a stock macOS installer package using createOSXinstallPkg
- If needed, download the latest version of createOSXinstallPkg.
- Consult the createOSXinstallPkg documentation on how to create a new installer package that only installs macOS Sierra.
As an example of how I’m doing it, I’m running the following commands:
A. Change to the createOSXinstallPkg application directory
cd /path/to/createOSXinstallPkg
B. Create a stock macOS Sierra installer:
computername:createOSXinstallPkg username$ sudo ./createOSXinstallPkg --source "/Applications/Install macOS Sierra.app"
Here’s what the output of the example process above looks like:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| computername:createOSXinstallPkg username$ sudo ./createOSXinstallPkg –source "/Applications/Install macOS Sierra.app" | |
| Examining and verifying source… | |
| —————————————————————- | |
| InstallESD.dmg: /Applications/Install macOS Sierra.app/Contents/SharedSupport/InstallESD.dmg | |
| OS Version: 10.12.1 | |
| OS Build: 16B2659 | |
| —————————————————————- | |
| Output path: /Users/username/createOSXinstallPkg/InstallOSX_10.12.1_16B2659.pkg | |
| Creating package wrapper… | |
| Copying brtool into package resources… | |
| Creating MacOSXInstaller.choiceChanges… | |
| —————————————————————- | |
| Downloading and adding IncompatibleAppList pkg… | |
| Downloading http://swcdn.apple.com/content/downloads/17/04/031-83163/n8thccuwnoqetn1kyn53bheb4nb7pw3wbv/OSX_10_12_IncompatibleAppList.pkg to /Users/username/createOSXinstallPkg/InstallOSX_10.12.1_16B2659.pkg/Contents/Resources/OS X Install Data/OSX_10_12_IncompatibleAppList.pkg… | |
| Writing index.sproduct to /Users/username/createOSXinstallPkg/InstallOSX_10.12.1_16B2659.pkg/Contents/Resources/OS X Install Data/index.sproduct… | |
| —————————————————————- | |
| Copying InstallESD into package… | |
| —————————————————————- | |
| Done! Completed package at: /Users/username/createOSXinstallPkg/InstallOSX_10.12.1_16B2659.pkg | |
| computername:createOSXinstallPkg username$ |
C. Once you have your macOS installer built, you can use it as-is or use your system management tool to deploy it.
Building a modified macOS installer package using createOSXinstallPkg
createOSXinstallPkg also has options for adding third-party packages to the OS installation, but as mentioned previously, the limitations of the OS install environment mean some packages won’t install correctly. In particular, packages that use preinstall or postinstall scripts as part of their normal installation process may fail to run properly in the OS install environment.
To help work around this limitation, I’ve developed First Boot Package Install Generator.app, an application that generates installer packages that enable other packages to be installed during the Mac’s first boot following the OS installation. This solves the issue because the installers are no longer running in the OS install environment and can run any associated preinstall or postinstall scripts. For information about building a firstboot package using First Boot Package Install Generator.app, please see the link below:
https://derflounder.wordpress.com/2014/10/19/first-boot-package-install-generator-app/
Another option for building firstboot packages is Graham Gilbert’s first-boot-pkg tool, which is designed to create a flat package that will install a series of packages when a Mac boots for the first time. It has configuration options which are not available in First Boot Package Install Generator.app, so if First Boot Package Install Generator.app does not meet all of your needs, please take a look at first-boot-pkg:
https://github.com/grahamgilbert/first-boot-pkg
Once you have your third-party package(s) available, see below for how to create a new installer package that installs macOS Sierra and includes an additional third-party installer package.
- If needed, download the latest version of createOSXinstallPkg.
- Consult the createOSXinstallPkg documentation on how to create a new installer package that installs macOS Sierra and includes additional installer packages.
As an example of how I’m doing it, I’m running the following commands:
A. Change to the createOSXinstallPkg application directory
cd /path/to/createOSXinstallPkg
B. Create a macOS Sierra installer with the following options:
- Use the —pkg option to include one installer package named Sierra First Boot Package Install.pkg, which is stored in /Users/username/createOSXinstallPkg/first_boot
- Use the —output option to set the Sierra installer package’s name to be Sierra 10.12.1 Installer.pkg.
sudo ./createOSXinstallPkg --source "/Applications/Install macOS Sierra.app" --pkg "/Users/username/createOSXinstallPkg/first_boot/Sierra First Boot Package Install.pkg" --output "Sierra 10.12.1 Installer.pkg"
Here’s what the output of the example process above looks like:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| computername:createOSXinstallPkg username$ sudo ./createOSXinstallPkg –source "/Applications/Install macOS Sierra.app" –pkg "/Users/username/createOSXinstallPkg/first_boot/Sierra First Boot Package Install.pkg" –output "Sierra 10.12.1 Installer.pkg" | |
| Password: | |
| Examining and verifying source… | |
| —————————————————————- | |
| InstallESD.dmg: /Applications/Install macOS Sierra.app/Contents/SharedSupport/InstallESD.dmg | |
| OS Version: 10.12.1 | |
| OS Build: 16B2659 | |
| —————————————————————- | |
| Output path: /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg | |
| Additional packages: | |
| —————————————————————- | |
| Sierra Upgrade First Boot Package Install.pkg | |
| —————————————————————- | |
| Total additional package size: 13700 Kbytes | |
| —————————————————————- | |
| Checking available space on /Applications/Install macOS Sierra.app/Contents/SharedSupport/InstallESD.dmg… | |
| Creating package wrapper… | |
| Copying brtool into package resources… | |
| Creating MacOSXInstaller.choiceChanges… | |
| —————————————————————- | |
| Downloading and adding IncompatibleAppList pkg… | |
| Downloading http://swcdn.apple.com/content/downloads/17/04/031-83163/n8thccuwnoqetn1kyn53bheb4nb7pw3wbv/OSX_10_12_IncompatibleAppList.pkg to /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg/Contents/Resources/OS X Install Data/OSX_10_12_IncompatibleAppList.pkg… | |
| Writing index.sproduct to /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg/Contents/Resources/OS X Install Data/index.sproduct… | |
| —————————————————————- | |
| Copying InstallESD into package… | |
| Mounting /Applications/Install macOS Sierra.app/Contents/SharedSupport/InstallESD.dmg… | |
| Copying additional packages to InstallESD/Packages/: | |
| Copying flat package /Users/username/createOSXinstallPkg/first_boot/Sierra Upgrade First Boot Package Install.pkg | |
| Creating /private/tmp/tmpAFfTca/dmg.4raGx3/Packages/OSInstall.collection | |
| Unmounting /Applications/Install macOS Sierra.app/Contents/SharedSupport/InstallESD.dmg… | |
| Creating disk image at /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg/Contents/Resources/InstallESD.dmg… | |
| Preparing imaging engine… | |
| Reading Protective Master Boot Record (MBR : 0)… | |
| (CRC32 $3A2C1859: Protective Master Boot Record (MBR : 0)) | |
| Reading GPT Header (Primary GPT Header : 1)… | |
| (CRC32 $6387BDC5: GPT Header (Primary GPT Header : 1)) | |
| Reading GPT Partition Data (Primary GPT Table : 2)… | |
| (CRC32 $9034B71B: GPT Partition Data (Primary GPT Table : 2)) | |
| Reading (Apple_Free : 3)… | |
| (CRC32 $00000000: (Apple_Free : 3)) | |
| Reading EFI System Partition (C12A7328-F81F-11D2-BA4B-00A0C93EC93B : 4)… | |
| …. | |
| (CRC32 $B54B659C: EFI System Partition (C12A7328-F81F-11D2-BA4B-00A0C93EC93B : 4)) | |
| Reading disk image (Apple_HFS : 5)… | |
| ………………………………………………………………………………………….. | |
| (CRC32 $6F849562: disk image (Apple_HFS : 5)) | |
| Reading (Apple_Free : 6)… | |
| ……………………………………………………………………………………………. | |
| (CRC32 $00000000: (Apple_Free : 6)) | |
| Reading GPT Partition Data (Backup GPT Table : 7)… | |
| ……………………………………………………………………………………………. | |
| (CRC32 $9034B71B: GPT Partition Data (Backup GPT Table : 7)) | |
| Reading GPT Header (Backup GPT Header : 8)… | |
| …………………………………………………………………………………………….. | |
| (CRC32 $FC9D3E61: GPT Header (Backup GPT Header : 8)) | |
| Adding resources… | |
| …………………………………………………………………………………………….. | |
| Elapsed Time: 9m 5.775s | |
| File size: 4887626747 bytes, Checksum: CRC32 $9B8D9D5F | |
| Sectors processed: 10741912, 10281876 compressed | |
| Speed: 9.2Mbytes/sec | |
| Savings: 11.1% | |
| created: /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg/Contents/Resources/InstallESD.dmg | |
| —————————————————————- | |
| Done! Completed package at: /Users/username/createOSXinstallPkg/Sierra 10.12.1 Installer.pkg | |
| computername:createOSXinstallPkg username$ |
C. Once you have your modified macOS installer built, you can use it as-is or use your system management tool to deploy it.
Leave a Reply
Recent Comments
 | Mark P on 20 years of Der Flounder |
 | Bruce Carter on 20 years of Der Flounder |
 | JimH on Downloading installer packages… |
 | Sander on Downloading installer packages… |
 | Andreas Schenk on Downloading installer packages… |
Der Flounder 
Whats the advantage or difference between this and AutoDMG?
Thanks Rich, your post here pushed me to finally give it a try. So far so good!
If I wanted to run a script after the installation, it sounds like I would need to use your First Boot Package Install Generator but it’s not clear to me if it can accept a script. I’m looking to create an installer that will run a script to disable the AppleID and diagnotic prompts and possibly some other configurations. Can you recommend the best way to accomplish this?
Jim,
A payload-free package is the best way to run a script using an installer package. I have a tool available via the link below that can take an existing script and create a payload-free package from it:
https://github.com/rtrouton/Payload-Free-Package-Creator
I also have an existing payload-free package which runs a script to disable iCloud, Diagnostics and Siri pop-up windows. It’s available via the link below:
https://github.com/rtrouton/rtrouton_scripts/tree/master/rtrouton_scripts/disable_apple_icloud_diagnostic_and_siri_pop_ups
Greetings Rich,
Thanks for the wealth of knowledge.
If you know, or know where I can find info on hosting the “Sierra 10.12.1 Installer.pkg” output file on macOS Apache server available to download that would be amazing.
Because the pkg isn’t a flat package, my download link gives either forbidden or is trying to browse the contents of the file.
I’ve checked the suggestions on the following sites, but to no avail
https://stackoverflow.com/questions/21694974/how-to-make-pkgdot-pkg-downloadable
There was another link but has been lost in a sea of browser tabs..
I know some HTML, have no experience with PHP, found this:
https://stackoverflow.com/questions/12189599/apache-how-to-make-folder-content-downloadable-only-treat-all-files-as-downl
Any guidance or link to ‘how to’ if you have one will be immensely appreciated.
Cheers,
MB
A solution I’ve come up with is putting the createOSXinstallPkg install pkg into a flat pkg as a payload, then running a postinstall script to run the macOS installer.
Seems cumbersome, but giving the desired result.