Skip to main content

Reinstall a clean macOS with one button

With the macOS High Sierra 10.13.4 update, Mac admins got a new tool for their toolbox (or a new toy for their toybox, however you like to look at it). When one of my co-workers pointed me to it in the Apple beta, I had the same reaction Homer Simpson has to doughnuts. And every one of my customers has loved it.

We now have a new argument for the startosinstall command line tool that comes bundled with the Install macOS High installer.


It does exactly what the name implies. We can use it to erase a Mac and reinstall macOS. It doesn’t require an external drive nor something like NetBoot. It doesn’t require booting to the Recovery HD.

So long as the installer app is on the computer, we have everything we need.

Why is this better than imaging?
Apple is killing the concept of imaging a Mac. Why?

A lot of what makes macOS work with Mac hardware is now based on firmware updates. Those firmware updates are installed only by the Apple installers and don’t get applied until the installer application runs to prepare the hardware.

When we use something like AutoDMG to upgrade a Mac from Sierra to High Sierra, for example, the image we’re deploying doesn’t contain the firmware updates. That can lead to stability problems and unexpected results.

Yes, running a macOS installer takes several times longer than block-copying an image to a computer, but the tradeoff is better security and performance. This is our new world.

How do we use --eraseinstall?
As I mentioned earlier, the --eraseinstall argument is part of the startosinstall command line tool. Download macOS High Sierra from the Mac App Store. It’ll download into the Applications folder. Right-click or Control-click the Install macOS High installer and choose Show Package Contents > Contents > Resources > startosinstall. Drag this file into a Terminal window and add --usage to the end.

 "/Applications/Install macOS High" ‑‑usage

This lists several arguments (each beginning with double-dashes) and explains what each does. Some are required. Some are optional. Only trial and error helps you determine which are required and which are optional.

After a little testing, this command does the trick:

 "/Applications/Install macOS High" ‑‑eraseinstall
‑‑newvolumename "Macintosh HD" --agreetolicense

The ‑‑eraseinstall argument is required. That’s what makes it work. The ‑‑newvolumename argument, though is optional. I like this because it renames the hard drive back to the default “Macintosh HD” in case a user has changed it. And the ‑‑agreetolicense argument is semi-required. Without it, you’ll be prompted to interactively view and agree to the license. With it, the command runs without further prompting.

The button
Now, let’s put this in Self Service. I suggest a two-policy approach.

The first policy should place the Install macOS High installer into the Applications folder (or any other folder) on your target machines. For this we need a few things.

1. Use Composer to create a new package. It should simply drop the installer app into your preferred location on your target Macs. Build the package as a PKG. (Remember, this new package doesn’t install High Sierra. It only places the High Sierra installer onto the computers.)

2. Upload your new package to your distribution point using Jamf Admin or the Jamf Pro web console if your Master distribution point is a cloud server.

3. Now, let’s make a Smart Computer Group for scoping. It should identify whether the Install macOS High installer is on the target Macs and it should verify it’s at the installer for macOS 10.13.4 or later. Use “13.4” not “10.13.4”. The installer’s version doesn’t exactly match the macOS version.

4. Next, make a policy to run the package and deliver the installer silently onto the target Macs ahead of time.

Why silently? Because the end user doesn’t need to know the app is getting placed on his or her machine. That part’s not important. Also, we want this 5 GB file on the Mac before we click the button to run the ‑‑eraseinstall command. This avoids the user having to wait 10 or more minutes for the package to download and gives the appearance that reinstalling macOS begins almost instantly.

Now, let’s create the second policy that performs the magic.

5. The final policy contains the startosinstall command and we’ll place it in Self Service to create that one-button reinstall.

Because we’re putting this policy into Self Service, we need to append an ampersand ( & ) to the end of the line to allow Self Service to quit when the command is ready to restart the computer. The complete command is below.

Enable this policy for Self Service, name the button something like “Erase & Install” and add an icon. Be sure to include a warning in the description alerting the user that by continuing, all data will be irrecoverably erased. Consider using markdown to add emphasis to your message.

How it works
After a user or technician clicks the Erase & Install button, the command only takes a few seconds to run and should restart the Mac within 30 seconds. It works by creating a new partition, copying the installer to the new partition, making it bootable and restarting the Mac. After restarting, the installer simply deletes the old partition with all its data, creates a new partition and installs a fresh macOS.

It takes the same amount of time to re-install macOS as if booting from an external drive and significantly less time than booting to the Recovery HD and running macOS Recovery, which downloads a fresh installer at that moment. Consider keeping a copy of the Install macOS High installer on your managed Macs all the time as a means of quickly erasing and re-installing the operating system on demand.

The ‑‑eraseinstall argument does have one caveat. It only works with APFS volumes. That means you can erase and install an existing macOS High Sierra Mac (10.13) that’s already been reformatted to APFS, but you cannot use it to erase and install a macOS Sierra (10.12) or earlier Mac. However, the startosinstall command does support upgrading macOS Sierra and earlier Macs to macOS High Sierra. Upgrading automatically converts HFS+ formatted SSD and flash-based drives to APFS. That command is:

 "/Applications/Install macOS High" ‑‑applicationpath "/Applications/Install macOS High" ‑‑agreetolicense &

Mmm... donuts.