Your startup disk is almost full: what to do, in order

The message shows up when macOS is running short of room to work in, and it does not wait for a convenient moment. Usually it is mid-export, or the day you needed to install something.

Ignore the advice to reinstall macOS. You almost never need to. Work down this list and stop when you have enough room — most people are done by step four.

1. Find out how bad it actually is

df -h /System/Volumes/Data

The Avail column is the space that exists right now, without macOS deleting anything first. Do this before you delete a thing, because Storage settings usually reports a larger number — it adds purgeable space, mostly Time Machine snapshots, which it can free on demand. The df figure is the pessimistic one, and it is the one an installer will complain about.

Write the number down. You will want to compare later.

2. Empty the Trash — all of them

Obvious, and still the most commonly skipped step. There is a Trash for your account and another on every external volume you have ever deleted from.

du -sh ~/.Trash

If an external drive is connected and still full after you deleted things from it, look for a hidden .Trashes folder at the root of that drive.

3. Delete installers you have already run

Disk images and packages sit in Downloads for years. Nobody has ever needed one twice.

find ~/Downloads -type f \( -name "*.dmg" -o -name "*.pkg" -o -name "*.zip" \) -exec du -sh {} \; | sort -h | tail -20

A single macOS installer is 12 GB or more. Two of them is a bad afternoon solved in ten seconds.

4. Thin Time Machine’s local snapshots

Time Machine keeps snapshots on your internal disk even when no backup drive is attached. On a machine that has been running a while they can be enormous.

tmutil listlocalsnapshots /
sudo tmutil thinlocalsnapshots / 50000000000 4

The big number is the bytes you want back, roughly 50 GB here. The 4 is urgency, and 4 is the most aggressive setting. Your real backups on the external drive are not touched.

For most people, steps two to four end the emergency. If you are still short, keep going.

5. Find the genuinely large files

Spotlight already indexed the size of everything, so you do not need to walk the disk:

mdfind 'kMDItemFSSize > 1073741824'

That lists every file over a gigabyte. Expect virtual machine disks, video projects, Docker images and a couple of applications. Running that here it returns seven results, and one of them is a 40 GB Docker disk image that I had entirely forgotten about.

For a folder-by-folder view of where it went:

du -sh ~/* | sort -h
du -sh ~/Library/* | sort -h | tail -15

6. Old iPhone and iPad backups

du -sh ~/Library/Application\ Support/MobileSync/Backup/*

Delete these through Finder — select the device in the sidebar, then Manage Backups — rather than dragging folders. Check the dates first. A backup for a phone you no longer own may be the only copy of it that exists.

7. Xcode, if you have it

Developers can usually free 30 GB here without consequence:

rm -rf ~/Library/Developer/Xcode/DerivedData/*
xcrun simctl delete unavailable
du -sh ~/Library/Developer/Xcode/iOS\ DeviceSupport

Build output regenerates. Simulator runtimes you no longer have installed are dead weight. Device support files are re-downloaded when you next connect a phone.

8. Caches, carefully

Leave this until later than most guides suggest, because the payoff is smaller than the internet claims and the risk is higher.

du -sh ~/Library/Caches/* | sort -h | tail -15

Quit the app first, then clear that app’s folder specifically. Do not empty the whole Caches directory in one go — it works, but you will be logged out of things and everything will feel slow for a day while it rebuilds.

9. Move the big libraries off the machine

If Photos or Music is the problem, moving beats deleting. Both let you hold the library on an external drive: quit the app, copy ~/Pictures/Photos Library.photoslibrary to the external disk, then hold Option while launching Photos and choose the new location. Verify it opens and everything is there before you delete the original. That last sentence is the one people skip.

What not to do

• Do not reinstall macOS to free space. It does not remove your files, so it does not solve this.
• Do not delete anything in /System or /private/var. The system volume is sealed, and swap comes straight back.
• Do not run a “cleaner” that will not show you the file list first. This category has a long history of scareware, and the ones that hide what they are deleting are hiding it for a reason.
• Do not empty ~/Library wholesale. Your preferences, keychains and app licenses live there.

Then restart

Genuinely. A restart clears caches that cannot be removed while macOS is running, and it forces Storage settings to recalculate instead of showing you a figure from four hours ago.

Run df -h /System/Volumes/Data again and compare it to the number you wrote down at step one. Storage settings will lag behind and read higher; df is the figure to judge progress by.