Two different numbers, measured
macOS exposes several "free space" figures and they do not agree. Measured on one Mac, at the same moment:
| Source | Reports | What it means |
|---|---|---|
| Finder / About This Mac | 13.1 GB | Includes space macOS believes it could reclaim |
df -h | 10.4 GB | What a program writing a file can actually use |
The 2.7 GB difference is purgeable space — caches, downloaded-again-able files and local snapshots macOS thinks it can evict under pressure. Finder counts it because in theory you can have it back. A compiler cannot count it, because in practice the eviction may not happen fast enough, or at all.
See the real number yourself
df -h /System/Volumes/Data
The Avail column is the honest figure. If it is far below what Finder claims,
purgeable space is the difference.
Why this matters more than it sounds. Every storage tool that shows you "free space" has to pick one of these numbers. Most pick Finder's, because it is the larger and friendlier one. That is also the one that is wrong when your build is failing.
Local snapshots are the other half
If Time Machine has taken local snapshots, deleted files stay on disk inside them. Check with:
tmutil listlocalsnapshots /
An empty list means snapshots are not your problem. A long list means the space you "freed" last week is still sitting there.
And the Trash counts too
The Trash is on the same volume. Moving 10 GB there frees exactly nothing until it is emptied — which is its own surprise.