A macOS point upgrade is usually painless. A yearly major upgrade — the ones Apple ships every autumn — is not. The installer downloads several gigabytes, unpacks another few, writes a new system volume, and then wants working room to migrate your user data. If the disk is thin on space or the machine has years of accumulated cruft, the installer fails halfway with an opaque error, and you get to reboot into a broken state.

This checklist takes about 45 minutes and prevents the vast majority of those failures. It applies to any recent macOS version but is written assuming you are moving from Sonoma or Sequoia to whatever ships next.

Free at least 25 GB before you start

The published minimum is smaller — usually around 15 GB free. In practice, plan for 25 GB. The installer needs room for the download, the expanded installer package, a snapshot of your current system before it writes the new one, and a working buffer for the migration. Below 20 GB free, the installer sometimes proceeds and then bricks the machine when it runs out mid-upgrade.

Check the honest number:

df -h /

If Available is under 25 GB, run through our regular cleanup order — Trash, Downloads, DerivedData, snapshots — before starting the installer.

Take a real backup, not just Time Machine

Time Machine is necessary but not sufficient. It is a bootable-adjacent backup, not a disk clone, and if the migration fails mid-way you cannot always boot into the old state from it alone. Do both of the following:

  1. Run a Time Machine backup and wait for it to finish. Verify the timestamp in the Time Machine menu.
  2. If you have a spare external drive, use a disk-cloning tool to make a bootable clone. On Apple silicon this is more complex than it used to be (the boot volume is signed), but the clone still gives you data recovery even if it will not boot directly.

Do not upgrade a machine whose only backup is iCloud Drive. iCloud is not a backup. It syncs, which means a deletion on the Mac becomes a deletion in the cloud, and a corrupted file becomes a corrupted file everywhere.

Confirm your critical apps are compatible

Every major macOS upgrade breaks something. In recent years the pattern has been:

  • 32-bit Intel apps have been dead since macOS Catalina in 2019. If you still have any, the installer will refuse to migrate them.
  • Kernel extensions from before Apple silicon rarely work. If a VPN, virtualisation, or antivirus tool relies on one, check the vendor's compatibility notes.
  • Some professional apps (older Adobe versions, older audio plugins, some VMware releases) skip a major version. Waiting a month is often cheaper than pioneering.

To list any legacy 32-bit binaries that survived a Time Machine restore from an older Mac:

system_profiler SPApplicationsDataType | grep -B 3 "Kind: Intel"

If a critical app is listed there, sort it out before upgrading, not after.

Clean the caches that the installer will rebuild anyway

Some caches take up space and slow the installer down because the migration will regenerate them. Clearing them now recovers space without losing anything:

  • Xcode DerivedData: rm -rf ~/Library/Developer/Xcode/DerivedData/*
  • iOS simulator images for uninstalled runtimes: xcrun simctl delete unavailable
  • Homebrew downloads: brew cleanup --prune=all
  • npm cache: npm cache verify (safer than npm cache clean --force)
  • pnpm store: pnpm store prune
  • Docker unused images: docker system prune -a --volumes (only if you are comfortable losing local images and volumes)

These are the same commands that a monthly maintenance routine runs. Running them before an upgrade means the migrated system starts clean.

Prune iOS backups you no longer need

iPhone and iPad backups live at ~/Library/Application Support/MobileSync/Backup/. Each is 5-15 GB. If you have retired a phone in the last two years, you probably have a backup for a device you no longer own. Open the folder and delete the ones whose Info.plist names a device you sold.

You can also delete these from Finder → your iPhone in sidebar → Manage Backups, which is safer because it shows a human-readable list.

Empty local snapshots

The installer will try to take a system snapshot of its own before writing. If your disk is already packed with older snapshots, that can fail. List and delete:

tmutil listlocalsnapshots /

Then for each snapshot you want to remove:

sudo tmutil deletelocalsnapshots <date-string>

Time Machine will make fresh snapshots on its next cycle. The old ones were only useful for a same-day rollback.

Turn off FileVault temporarily? No.

Some old guides say to disable FileVault before a major upgrade. Do not. On Apple silicon, FileVault is effectively free (it uses hardware acceleration) and disabling it is a multi-hour process that you have to reverse afterwards. The installer handles FileVault volumes correctly. Leave it on.

Verify the download before running it

When you download the installer from the App Store or System Settings → General → Software Update, wait for it to finish completely. A partial download will fail with a cryptic error. If you have to restart the download, delete the incomplete installer from /Applications first.

You can verify the installer is not corrupted by right-clicking it in /Applications and choosing Show Package Contents. If the package opens without complaint, it is intact. If Finder says the app is damaged, delete and re-download.

Plan for it to take longer than Apple says

A major upgrade takes 30-90 minutes on modern hardware, longer on machines with a lot of user data. Do not start it before a meeting or on the last day of a sprint. Plug in power, disable sleep in System Settings → Displays → Advanced, and let it run.

Do not close the lid on a laptop mid-upgrade. Some laptops cope with this, but it is a coin flip you do not need to make.

After the upgrade: check what came back

Once you are on the new version, run through the caches list one more time. Some of them (DerivedData, browser caches, iCloud local copies) will refill immediately as apps re-index and re-download. That is normal.

Check df -h / a week after the upgrade. If the disk has filled up significantly, one of your apps has re-populated a cache you did not expect. That is a good moment to open a storage map and find out which.

Where VolumeLens comes in

We built VolumeLens partly because pre-upgrade cleanups always come with the same question: where else is space hiding? The visual map answers it in one look. Every action is Move to Trash after review, which matters twice as much before a system upgrade: you want to be certain about what you are deleting.

The free tier scans, browses, searches, and cleans up. Insights — the paid tier — explicitly recognises the caches an upgrade will regenerate anyway, so you can clear them in one pass. See pricing for details.