“Your disk is almost full.”
What to do first.

macOS shows this notification when free space on your startup disk runs low. Apple doesn't publish the exact point at which it appears, so don't read it as a fixed number. Read it as: the next big download, build, update or Docker pull may fail.

It helps to know which number macOS means by “free”. Finder and Storage settings count some space as available even though something still occupies it. Apple says so directly about Time Machine: your Mac counts the space used by local snapshots as available storage, because it deletes them when the space is needed. Terminal shows the stricter figure:

df -H /System/Volumes/Data

Your files live on the Data volume, so measure that one rather than /, which is the read-only system volume. Both share one APFS container, so the Avail column matches; Used is only meaningful on the Data volume. -H prints decimal units (GB), the ones Finder uses.

macOS's own answer lives in System Settings → General → Storage. Apple's Optimize storage space page describes the three recommendations you find there:

Apple adds that when space is needed, macOS also clears caches and logs that are safe to delete: temporary database files, interrupted downloads, staged macOS and app updates, Safari website data and more.

All of that is worth doing if you keep media and mail on your Mac. But notice what the list doesn't mention: Docker's disk image, Xcode's build output and simulators, node_modules folders, Gradle and package-manager caches, or the versions and models AI tools download. On a developer's Mac that is usually where the space went, and Storage settings mostly files it under System Data. The System Data guide takes that grey bar apart.

Check these in order. The first ones are quick wins; the later ones need a little more thought. Each command only measures, it doesn't delete anything. 2>/dev/null hides errors for folders you don't have.

1. The Trash

Apple's Free up storage space article reminds you that a file you move to the Trash keeps its space until you empty the Trash. In Terminal:

du -sh ~/.Trash

If that prints “Operation not permitted”, Terminal doesn't have Full Disk Access. Open the Trash in Finder instead and look at the item count, or grant access in System Settings → Privacy & Security → Full Disk Access.

2. Downloads

du -sh ~/Downloads
ls -lhS ~/Downloads | head -n 15

The second line lists the biggest files first. Installers, disk images and archives you already unpacked are the usual suspects.

3. Docker

docker system df
du -h ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw

Docker Desktop keeps every image, container and volume inside one file, Docker.raw. It is a sparse file: ls -lh can show a size far bigger than what it occupies, while du shows the blocks it really uses. Use Docker's own prune commands to shrink it, never delete the file. The Docker guide covers which prune is safe.

4. Xcode build output and simulators

du -sh ~/Library/Developer/Xcode/DerivedData \
       ~/Library/Developer/CoreSimulator/Devices \
       ~/Library/Developer/Xcode/iOS\ DeviceSupport 2>/dev/null

DerivedData is build output and indexes Xcode recreates on the next build. Simulator devices hold app data you may want to keep. Read Xcode DerivedData and simulators and DeviceSupport before removing either.

5. node_modules and other project folders

find ~/Projects -type d -name node_modules -prune -exec du -sh {} + 2>/dev/null | sort -h

Replace ~/Projects with the folder where your code lives. -prune stops find from descending into each match, so nested copies aren't counted twice. Projects you haven't opened in months are the safe ones: npm install brings the folder back. See Delete node_modules recursively.

6. Package-manager and build caches

du -sh ~/Library/Caches/Homebrew ~/.npm ~/Library/pnpm/store \
       ~/Library/Caches/pip ~/.gradle/caches 2>/dev/null

Every package manager keeps a copy of what it downloaded. Each has its own command to clear it, such as brew cleanup or npm cache clean --force; the cost is downloading things again. See package manager caches and the Gradle cache.

7. AI coding tools and local models

du -sh ~/.local/share/claude/versions ~/.ollama/models 2>/dev/null

Claude Code's native installer keeps earlier versions next to the current one, and ~/.local/bin/claude points at the one in use. Ollama keeps downloaded models in ~/.ollama/models; ollama list shows them and ollama rm removes one. Session transcripts live in other folders and are yours to keep or archive. See AI coding tools.

8. Time Machine local snapshots

tmutil listlocalsnapshots /

According to Apple, Time Machine saves a snapshot about every hour and keeps it for 24 hours, plus one of your last successful backup until space is needed. It deletes them as they age or as space is needed, and snapshots already count as available in Finder. If you still want them gone, Apple's way is to set Time Machine's backup frequency to Manually, wait a few minutes, then turn automatic backups back on.

When the disk is full it is tempting to delete whatever is big. These are the places where that goes wrong:

• ~/Library as a whole, or any folder directly inside it. Apps keep settings, databases and licenses there next to caches. Delete specific cache folders, not their parents.
• iCloud Drive and other cloud-synced folders (~/Library/Mobile Documents, ~/Library/CloudStorage). Deleting files there deletes them on your other devices too.
• An app's whole data folder in ~/Library/Containers, Group Containers or Application Support, and your Mail, Messages and Keychains folders. Use the app's own settings to remove its data.
• Anything inside a Photos library. Photos manages its own files; Apple suggests moving the library to another drive instead.
• Docker.raw. It holds every image, container and volume, including databases you may not have backed up.
• Xcode archives in ~/Library/Developer/Xcode/Archives. They hold the dSYMs you need to symbolicate crash reports from builds you shipped.

When in doubt, move it to the Trash rather than deleting it with rm, and empty the Trash once everything still works.

The warning tells you where you are, not how you got there. Free space on a developer's Mac moves in two ways. Some drops are temporary: a large build or download that you delete again an hour later. Others are steady: images, caches and versions that pile up a little every day and never leave on their own.

The steady part is the one worth watching. If you write down free space once a day, the slope of that line in gigabytes per day tells you roughly how many days you have left, long before a notification does. Even a plain log helps:

echo "$(date +%F) $(df -k /System/Volumes/Data | awk 'NR==2 {print $4}')" >> ~/free-space.log

That appends the date and the free kilobytes to a file. A few weeks of lines show the trend. A single reading, before or after a big build, doesn't.

Specula shows free space in the menu bar and keeps 30 days of history, sampled every 5 minutes. It notifies you when free space drops below a threshold you set (20 GB unless you change it) or when space disappears fast — by default 10 GB or more within an hour. When macOS could free more than 1 GB of purgeable space on demand, Specula shows that amount next to the free-space figure.

Its forecast is a least-squares trend over the last 7 days, such as “full in ~6 days, −3.1 GB/day”. It needs at least 6 hours of samples, so one build or download can't fake a trend, and space you free with a cleanup is taken out of the slope instead of hiding the consumption that continues.

Its Clean Up pages measure the places above — Docker, Xcode, simulators, project folders, package caches, AI tools, the Trash and Downloads — and mark each one regenerable, app data or your data, with nothing deleted before you confirm.