FAQs
I'll try to assemble some of the most common questions relating to this tool here.
No. Apple does not provide an in-place downgrade option that can be run from the system. You have to use an external bootable installer, internet recovery, or DFU mode on Apple Silicon Mac to achieve this.
Run the script with --help to see all options.
/Library/Management/erase-install/erase-install.sh --help
A common question goes something like:
11.6.6 was just released. I want to upgrade a Mac running 10.14.6 to 11.6.6. But when I run
erase-install.sh --reinstall --os 11the Mac is upgraded to 11.6.1. I also triederase-install.sh --reinstall --version 11.6.6but still did not get 11.6.1. Why not?
Apple publish different software catalogs for different system OS versions. For example, Mojave has a different catalog to Catalina. Not all releases are published to all catalogs. We don't know why Apple omit some installers from some catalogs. However, it may be that they don't publish them because they have not tested the upgrade from that system OS version.
You can check which installers are available on the system you are running by running erase-install.sh --list. This will show you the installers available in the default catalog for that OS version, and also which are compatible with your current system.
If you want to try to obtain an installer not available in the default catalog for a particular version, you can override it with the --catalog option. For example, erase-install.sh --reinstall --os 11 --catalog 11 would get the latest available macOS 11 installer from the default Big Sur catalog. You can of course check which installers are available in that catalog with erase-install.sh --list --catalog 11. I would advise that you test out this workflow on a test system before rolling this out to end user computers, because we have seen installers that will download but won't successfully install on the older OSs.
The script outputs to stdout. Everything is also outputted to /Library/Management/erase-install/log/erase-install.log. This file is of course removed if you are running the --erase workflow. It is also cleared if you use the --cleanup-after-use option.
I've tried to make the help page as complete as I can:
/Library/Management/erase-install/erase-install.sh --help
This tool requires a good network connection since you are downloading a full macOS installer which are over 10 GB in size. Poor Internet connection with interruptions may result in failure. This is generally visible in the output of curl. For example, if you see something like the following in your output or the log, then your connection to Apple's Software Update servers has failed during the download:
curl: (18) transfer closed with 3739576598 bytes remaining to read
Could not replicate https://swcdn.apple.com/content/downloads/06/34/002-42435-A_MA7OBDUK86/6xzypeod1xebasc92qkw2iv44e1j9pv09f/InstallAssistant.pkg: Command '['/usr/bin/curl', '-fL', '--create-dirs', '-o', '/Library/Management/erase-install/content/downloads/06/34/002-42435-A_MA7OBDUK86/6xzypeod1xebasc92qkw2iv44e1j9pv09f/InstallAssistant.pkg', '-w', '%{http_code}', '--compressed', 'https://swcdn.apple.com/content/downloads/06/34/002-42435-A_MA7OBDUK86/6xzypeod1xebasc92qkw2iv44e1j9pv09f/InstallAssistant.pkg']' returned non-zero exit status 18.
Are you running any security software? There have been reports that tools such as CrowdStrike and Microsoft Defender are blocking the construction of the installer from the downloaded components. If this happens, you could try the --fetch-full-installer option which uses Apple's softwareupdate command to obtain the installer.
Some users have also seen the following error during the run of the startosinstall command on Apple Silicon Mac:
Requested user is not an administrator. Allow the user to administer this computer in System Preferences to continue.
From what we can tell, this occurs when the account being used has not been made an admin in a way that is satisfactory to startosinstall. We are not 100% clear on what startosinstall expects, but for example, it is not enough to create an account with the PrimaryGroupID of 80 to make it a local admin. The account must still have the admin group added to it, e.g. dseditgroup -o edit -a <username> -t user admin. Accounts that were elevated to admin using a Jamf Policy or Privileges.app may also fail, though I have not seen any evidence of the latter lately.
Please note that the specified account does not need to be an admin. For the --reinstall option, the account just needs to be a Volume Owner, and for the --erase option we elevate the account to admin to make it work.
Downloads using the default method are not stored in Content Caching. I've had opposing reports that the installers obtained with the --fetch-full-installer option are cached in a Content Caching server, or are not! I have not been able to test this myself.
Can you change the name of this script as it is confusing when we want to use it for upgrading macOS, not erasing it?
This is a legacy of the very first version of this script, which I released to take advantage of the then brand new --eraseinstall option of startosinstall, and combine it with installinstallmacos.py. The functionality of the script has grown considerably since then, particularly in relation to using it for upgrading macOS. Unfortunately the script is now too well known to change the name.
If it overly concerns you, you can of course change the name yourself. I have written the script so that the logs and output will show whatever the name of the script is.
The policy can never finish, because the startosinstall command is a part of the script, but it restarts the computer itself. So the policy never completes.
To ensure that the new OS is logged to Jamf, I recommend setting an Update Inventory policy to run at startup.
I'm aware of a few other tools and scripts that do a similar job to this script, so I'll cover them here:
S.U.P.E.R.M.A.N. or super is a tool for updating or upgrading macOS. It can use MDM commands to issue software updates when linked to your MDM provider (primarily Jamf) using an API account, or it can attempt to use the softwareupdate command if MDM is not available. As with erase-install, it can also use mist-cli as a fallback to upgrade a machine if MDM or delta updates are not available. So it can do everything that erase-install can do (except erasing a Mac) and more, since erase-install only deals with full installer apps, but does require more work to setup.
installinstallmacos.py is a script for downloading macOS installers. It does not have a non-interactive mode, nor does it check for compatibility with your current system.
erase-install.sh can be run with the --fetch-full-installer option, in which case it will use macOS' built-in softwareupdate --fetch-full-installer function to obtain the installer, and then optionally use it to upgrade or erase and reinstall your Mac.
Armin Briegel's fetch-installer-pkg is a variant of Greg Neagle's installinstallmacos.py, designed to obtain an installer package rather than an installer app. It works for macOS 11 and newer. As with installinstallmacos.py, it does not have a non-interactive mode, nor does it check for compatibility with your current system.
Armin Briegel's DownloadFullInstaller application is a Swift-based implementation of his fetch-installer-pkg script. As such, it is just a GUI method of obtaining the installer and cannot be used as part of an automation workflow.
Greg Neagle's getmacosipsws.py can be used to get IPSW files for use with Apple Configurator 2, in order to reinstall macOS on Apple Silicon Mac computers using DFU mode. DFU-mode restores are a very fast method of reinstalling macOS, including the ability to downgrade macOS. There is no "single-click" workflow for reinstallation using these files, however.
Nindi Gill's Mist is a Swift-based application for obtaining installers. This is another tool that uses the same software catalogs as installinstallmacos.py and fetch-installer-pkg, and can download either the installer app, pkg, or IPSW file, depending on the options used. mist-cli is a command-line version. erase-install.sh version 28 and newer uses mist-cli as its back-end for downloading installers.
macOSUpgrade.sh is a script that provides similar workflows to the upgrade and erase-install options of erase-install.sh, but it does not include any functionality for obtaining the installer in the first place.
I have attempted to include all the options that macOSUpgrade has into erase-install.sh, such as disk space checks and a "confirm" option. Additionally, I do not believe that macOSUpgrade has yet been updated so that it will work on Apple Silicon Mac computers.
If you have found a feature in macOSUpgrade that you like and is not present in erase-install.sh, let me know and I'll consider adding it.