Understanding Free Space on APFS Volumes

What
This article explains why free space on APFS volumes can look different from free space on older file systems such as HFS+.
When/Why
APFS free-space values can move around because macOS accounts for snapshots, clones, sparse files, and shared container space. That matters when you are checking whether a Mac has enough usable storage for updates, deployments, or troubleshooting.
How
Traditional file systems such as HFS+: Free space is usually calculated by subtracting occupied storage blocks from the total volume capacity.
Snapshots: APFS snapshots can hold blocks that look deleted from the live file system. Deleting a snapshot may free space, but the amount depends on what other snapshots still reference.
Clones: APFS cloned files can share storage blocks at first. As the files change, they use additional space. Finder may show the files separately while APFS still accounts for the shared blocks.
Sparse files: Sparse files reserve a logical size that can be much larger than the data they currently store. Copying or saving them without preserving the sparse format can expand them to their full size.
Other volumes: APFS containers share free space across volumes. macOS decides how much space volumes such as Data and VM use inside that shared container.
Free-space estimates: APFS and macOS report changing estimates for available space, including space that can be reclaimed from snapshots or other system-managed storage.
Because APFS can reuse, share, or reclaim blocks, a single free-space number may not tell the whole story. Check the context before assuming a Mac is out of space or before using Finder-reported values as the only source of truth.
For a second opinion, see the related links below. The linked 
diskspace tool can help return APFS-aware available-space values from the command line.
Related Links
Free space on an APFS volume is an illusion – The Eclectic Light Company
GitHub - scriptingosx/diskspace: macOS command line tool to return the available disk space on APFS volumes