Reading Mac disk space in Terminal and why it disagrees with Finder

Three commands answer three different questions. df asks the file system how many blocks are free. du adds up the files it can walk. diskutil describes the container underneath both. They disagree because they measure different things. One common disagreement is only the units.

Finder is a fourth answer again, the least literal of the four.

The three commands

Start with df, use du to attribute, reach for diskutil when the first two do not add up.

df, plus the units that catch everybody out

df -h / reports the size, used and available figures the file system itself holds. It does not walk a single file, which is why it returns instantly on a full disk where Finder would think about it.

Here is the part that wastes an afternoon.

df and Apple count in different units. The -h flag prints binary units and labels them Gi. Apple reports storage in decimal GB. A volume where df says 299Gi available and diskutil says 321.0 GB free is not inconsistent. Those are the same quantity written two ways.

The gap runs about seven per cent and grows with the number, so on a 2TB drive it looks like well over a hundred gigabytes have gone missing. Nothing has. Use df -H with a capital H for decimal units and the two tools agree.

Why / is not where your files are

Run df -h / on a current Mac and the used figure comes back surprisingly small, around twelve gigabytes on many machines.

That is correct. On modern macOS / is the sealed system volume, which is read only and does not grow. Your files sit on the data volume, mounted at /System/Volumes/Data, sharing the same container.

That is the line to read for how full the Mac actually is. The two volumes report the same available figure, because they draw on one shared pool, which is also why the used columns never add up to the container total.

du, plus the things it cannot see

du -sh ~/Documents gives the size of one thing. du -sh * in any folder gives a line per item, which is the fastest way to find the large one.

Two habits make it usable in practice. Sort the output with du -sh * | sort -h so the biggest lands at the bottom. And expect permission errors on system paths, which explains why sudo appears in half the examples online.

What matters more is what du misses.

It sums files it can walk, so anything the file system is holding without a visible file to point at goes uncounted. Snapshots and purgeable data are the two big ones. That is a large gap. It is also the whole reason a delete can free nothing at all.

It also miscounts in the other direction. APFS clones let two files share the same blocks. du counts both, so duplicating a folder appears to double the disk usage when nothing was written.

diskutil, for the layer underneath

When df and du disagree with each other, the answer sits one level down.

diskutil apfs list prints the containers, the volumes inside each one and a figure for capacity in use. It also names the roles, so you can see which volume is System, which is Data and which are the hidden ones.

diskutil list internal is the blunter version and reveals something Disk Utility hides badly. A volume you forgot about, sitting inside the same container, quietly holding space. An abandoned install, a second macOS, a container created for a test years ago.

One property is worth carrying into every reading. Volumes draw on one pool, so their free figures move together. Containers do not. Each holds a fixed slice of the disk. So a container that is full stays full even when the disk next to it is empty.

When Terminal is worth opening at all

Most storage questions do not need any of this. Three do.

The numbers disagree and you need to know which is right. Finder, Disk Utility and an installer giving three answers is the classic case. df settles it in a second.

Something is large and Finder will not tell you what. Walking down with du finds it in a few commands, including inside folders Finder declines to size.

The arithmetic is impossible. Used plus free coming to more than the disk holds means there is a layer you cannot see. Only diskutil shows it.

Outside those, the storage bar is a perfectly good answer and considerably faster to read.

Which number to trust

Finder is missing from that table deliberately. Finder's available figure includes purgeable space, which means it reports room that does not exist yet and could never arrive. It is the right number for a rough glance and the wrong one for a decision.

How the storage bar arrives at its categories is a separate reading exercise.

Four things that skew every count

Worth knowing before you conclude that a number is wrong.

Clones. Two names, one set of blocks. Counted twice by du and once by df.

Sparse files. A disk image nominally 100GB holding 2GB occupies 2GB. Some tools report the nominal size.

Dataless files. Anything offloaded to iCloud is a placeholder locally, so it costs almost nothing on disk while looking full size in Finder.

Compression. macOS compresses parts of the system volume, so the bytes on disk are fewer than the file sizes suggest.

None of those is a fault. They are the reasons two honest tools return two honest numbers that differ.

The short version

df -h /System/Volumes/Data for the truth about free space, remembering that Gi is not GB. du -sh * | sort -h to find what is large. diskutil apfs list when the arithmetic refuses to work.

And if df and Finder disagree by tens of gigabytes with nothing obvious to explain it, the difference is nearly always purgeable space rather than a broken tool.