"Startup Disk Almost Full" on Mac — What It Means

The warning is blunt: "Your startup disk is almost full." macOS shows it as a system alert, sometimes mid-task, and it's genuinely disruptive — Spotlight indexing slows down, apps stutter on launch, and Time Machine backups start failing silently in the background. But the alert itself gives you almost nothing to work with beyond a button that opens Storage Management and a vague suggestion to "optimize storage."

This is one of the most common storage complaints on macOS, and it happens to careful, organized people just as often as it happens to digital hoarders. You can have an empty Desktop, a tidy Downloads folder, and still get this warning, because most of what fills a startup disk in 2026 isn't sitting in a folder you'd think to check. It's spread across caches, build artifacts, snapshots, and leftover application data that Finder doesn't surface by default.

This post walks through what "startup disk" actually refers to, why the warning triggers when it does, and the concrete steps — Terminal commands included — to find out what's really eating the space before you do anything drastic like reinstalling macOS or buying a bigger drive.

On every Mac since the shift to APFS, your internal drive is really a single APFS container split into multiple volumes that share the same free space pool: a system volume (read-only, holds macOS itself), a Data volume (holds your files, apps, and most everything you interact with), and often a Preboot, Recovery, and VM (swap) volume. "Startup disk" in the warning refers to this whole container, not one file you can point at.

That's why the warning can feel sudden — it's not about one volume slowly filling, it's about the combined free space across the container dropping below a threshold. A large swap file created during a memory-heavy session, a burst of Xcode builds, or a batch of new Docker images can all tip it over in a single afternoon. The system volume itself is normally sealed and doesn't grow much between OS updates, so almost all of the growth you're chasing is happening on the Data volume or in purgeable space shared across the container.

It also explains why two Macs with the "same" amount of free space can behave differently near the threshold — one might have most of its remaining space as genuinely free blocks, while the other has a chunk of it tied up as purgeable snapshot data that macOS hasn't gotten around to reclaiming yet.

Before digging into causes, confirm what you're working with. Open Terminal and run the following. Don't skip this step even if you're confident you already know the number from About This Mac — that number is frequently stale, cached from the last time macOS recalculated it in the background, and can lag behind what's true right now by a significant margin.

In practice, four categories account for most "almost full" warnings on developer and power-user Macs, and they're worth checking roughly in this order since it maps to how often each one turns out to be the actual cause:

Terminal's du command is the fastest way to get real numbers without waiting for Finder to calculate folder sizes one at a time, which can take minutes on a large, deeply nested folder like ~/Library. Run this to see the top-level size of your home folder's biggest hidden directories:

Because snapshots don't show up in du output the way regular files do, check for them separately. This is genuinely one of the highest-value checks on this whole list, since a Mac that's had a lot of file churn recently — a big project migration, a video edit, a batch of large installs — can accumulate a surprising amount of snapshot data in a short window:

The commands above work, but they're a scavenger hunt — you're running one, reading a number, running another, and never getting a full picture at once. Doing this properly means checking snapshots with tmutil, dev caches with du and find, Docker separately with docker system df, and cross-referencing all of it against df -h to make sure the numbers actually explain the gap. That's a reasonable amount of Terminal work for a one-off, but it gets old fast if this keeps happening.

This is the exact gap Reclaim was built for: a free treemap scan of your whole disk that shows every category — dev caches, AI model files, duplicates, app leftovers, local snapshots — sized and grouped in one view, so you can see what's actually large before deciding what to touch.

Once you know what's large, act on the safest categories first. Emptying old installer .dmg files from Downloads and thinning local snapshots are essentially zero-risk. Developer caches like node_modules and DerivedData are regenerable — deleting them just means the next build or install takes longer, nothing is permanently lost. Be more careful with anything inside ~/Documents, ~/Desktop, or app-specific data folders you don't recognize; check what it is before removing it, since not everything under Application Support is disposable cache — some of it is your actual saved settings or data for that app.

If you'd rather not memorize Terminal flags every time this happens, Reclaim lets you bulk-select entire categories — all node_modules folders, all DerivedData, all local snapshots — and review the total size before anything moves to Trash, which is where every deletion goes rather than being permanently removed outright. That last part matters more than it sounds: it means a mistaken selection is recoverable exactly the way a Finder drag-to-Trash is, not a one-way command you have to be certain about in advance.

A single cleanup pass fixes the warning today, but if you do regular development work, dev caches and snapshot buildup will happen again — it's a natural side effect of how these tools operate, not a one-time mistake you made. Rather than waiting for the next warning, it's worth building a light habit around checking a couple of the biggest categories every month or two: run du -sh ~/Library/Developer/Xcode/DerivedData and tmutil listlocalsnapshots / as a quick health check, especially after a stretch of heavy project work or big installs.

It's also worth checking whether your workflow is generating more waste than it needs to. Some CI setups and editor configurations rebuild from scratch far more often than necessary, regenerating gigabytes of DerivedData or node_modules repeatedly when a cached build would do. That's a separate performance question from disk space, but the two are often connected — a Mac that rebuilds excessively also tends to accumulate excess cache faster than one that doesn't.

If you'd rather not run a monthly Terminal checklist by hand, a periodic scan with a tool that tracks these categories automatically catches the buildup before it reaches warning-threshold levels, rather than after.