Reinstall macOS Catalina with one button
Apple introduced the ability to erase and cleanly install the Mac operating system in macOS High Sierra 10.13.4 using a one-line command called startosinstall. Two years later, they continue to improve on this valuable tool for Mac admins.
During our recent webinar Reinstall a Clean macOS with One Button, I discussed these improvements and offered advice for constructing a workflow for Mac admins to use in their environments. Here, I’ll recap the webinar and attempt to answer questions from our audience.
A brief history
Every Mac OS installer app since OS X El Capitan 10.11 has included the startosinstall command line tool in its app bundle. This tool enabled Mac admins to script installing the Mac OS, allowing them to deploy upgrades to their fleets through management tools like Jamf Pro.
macOS High Sierra 10.13.4 included the new option --eraseinstall to the startosinstall tool, enabling admins to not only update or upgrade existing Macs, but completely erase them and cleanly reinstall the macOS. It was a gamechanger because they could now refresh Macs in the field without needing additional equipment like bootable thumb drives. All management settings, applications, user accounts and user data were erased.
Now, Apple has expanded functionality in macOS Catalina 10.15 by adding the --forcequitapps option to startosinstall to prevent running apps from interfering with the installation process as well as the --fetch-full-installer to the softwareupdate command for downloading and installing macOS updates.option
Let’s see how we can put all this together to reinstall macOS Catalina with one button.
Downloading a new macOS installer
The Install macOS Catalina app appears in the App Store on Macs, but when downloaded on a Mac already running Catalina, it hands off the download to Software Update in System Preferences. Downloading a new OS installer is now handled by the same mechanism as getting Safari, security and other updates for the operating system.
The command line equivalent to Software Update is softwareupdate and it too supports downloading not only Catalina but also Mojave and High Sierra installers, which are no longer available in the App Store.
To manually download the latest full 8 GB Install macOS Catalina app, open the Terminal application found in Applications > Utilities and run the softwareupdate command with the new option. This requires you be logged in with administrator privileges. (The backslash at the end of a line simply means it’s wrapping to the next line. Any time you see this, you can omit the slash and write the entire command on one line.)
sudo /usr/sbin/softwareupdate --fetch-full-installer
Terminal will show the progress as the app is downloading and installing. “Installing” in this sense is the same as installing any other app from the App Store. The Install macOS Catalina app is downloading into the Applications folder — it’s not actually going to run the installer.
It should look something like this in the Terminal window:
sudo softwareupdate --fetch-full-installer Downloading and installing (null) installer Installing: 51.0%|
Downloading the installer app using Terminal takes about the same time as downloading it through Software Update.
To retrieve an earlier macOS version, add the --full-installer-version option followed by the macOS version number. This command gets the latest Mojave installer.
sudo /usr/sbin/softwareupdate \ --fetch-full-installer \ --full-installer-version 10.14.6
Identifying Macs eligible to erase and install
Before running startosinstall to erase and install our Macs, we need to first identify which ones meet Apple’s system requirements.
- OS X 10.9 or later
- 4GB of memory
- 12.5GB of available storage for OS X El Capitan 10.11.5 or later (I like to double that for breathing room)
- MacBook (Early 2015 or newer)
- MacBook Air (Mid 2012 or newer)
- MacBook Pro (Mid 2012 or newer)
- Mac mini (Late 2012 or newer)
- iMac (Late 2012 or newer)
- iMac Pro (2017)
- Mac Pro (Late 2013 or newer)
To do this, we’ll create a new Smart Computer Group and name it “macOS Catalina Compatible Macs” and add the following criteria:
Operating System Version: greater than or equal to 10.9 and Total RAM MB more than 4095 and Boot Drive Available MB more than 25600 and Model Identifier matches (see regex below)
We need to use the model identifier of Macs to pinpoint the exact models Apple says are eligible for Catalina. That’s nearly 60 models. Rather than bloat our Smart Computer Group with 60 more lines of criteria, we can use a regular expression (or regex) to do that. Regex lets us create a pattern that can match certain strings of characters such as model identifiers. This one line of text will match all the eligible models including the new 16-inch MacBook Pro released this month. Copy and paste it in the value field for the Model Identifier criterion in the above Smart Computer Group.
After saving, be sure to click the View button to verify the group is working as expected.
While we’re at it, create a second Smart Computer Group named “Install macOS Catalina App Cached” and add the following criteria:
Application Title is Install macOS Catalina.app and Application Version like 15.1
This will help us identify Macs that have the Catalina installer app already downloaded to prevent Jamf Pro from downloading it again. Be sure to get the current version of the installer app by selecting it and choosing File > Get Info.
Deploying the macOS Catalina installer
We need to get the Install macOS Catalina app to our target machines identified by our “macOS Catalina Compatible Macs” Smart Computer Group.
If our target Macs are already running Catalina, the most efficient way to get the installer to them is to tell them to download it themselves. Otherwise, we’ll need to use a packaging tool like Composer to package the installer and deploy it that way. (Jamf Pro customers will find Composer after logging in to Jamf Nation and viewing the My Assets area. Click the first big Download button.)
Create a new policy in Jamf Pro named “Cache Install macOS Catalina.app”. In this context, “cache” means simply to put it on the target machines in the Applications folder. We’re not running the installer yet. Complete the following payloads and scope in the policy.
- Display name: Cache Install macOS Catalina.app
- Trigger: Recurring Check-In
- Execution Frequency: Ongoing
- Update Inventory: Enabled
Files and Processes
- Execute Command: /usr/sbin/softwareupdate --fetch-full-installer
- Targets: macOS Catalina Compatible Macs (Smart Computer Group)
- Exclusions: Install macOS Catalina App Cached (Smart Computer Group)
When viewing the policy in the Policies list, it should look like this:
To deploy the Catalina installer to a Mac running macOS Mojave or earlier, use Composer to create a package that places the installer app into the Applications folder and then build the package as a PKG. Upload this to your Jamf Pro distribution point.
Use the same policy settings above but replace the Files and Processes payload with the Packages payload and add the Catalina package from Composer.
When Macs next check in (every 15 minutes by default), they will silently download and cache the installer without interrupting the end users. Our scoping ensures the installer only downloads if it doesn’t exist. That takes care of getting the Install macOS Catalina app deployed to our targeted Macs. Next, we’ll put the startosinstall command into Self Service.
Building our command
As I mentioned earlier, the --eraseinstall option is part of the startosinstall command line tool found inside the Install macOS Catalina app bundle. To find the command line tool, right-click or Control-click the Install macOS Catalina.app file and choose Show Package Contents > Contents > Resources. Locate and drag the startosinstall file into a Terminal window and add --usage to the end.
'/Applications/Install macOS Catalina.app/Contents/Resources/startosinstall' ‑‑usage
This lists several arguments (each beginning with double-dashes) and explains what each does. We want to use the following:
- --eraseinstall — the option that does the magic
- --agreetolicense — required to fully automate the process
- --forcequitapps — prevents running apps from hampering installation
- --newvolumename — optional, names or renames the Macintosh HD
Putting the entire one-line command together, it looks like this:
'/Applications/Install macOS Catalina.app/Contents/Resources/startosinstall' ‑‑eraseinstall --agreetolicense --forcequitapps ‑‑newvolumename 'Macintosh HD'
How does it work?
When we copy the installer app to our target Macs and run the startosinstall command with the above options, it quickly takes available free space on the Mac and carves out a temporary partition. After partitioning, the command copies the Install macOS Catalina app to the temporary partition, makes it the bootable volume and restarts the Mac.
Within a few minutes after clicking the Erase & Install button, the Mac should reboot and begin the installation.
Then from the temporary partition, the installer runs and deletes the primary partition. This effectively wipes all data from the partition. Now, it installs a fresh macOS Catalina on the primary partition, makes that bootable and restarts the Mac again. All that remains is to delete the temporary partition and the Mac is ready.
Creating the button
Now, let’s put our startosinstall command into a policy and make it available in Self Service.
Our first policy above places the Install macOS Catalina app on our target Macs. When that’s successful, our “Install macOS Catalina App Cached” Smart Computer Group should now list Macs ready to erase and install.
Create a new Policy in Jamf Pro named “Erase and Install macOS Catalina”. Complete the following payloads and scope.
- Display name: Erase and Install macOS Catalina
- Trigger: None (enable Self Service instead)
- Execution Frequency: Ongoing
Files and Processes
- Execute command: '/Applications/Install macOS Catalina.app/Contents/Resources/startosinstall' ‑‑eraseinstall --agreetolicense --forcequitapps ‑‑newvolumename 'Macintosh HD'
- Targets: Install macOS Catalina App Cached (Smart Computer Group)
- Button names: Erase & Install
- Description: Warning — Your Mac is about to be fully erased and macOS re-installed. Before proceeding, copy all important files and user data to another computer or backup system. After your Mac is erased, you cannot recover deleted data. (Consider using markdown to add emphasis to your message. See the example Self Service picture farther down.)
- Ensure that users view the description: Enabled
Add a button icon, assign categories and save the policy. When viewing the policy in the Policies list, it should look like this:
Clicking the button
After opening Self Service on one of the target Macs and clicking the Erase & Install button, end users should see the warning before proceeding.
Within a few minutes after clicking the Erase & Install button, the Mac should reboot and begin the installation.
In about 10-15 minutes, the Mac will complete installation, restart and display the Mac Setup Assistant.
Upgrading instead of erasing
With one simple change, this entire workflow can instead upgrade a Mac to macOS Catalina from an OS X 10.9 or later operating system preserving applications, data and user settings. Or it can re-install Catalina over an existing Catalina operating system. Installing the same version of macOS can sometimes repair corrupted installations.
Edit the “Erase and Install macOS Catalina” policy or clone it to make a new one and rename it to “Upgrade to macOS Catalina." Then adjust the Execute Command field in the Files and Processes payload to omit the --eraseinstall and --newvolumename options.
'/Applications/Install macOS Catalina.app/Contents/Resources/startosinstall' --agreetolicense --forcequitapps
Frequently asked questions
Q: Can I use the startosinstall to downgrade a Mac to an earlier version of macOS?
A: No, only installing the same or upgrading to a newer macOS is supported.
Q: Can I use startosinstall on a FileVault 2 enabled Mac?
A: Yes! If using the --eraseinstall option, it will delete the primary partition whether it’s encrypted or not. When used to upgrade an existing operating system to a newer one, the disk is already unlocked, and the installer will perform authenticated reboots as needed to work with FileVault-enabled volumes.
Q: Can I set the computer name or perform other actions like enabling Remote Management using this workflow?
A: No, the computer name is set during the Setup Assistant, which comes later. Use a script or policy to rename Macs after they’re enrolled into Jamf Pro. Remote Management must be enabled using an MDM command sent from Jamf Pro.
Q: When using the --installpackage option of startosinstall, can I download the package from Jamf Pro?
A: Yes, but it must be placed in a location of your choosing on the Mac before running the startosinstall command and the command must provide the path to the package.
Q: Can I install a QuickAdd package using the --installpackage option?
A: Yes! Installing a QuickAdd package using startosinstall will enroll a Mac into Jamf Pro before completing the Setup Assistant. However, this will not enable User Approved MDM (UAMDM). A user sitting in front of the Mac must manually approve the MDM profile.
Q: How many packages can I install using the --installpackage option?
A: This option supports multiple installers, but Apple has published no maximum limit.
Q: How do I prevent non-authorized users from accessing the Erase & Install policy in Self Service?
A: Scope the policy to users or a user group and allow them to authenticate to Self Service. Only scoped users should then see the policy.
Q: Can I use the --fetch-full-installer option with macOS Mojave or earlier?
A: No, this is a macOS Catalina-only feature.
Q: Does Jamf Now support this workflow?
A: No, Jamf Now’s feature set does not include all the necessary support needed for this workflow.
Q: Can I use Volume Purchasing to buy licenses for Catalina and deploy the app that way?
A: Using Volume Purchasing to deploy the Install macOS Catalina app has in the past only downloaded a truncated stub installer not the complete installer. However, invoking the startosinstall command does trigger the download for the rest of the installer. That means the Mac must be connected to the Internet and the download will greatly extend the time to erase and install. Also, the macOS may unexpectedly alert the user to run the installer. This method should only be used for unattended lab Macs, if at all.
Q: Wouldn’t it be easier and faster to create USB installer disks to erase and install Catalina?
A: Not necessarily. T2-enabled Macs would first need to be booted to the Recovery HD and security lowered to allow booting from external media. Also, erasing the disk before installing a clean operating system requires an additional manual step. To save time and preserve security, follow this erase and install workflow instead.
Q: What versions of Jamf Pro support this workflow?
A: All Jamf Pro environments should support this workflow. The features used here have been available for several years.
Q: Will the --fetch-full-installer option allow me to download High Sierra and earlier versions?
A: This option supports downloading both macOS Mojave 10.14.6 and macOS High Sierra 10.13.6. To download earlier installers, refer to Apple’s installer page.
Q: Does this workflow require DEP?
A: No. For easier deployment to a fleet of Macs, use a management server like Jamf Pro, but this has no dependency on Automated Device Enrollment technologies.
Q: Does this workflow require an Internet connection?
A: For upgrades from one major macOS version to another (e.g. Mojave to Catalina), the Mac must be connected to the Internet to download necessary firmware updates. Reinstalling the same operating system version may not necessarily require an Internet connection but is still recommended.
Q: Does it matter that I build my Catalina deployment package in Composer as a PKG or DMG?
A: For deployment by Jamf Pro, no, it doesn’t matter. Jamf Pro will treat both the same. For deployment by another management tool, the better practice is to build as a PKG.
Q: Do I still need to go through the Apple Setup Assistant on each of my Macs?
A: Yes, this workflow cannot automate or bypass the Setup Assistant.
Q: Can I speed up the download process?
A: When using the softwareupdate command to download the Catalina installer, enabling the Content Caching service on a robust Mac on the network can reduce download times by 50 percent or more.
Q: The softwareupate command acts like it’s downloading my installer, but it’s always the same old installer. What’s happening?
A: If the Finder knows of another installer either on the Macintosh HD or an external drive, it will find that and attempt to use it. Be sure to delete all old installers and empty the Trash to ensure a new copy is downloaded.
For further discussion, please post on Jamf Nation.