Disclosure: this article links to CleanMyMac, a commercial product developed by MacPaw. We may earn a commission from purchases made through those links. CleanMyMac is Apple-notarized and distributed through the MacPaw Store, Setapp, and the Mac App Store. Every method described here also works manually at no cost, and the manual method is shown first in every case.
Key takeaways:
- The warning is a forecast, not a failure. It fires when genuinely free space drops below what macOS considers safe working headroom — not when the disk is literally full.
- Finder and the warning measure different things. Finder counts purgeable space as available; the warning does not.
- If the alert returns within minutes of a cleanup, something is actively writing. If it returns after days, you are looking at snapshots or a Trash that was never emptied.
df -h /System/Volumes/Dataandtmutil listlocalsnapshots /are the two commands that separate the common cases in under a minute.- A full boot volume will not corrupt your data, but it will block system updates and can stall startup.
- The fix procedure lives in the companion cleanup guide; this article is about working out which problem you have before you delete anything.
What the warning actually means
macOS shows “Your startup disk is almost full” when free space on the boot volume falls below the level it treats as safe operating headroom. This is not the same as the disk being full. The system is reporting that it no longer has comfortable room for the things it needs to write without being asked: virtual memory swap, temporary files, application scratch space, and the staging area a system update requires before it can install.
That distinction matters because it explains the single most common complaint about this alert — that it appears while Finder insists there is plenty of space left. Both readings are correct. They are answering different questions.
The warning is also non-blocking. Nothing stops working the moment it appears, and dismissing it does not make anything worse in the next hour. What it does mean is that the machine is now operating without a margin, and the failure modes that follow are unpleasant rather than dramatic: an app that cannot write its save file, an update that refuses to stage, a slowdown severe enough to feel like a hang.
Why Finder and the warning disagree
APFS reports free space in a way that includes purgeable content — data macOS believes it can reclaim on demand. That category covers local Time Machine snapshots, iCloud files that exist on the server and can be re-downloaded, and caches the system considers expendable.
Finder shows you the optimistic number: what could be available if macOS reclaimed everything reclaimable. The startup disk warning is driven by the pessimistic number: what is free right now, with no reclamation required.
When purgeable content is small, the two figures are close and nobody notices. When it is large — typically because local snapshots have accumulated — they diverge sharply, and you get a disk-full warning next to a Finder window claiming a great deal of free space.
| What you are looking at | What it counts | Why it differs |
|---|---|---|
| Finder “Available” | Free space plus purgeable content | Optimistic; assumes reclamation will succeed |
| Startup disk warning | Space free without reclamation | Pessimistic; drives the alert threshold |
df -h in Terminal |
Filesystem-level free space on the volume | Closest to what the system actually has now |
| Storage pane in Settings | Categorized breakdown, recalculated on a delay | Lags behind reality by 15–60 minutes |
Storage says full but Finder shows nothing
A specific version of the same contradiction deserves its own answer: the volume is reportedly full, you have gone looking for what is consuming it, and Finder shows you nothing large enough to explain the figure. Nothing is broken. Finder is simply not showing you most of what is on the disk.
Three separate mechanisms hide storage from a normal Finder window.
Hidden files and directories. Anything whose name begins with a dot is hidden by default, as are a number of system directories. Press Command-Shift-. in any Finder window to toggle their visibility. Much of what appears will be small, but hidden directories in your home folder can hold substantial caches for development tooling.
Library folders. Your user Library is hidden from Finder by default, and it is where the majority of unexplained consumption lives — caches, application support, containers, device backups. Hold Option while opening Finder’s Go menu to reveal it, or press Command-Shift-G and enter ~/Library.
Content with no file representation. Local snapshots and virtual memory swap occupy real space but do not appear as files you can browse to at all. No amount of looking in Finder will reveal them, which is why the diagnostic commands below matter more than visual inspection.
Spotlight compounds the problem, because it excludes hidden and system locations from results by default. Searching for large files will not surface anything in these categories, and concluding from an empty search that the disk is fine is a reliable way to spend an afternoon on the wrong problem.
du -sh ~/Library/* 2>/dev/null | sort -rh | head -20That single command usually explains the discrepancy in one screen, and it takes seconds. If the total it reports is far smaller than the space you are missing, the remainder is almost certainly snapshots or swap — neither of which is a file, and both of which are covered below.
Diagnose it in three commands
Before deleting anything, work out which case you are in. These three commands take under a minute and none of them modify the system.
Start with actual filesystem-level free space on the data volume:
df -h /System/Volumes/DataThis gives you the number the system is really working with, unmediated by Finder’s purgeable arithmetic. Compare it against what Finder claims. A large gap points directly at snapshots or iCloud offload candidates.
Next, check whether local snapshots are holding space:
tmutil listlocalsnapshots /
tmutil listlocalsnapshotdates /An empty or short list rules snapshots out. A long list, especially one with dates going back weeks, tells you the machine has been keeping local backups because its Time Machine destination has not been available.
Finally, find out whether anything is actively growing:
sudo du -xh -d 1 /System/Volumes/Data 2>/dev/null | sort -rh | head -20sudo and traverses the whole data volume, which can take several minutes on a large disk. It only reads — it deletes nothing — but back up before acting on anything it reveals. Run it twice, several minutes apart, and compare: a directory whose size changes between runs is the thing regenerating your disk usage.
Why the warning comes back after you clean up
This is the question that sends people to search in the first place, and it has three distinct answers. Identifying which one applies saves hours.
The space was never released
Files in Trash still occupy the volume. So do files referenced by a local APFS snapshot taken before the deletion — the snapshot holds those blocks so the backup remains restorable, and the space does not return until the snapshot ages out or is removed. This is the most common cause of “I deleted 40 GB and nothing changed.”
The Storage pane simply had not caught up
The categorized breakdown in Settings recalculates on a delay, and Spotlight often needs to reindex changed folders first. If you deleted files and checked immediately, you may have been looking at a stale number. Give it up to an hour before concluding anything.
Something is actively writing
If the warning returns within minutes rather than days, the disk is being refilled. The usual candidates are a sync client re-downloading a library after you deleted its local copy, a log file in a failure loop, and virtualization or container disk images that grow but never shrink on their own. The repeated du comparison above identifies this case directly.
Where the space usually is
Across the common cases, a small number of categories account for most unexplained consumption on a boot volume.
| Category | Typical location | Shrinks on its own? |
|---|---|---|
| Local Time Machine snapshots | Managed by tmutil, not visible in Finder |
Yes, eventually — slowly if the backup drive is absent |
| User and app caches | ~/Library/Caches |
No |
| Old iOS device backups | ~/Library/Application Support/MobileSync/Backup/ |
No |
| Uninstalled app leftovers | ~/Library/Application Support, ~/Library/Preferences, ~/Library/Logs |
No |
| Developer build artifacts | ~/Library/Developer/Xcode/DerivedData |
No |
| Container and VM disk images | App-specific; check the app’s own settings | No — deleting contents inside rarely shrinks the image |
The last row is the one that catches people repeatedly. Deleting images and containers inside a virtualization tool frees space inside its virtual disk, while the disk image file on your real volume stays the same size. That reclamation has to be triggered through the application itself.
App leftovers are the other persistent trap: dragging an application to Trash removes the bundle but typically leaves support files, preferences, caches, and logs behind in four separate locations. Hunting those manually per application is tedious rather than difficult, which is the one place a dedicated Mac uninstaller earns its place — an uninstaller module catches all four locations in a single pass instead of four Finder trips per app.
What to do once you know which case you have
Diagnosis points at one of four actions, in ascending order of effort.
- Empty Trash and wait an hour. If the numbers were stale or the space was sitting in Trash, this resolves it with no risk at all.
- Reconnect your Time Machine drive. If snapshots are the cause, letting a real backup complete allows macOS to thin local snapshots normally. This is safer than deleting snapshots by hand.
- Clear caches and leftovers. The ordered procedure — user caches, old device backups, app leftovers, developer artifacts — is covered step by step in the companion cleanup guide rather than repeated here.
- Accept that the volume is undersized. If the warning returns every few weeks despite a clean machine, no amount of cleanup will fix it. The answer is offloading to external or cloud storage.
If you would rather not work through the folder-by-folder hunt in step three, CleanMyMac maps the same categories in a single scan and shows you what it proposes to remove before removing it. It is developed by MacPaw and is Apple-notarized, which matters in a category that has historically attracted scareware. The manual route reaches the same result for free and is worth doing at least once, if only to understand where your space actually goes.
Deleting snapshots by hand
If a backup drive is genuinely unavailable and snapshots must go, this is the supported route. It is listed after the safer options deliberately.
tmutil listlocalsnapshotdates /
sudo tmutil deletelocalsnapshots [date-from-the-output-above]sudo and permanently removes a restore point. Only delete snapshots whose dates you have confirmed in the listing output, and never delete your most recent snapshot unless a current backup exists elsewhere. If you are unsure, connect the backup drive and let macOS thin snapshots itself instead.
What this won’t fix
Diagnosis and cleanup address caches, snapshots, backups, and leftovers. They do not shrink a photo library, a video project, or applications you actively use. If free space stays low after all of the above, the remaining possibilities are narrower and more specific: a corrupted Spotlight index consuming abnormal space, a log file in a failure loop, an APFS snapshot that will not release, or simply more data than the volume was sized for.
Nor will any of this help a Mac that has already filled to the point of refusing to boot. That situation needs recovery mode or an external boot volume, and it is a different procedure from the one described here.
CleanMyMac app helps automate these steps in a single scan.
Frequently asked questions
What does “Your startup disk is almost full” actually mean?
It means macOS has calculated that free space on your boot volume has fallen below the level it considers safe for normal operation. The system needs working room beyond your files — swap, temporary files, scratch space, and update staging. The warning is a forecast rather than a failure report: nothing is broken when it appears, but the machine no longer has headroom. Because the calculation treats purgeable space differently from Finder, the warning can appear while Finder still reports substantial free space.
Why does the warning appear when Finder shows free space available?
They measure different things. Finder counts purgeable content — local snapshots, re-downloadable iCloud files — as available, because it could be reclaimed. The warning counts only what is free right now without any reclamation step. When purgeable data is large, the two numbers diverge sharply, producing the contradiction you are seeing. Running df -h /System/Volumes/Data gives you the figure closest to what the system actually has.
Why does the warning come back after I delete files?
Usually one of three reasons. The files may still be in Trash, which occupies the same volume. A local snapshot taken before the deletion may still reference those blocks, holding the space until it expires. Or something is actively regenerating data — a sync client, a runaway log, a growing disk image. Timing distinguishes them: a return within minutes points at active writing, while a return after days points at snapshots.
Can a full startup disk damage my Mac or my data?
It will not damage hardware, and APFS is built to fail safely rather than corrupt data when a volume fills. The real risks are operational: unsaved work lost when an app cannot write, updates that refuse to stage, and severe slowdowns from memory pressure. A genuinely full boot volume can also prevent startup from completing. Treat it as urgent maintenance, not an emergency — but do not leave it for weeks.
How much free space does macOS actually need?
There is no single official number, and the honest answer depends on workload. You need simultaneous room for swap, temporary files, and a full update staging area. Development, video, and virtualization work all expand that requirement considerably, since build artifacts and disk images grow by tens of gigabytes without notice. Aim for comfortable headroom rather than a specific figure, and treat recurring warnings as evidence the volume is undersized for what you do.
Does the warning ever appear because of an external drive?
The startup disk warning refers to the boot volume specifically, so a full external drive produces a different alert. External drives can cause it indirectly, though: when a Time Machine destination is unavailable, macOS retains local snapshots on the internal volume longer than usual, and those consume internal space. A machine that has not seen its backup drive in months is a common source of otherwise unexplained internal consumption.