Skip to content

Legacy 6. Upgrading or reinstalling macOS

Graham Pugh edited this page Jan 19, 2023 · 2 revisions

Use the --reinstall parameter to initiate the reinstallation of the system volume without erasing it. This is commonly used for upgrading to a new version of macOS, but can also be used to reinstall the same version when troubleshooting, similar to reinstalling macOS via the Recovery Partition.

If the --reinstall parameter is used alone, erase-install.sh will check for a cached installer in the working directory and in /Applications. If it finds one, it will use this installer for the reinstall process described below. If it does not find one, it will download the latest compatible installer for the system on which the script is running. This is also compatible with the --fetch-full-installer and --pkg parameters described elsewhere.

The reinstall process calls startosinstall (startosinstall is a command-line tool included in the macOS installer app).

Apple Silicon Mac

The startosinstall command requires user credentials to be supplied when run on an Apple Silicon Mac. When running this script on an Apple Silicon Mac, the user will be prompted to enter a username and password via osascript dialogs. The script checks that the user exists, is a "Volume Owner", and that the password is correct.

osascript-accountname osascript-password.png

--current-user

You can reduce the number of dialogs by adding the --current-user parameter to pre-select the logged-in user.

--user

You can reduce the number of dialogs by adding the --user parameter to pre-select a user.

Available drive space

macOS Big Sur requires 45 GB spare drive space to perform an upgrade using startosinstall. If this space is not available, the user is informed via an osascript dialog and the script ends.

osascript-min-drive-space

--min-drive-space NN

This figure is lower on older versions of macOS. You can override the default minimum space required for startosinstall to run with the --min-drive-space=NN or --min-drive-space NN parameter, where NN is a value in GB. Example --min-drive-space 30.

User dialog during download

If the system has the jamfHelper tool installed (jamfHelper is installed when enrolling into Jamf Pro), a notification message is displayed during the download process. Once the download is complete, the window is closed and the script moves on to the reinstall process described below.

jamfhelper-download

--depnotify

If DEPNotify is installed, and the --depnotify parameter is used, a notification message is displayed using DEPNotify.

depnotify-download

User dialog during preparation for reinstallation

Once the reinstall process is ready to begin, another dialog is launched. On Jamf Pro enrolled Macs, this is a full-screen jamfHelper window:

jamfhelper-reinstall

For Jamf users testing the script, you can add the --no-fs parameter to switch to a utility window instead of the full screen window. Or, you can use the --no-jamfhelper to switch to the osascript dialogs.

Cmd+Q will quit any jamfHelper dialog.

If jamfHelper is not available, an osascript dialog is shown instead:

osascript-reinstall

If the --depnotify parameter is used, and DEPNotify is installed on the client, a full-screen DEPNotify window is used:

depnotify-reinstall-fs

Ctrl+Cmd+X will quit the DEP Notify dialog.

Additional options

There are various additional parameters that can customise the reinstall workflow.

Choosing a specific version of macOS to install

You can specify a specific OS, version or Build ID to download using the --os, --version or --build parameters. You can keep to the same OS as the current system using the --sameos parameter. You can keep to the same Build ID using the --samebuild parameter. See the section on downloading a specific version for more details of how these parameters work.

--rebootdelay

Recent versions of macOS have a long preparation phase followed by a short post-restart phase when reinstalling/upgrading. You can minimise the disruption to a user by allowing them to continue to work during the preparation phase. To do this, use the --rebootdelay option to allow a period of time after the preparation has completed for the user to save their work. If you specify a reboot delay of more than 10 seconds, the dialog window during the preparation phase is not full screen. A new dialog is shown when the preparation is complete.

--cleanup-after-use

If the --cleanup-after-use option is used, the script cleans up after itself after an upgrade/reinstallation is made. This is achieved by setting a LaunchDaemon that wipes erase-install's working directory upon startup.

--check-power

If the --check-power option is used, the script will check if the computer is connected to AC power. If it isn't, it will wait for a default of 60 seconds for power to be added, and otherwise fail.

The default time to wait can be altered by setting the --power-wait-limit option, e.g. --power-wait-limit 180 for 3 minutes.

This is the dialog if jamfHelper is available:

jamfhelper-check-power

This is the osascript dialog:

osascript-check-power

--test-run

For testing out the script, you can add the --test-run parameter. This runs through the entire workflow up to but not including the startosinstall command. Instead, a sleep 120 command is run.