Why your Mac lies to you about free space

Ask your Mac how much space is free and you can get three different answers. Finder's Get Info says one thing, df -h / says another, and du on your home folder says a third, and at least one of them is just wrong. If your Mac's free space looks wrong, you're not imagining it. The tools really do disagree, and here's exactly why.

Three tools, three answers

Each tool answers a slightly different question, so the numbers rarely line up:

df -h /                 # what the filesystem accounts for — trustworthy
du -sh ~                # sums files it can walk — under-reports
# Finder → Get Info     # includes purgeable — often wildly inaccurate

df and du are Unix tools that predate APFS by decades. Finder is a modern GUI trying to be helpful about space it might reclaim. None of them is lying on purpose, but only one of them is a good answer to "how much room do I actually have," and it isn't Finder.

Why Finder's free-space number is just wrong

Finder folds purgeable space (space macOS believes it could free up later) into the "available" figure it shows you. The problem is that the estimate is frequently, badly off.

Howard Oakley, who reverse-engineers macOS storage internals, documented Finder reporting 83.71 GB of purgeable space on a disk where his own measurement tool found the real purgeable amount to be 0 GB. Not slightly optimistic. Off by the entire figure. Finder was promising 83.71 GB it could not actually deliver.

So when Finder says you have plenty of room and your disk fills up anyway, this is why. It's quoting a number that includes space that may not exist.

Why du under-reports

du walks the directory tree and adds up the files it can see. That sounds like the straightforward approach, but on APFS it misses two big things:

• Snapshot-retained blocks. When a file changes, its old blocks are kept as long as a local snapshot references them. du walks your live files, not the retained originals, so that space is invisible to it.
• Purgeable data. OS-managed caches and indexes that macOS counts against your disk aren't things du sums as your files.

So du tells you how big the files you can see are, which is smaller than how full the disk really is. It under-reports.

Why df is the closest to the truth

df doesn't walk files. It asks the filesystem itself how many blocks are used and how many are free at the container level, then reports that:

Filesystem  Size   Used  Avail  Capacity  Mounted on
/dev/disk3s1  926Gi  ...   ...    ...       /

(Values above are just the column layout, not a reading.) Because it reports the filesystem's own accounting rather than an estimate or a file-by-file sum, df is the number to trust for "how much room is actually left." It won't break "System Data" into pieces for you (that's a different job), but for the single free-space figure, it's honest.

Purgeable space and snapshots: why the numbers diverge

The gap between these tools comes down to two APFS features that traditional Unix tools never had to account for.

Purgeable space is Apple's term for space macOS will free up on demand; you can't delete it yourself. APFS snapshots are point-in-time freezes of the filesystem: taking one copies no file data, but as you change files afterward, the original blocks are retained while the snapshot exists. That retention silently consumes space Finder and du don't show.

Here's the nuance worth keeping: it's tempting to say "purgeable space is just snapshots," but the experts don't actually agree on that. Cleaner vendors describe purgeable as mostly local snapshots. Oakley's more rigorous analysis argues macOS counts snapshots as used space, not purgeable, and that genuine purgeable space is OS-controlled caches, Spotlight indexes, and version databases. When the people who measure this for a living can't reconcile what counts, that disagreement is the reason the numbers you see can't be trusted. For the full breakdown of what purgeable really includes, see purgeable space on a Mac; for the grey block Finder can't explain, see what System Data actually is.

How to get the real number

Skip Finder for this. Two trustworthy paths:

• Disk Utility (the GUI way). Open Disk Utility, and in the sidebar select the APFS container, the top-level item, not the volume nested under it. Its free-space figure is the filesystem's own accounting. If you select a volume instead, macOS shows free space with the purgeable amount in brackets: the maximum that could be freed if everything purgeable were deleted. Useful context, but not your real headroom.
• df -h / (the command-line way). Read the Avail column. Same filesystem accounting, one line, no estimate.

If you want to understand where the space actually went once you know how much is missing, that's a bigger question; walk through the hidden storage on your Mac for the full map.

Reconciling three tools that each report a different number, then chasing purgeable space and snapshots by hand, is tedious and easy to get wrong. That's exactly the gap Plumby closes. It reads what Finder, df, and du each claim, reconciles them into one honest number, and shows the difference with exact paths instead of an estimate. Nothing is fabricated. Freed space is measured as each item goes, and anything it clears can go to the Trash rather than be deleted, so you can put it back.