erase-install drives macOS reinstalls from the system volume

Reinstalling macOS from the installer already on disk

The problem erase-install addresses is not downloading a macOS installer, which Apple tooling can already do. It is what comes after the download: getting that installer to run a full reinstall on the machine, unattended, in a way that fits an administrator's deployment pipeline.

The script works from the system volume. It calls startosinstall, a resource binary built into macOS installer applications since version 10.12.4, and the erase behaviour comes from the --eraseinstall option added in macOS 10.13.4 for computers with an APFS system volume. The project states the scope directly: it can be used to download, reinstall, upgrade, or erase macOS.

That makes it a Mac administration tool rather than a consumer utility. The original design target was Macs enrolled into Jamf Pro, and the project now also carries options for other management systems or no management system at all. The warning at the top of the documentation is blunt about the consequence: this is a self-destruct script, and the instructions say not to try it out on your own device.

Three branches mapped to three eras of macOS

The repository is split across branches that correspond to macOS generations, and choosing the wrong one is the first thing that will bite you.

The default main branch carries the latest code commit of the production track, which the documentation defines as versions 28.0 and newer, and pull requests are meant to go there. The release branch corresponds to the current latest release. The legacy branch holds the latest code commit of the legacy track, representing versions up to 27.x, and it exists for people who need the script on macOS 10.15 or older.

This is the project's version compatibility mechanism. There is no runtime check in the documentation that tells you which branch suits a given Mac, so the branch decision has to be made by whoever administers the fleet, based on the OS versions in front of them. Because the legacy track is the only path for 10.15 machines, an organisation that still supports those systems has to keep a second branch in its workflow, and the two tracks will not always carry the same feature set.

Two routes for getting the installer application

The script needs a macOS Installer application on the client before it can reinstall anything, and there are two documented ways to obtain one.

The primary route goes through mist-cli, a script developed by Nindi Gill, which downloads a macOS Installer application directly from Apple to the client. The minimum required version for that path is macOS 10.15.

The second route uses Apple's own command line tooling on Macs running macOS 11 or greater:

softwareupdate --fetch-full-installer

The macOS 11 requirement exists because the script uses the --list-full-installers option to find valid builds, and that option is what tells it which builds can actually be fetched. The two routes therefore differ in more than preference. The mist-cli path works on 10.15, while the softwareupdate path is limited to 11 and newer, which lines up with the point where the legacy track hands over to the production track.

Neither route is self-contained in the sense of needing no network. A deployment that relies on this script still depends on Apple being reachable at the moment the installer is pulled, and the documentation does not describe behaviour for a machine that is offline or on a slow link at that point.

swiftDialog supplies the user-facing part

A reinstall that wipes the disk needs to tell somebody what is about to happen and collect what it needs. erase-install handles that with swiftDialog, and the minimum required version for swiftDialog is macOS 11.

That single constraint shapes the deployment picture more than it first appears. swiftDialog is used for providing dialogues to users, so the dialogue driven flow belongs to macOS 11 and newer, which is also where the production track begins. The script also has a separate file in the repository, set-credentials.sh, which points to a workflow where credentials are passed to the process before it runs, consistent with a tool that installs macOS unattended on hardware it does not own.

The important caveat for a first-time reader is that the repository's own documentation is not complete. The README carries a single instruction for people who want the details: please refer to the Wiki for detailed documentation, at the project wiki. Option names, the full set of flags, and the exact dialog flows are not enumerated in the README, so anyone planning an unattended deployment needs that wiki before they can write a reliable workflow.

The Makefile packages the script for distribution

erase-install ships a Makefile that builds a macOS installer package, which tells you how the tool is expected to reach machines in the first place.

The package payload is assembled under pkg/erase-install/payload, and the script is copied into the management directory that macOS administrators already know:

mkdir -p "$(PKG_ROOT)/Library/Management/erase-install"
cp "$(CURDIR)/erase-install.sh" "$(PKG_ROOT)/Library/Management/erase-install/erase-install.sh"
chmod 755 "$(PKG_ROOT)/Library/Management/erase-install/erase-install.sh"

The version number is not hardcoded in the Makefile. It is read out of erase-install.sh with awk, taking the value after a version= line, and the release tag is derived from it as v plus that version. The build output is named erase-install plus version plus .pkg, and the signing identity defaults to Graham Pugh through the SIGN_ID_PKG variable.

The build also downloads swiftDialog at a version the script itself declares, resolving the download through the GitHub releases API using a token read from a file, and the icons folder is copied alongside the script. In other words, the whole chain, script plus dialogue tool plus icons, ships as one signed package that a management system can push to a Mac.

How this differs from letting macOS upgrade itself

The natural alternative is the path Apple already provides, in which a Mac downloads and installs a macOS update through its own update mechanism, with no third party script in the loop. The difference in approach is worth spelling out because it decides whether you need this project at all.

Apple's own path upgrades a Mac in place. The system volume is preserved, user data stays where it is, and the update arrives as part of the standard operating system lifecycle. erase-install goes further: it can pull a full installer application and run startosinstall, and with --eraseinstall on an APFS system volume it wipes the volume and installs macOS onto a clean filesystem. That is a different operation, closer to imaging than to updating.

The trade-off follows from that. An in-place upgrade is something a user can trigger on a laptop, and it needs no separate package and no dialogue tool. An erase and reinstall wants a known-good target state, and it wants to be driven from a management system that already knows how to push packages and run scripts as root. The project started life as a Jamf Pro workflow and grew from there, so its options are shaped for that world, and the price of that focus is a tool that is heavy to use and dangerous to misuse.

Release history and what the README leaves out

The published releases show a long and mostly steady line: v27.3 dated 2023-01-24, v42.3 dated 2026-04-08, and v43.3 dated 2026-09-09. The last push to the repository was on 2026-10-09, so the repository is not archived and work is landing on it. A CHANGELOG.md sits in the top level alongside the scripts and the package build.

What the README does not document is as important as what it does. There is no description of rollback behaviour, no troubleshooting section, and no list of the individual command line options even though the project advertises many of them. There is no statement of what happens if the installer download fails midway, or if the target volume cannot be erased, so failure handling is left to the operator. There is also no test suite described beyond a _tests/ directory in the repository, and no account of how the automated checks are run.

The licence is Apache-2.0, which permits modification and redistribution provided the licence and notice are preserved. Internal use inside an organisation sits comfortably inside those terms, while anyone redistributing a modified build as a product should read the licence text for itself. No legal advice is offered here beyond reading that text.

Editorial conclusion

erase-install fits administrators who need a repeatable, self-service macOS deployment path from an installer already present on the disk, and it fits anyone maintaining such a workflow in Jamf Pro or a comparable tool. It does not fit a person testing on their own Mac, since the script describes itself as a self-destruct script and erases the target volume. Before deploying it, check the branch you are on against the macOS version of the target machine, confirm the required mist-cli and swiftDialog versions for that fleet, and read the wiki, because the README itself points there for the detailed documentation.

Frequently asked questions

Official sources

1. grahampugh/erase-install on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases