"Your startup disk is almost full": what to do right now

What the warning means

Your startup disk is the internal drive that holds macOS, your apps and your files. macOS needs free space on it to run: for swap when memory fills up, for temporary files, for app caches and for software updates.

When free space gets very low, the Mac slows down, apps may fail to save, and updates cannot install. If the disk fills completely, apps can quit and the Mac may struggle to start. So treat the warning as a prompt to act today, not as an emergency that calls for deleting things at random.

The quickest safe wins, in order

Work down this list and stop as soon as you have comfortable room. Save your open work before you start.

• Empty the Trash. Right-click the Trash in the Dock and choose Empty Trash. Files in the Trash still count against your disk.
• Clear Downloads. Open ~/Downloads, sort by size, and remove disk images (.dmg), installers (.pkg) and zip files you have already used. Then empty the Trash again.
• Restart the Mac. This clears swap and temporary files. More on why below.
• Open Apple menu, System Settings, General, Storage. Click the info button next to Documents and look at Large Files. Delete or move to an external drive anything large that you do not need on this Mac.
• In the same screen, open iOS Files if it is listed, and delete backups of devices you no longer own.
• Still in Storage, open Applications, sort by size, and delete large apps you no longer use.

Why a restart helps

When your Mac runs short of memory it writes swap files to the startup disk. On a disk that is already nearly full, swap can take the last of the space, which is often what triggers the warning in the first place. Swap files are removed when the Mac restarts.

A restart also clears temporary files that apps and macOS left behind, and closes apps that were holding large files open. It will not fix a disk that is full of your own files, but it frequently buys a few GB, and that is enough room to do the rest of the clean up comfortably.

If you still need more room

The next tier takes a little more care but is still safe.

• App caches. Quit your apps, choose Go then Go to Folder in Finder, enter ~/Library/Caches, and move the contents of the largest folders to the Trash. Apps rebuild them.
• Developer files, if you write code. Xcode's DerivedData folder, unused simulators and old node_modules folders are build output and can be recreated.
• Message attachments. In Storage, open Messages and delete large videos and photos you do not need. With Messages in iCloud on, they are removed from your other devices as well.
• Photos. With iCloud Photos, turn on Optimize Mac Storage in Photos, Settings, iCloud. Originals stay in iCloud and smaller versions stay on the Mac.
• Move, do not delete. Finished projects, old videos and archives can live on an external drive.

Why free space may not rise straight away

If you use Time Machine, macOS keeps local snapshots on the startup disk. A snapshot can hold on to files you have just deleted, so the free space figure does not move as much as you expect. macOS removes snapshots when it needs the space, and they expire after about 24 hours anyway.

You can see whether any exist with the command below. It only lists them. Also give the Storage screen a minute to recalculate before trusting its numbers.

tmutil listlocalsnapshots /

What not to delete

A full disk makes large unfamiliar folders look like easy targets. These are the ones to leave alone.

• Anything in /System, /Library, /private or /usr. This is macOS itself, and removing parts of it can stop the Mac from starting.
• Swap files and the sleep image in /private/var/vm. macOS manages them. Restart instead.
• ~/Library/Application Support as a whole. It contains real data: app databases, mail, notes, saved games and device backups. Remove a single folder only when you know which app owns it and you no longer use that app.
• ~/Library/Containers and ~/Library/Group Containers as a whole. These are the data folders of sandboxed apps.
• The inside of your Photos library or Mail folders. Delete photos and messages from within the apps, not from Finder.
• Files you do not recognise, on the advice of a command you do not understand. If you cannot say what a command deletes, do not run it.

How to stop it happening again

Disks fill up slowly and then all at once, so a few habits go a long way.

• Turn on Empty Trash Automatically in the Storage recommendations. Items are removed after 30 days in the Trash.
• Treat Downloads as a temporary folder and clear it every month or so.
• Keep some headroom. macOS updates need several GB free to download and install, and swap needs room to grow.
• Delete installers once the app is installed.
• Check Storage in System Settings now and then, so growth does not surprise you.

A faster way to see what is filling the disk

Diskzy is a native Mac app, about 3 MB, that maps the whole disk. The first read takes a few seconds, and after that it stays current as files change. Its Clean up tab lists caches, logs, Xcode leftovers, project build folders, package manager caches and old installers, each one ticked or unticked with a reason, and it leaves alone any app that is open.

Everything Diskzy removes goes to the Trash, so nothing is gone until you empty it. Bear in mind that on a full disk you do need to empty the Trash to get the space back. Diskzy is free for 72 hours with everything unlocked, then $9 once for 2 Macs.