Edmondo's Vault

diskutil - The Ground Truth Tool

May 18, 20263 min read

diskutil — The Ground Truth Tool

diskutil is Apple’s command-line interface to the Disk Arbitration and IOKit disk management stack. For APFS accounting, it has access to container-level and volume-level metrics that no userspace filesystem traversal can match.

The most important command

diskutil apfs list

Read the output in two sections:

Container section — gives you ground truth for the entire pool:

  • Container Total Space — physical capacity of the container
  • Container Free Space — truly unallocated blocks. This is real free space.

Per-volume section — for each volume:

  • Capacity Consumed — how many bytes this volume has taken from the pool. Includes live files, snapshots, and metadata.
  • Quota — if set, the cap for this volume. Usually not set.

The Capacity Consumed values per volume sum to approximately Container Total Space - Container Free Space.

Detailed info for one volume

diskutil info /

Key fields:

  • Container Free Space — same as above, available pool free space
  • Volume Used Space — live files on this volume only

Purgeable space field

Some documentation references a “Volume Purgeable Space” field in diskutil info output. This field does not appear on all macOS versions or volume types. See APFS - Purgeable Space for what purgeable space is conceptually.

Listing all snapshots

You need the device identifier for the volume, not the mount path. Get it from diskutil apfs list — it looks like disk3s2.

# List all snapshots on the Data volume
diskutil apfs listSnapshots disk3s2
 
# List all snapshots on the System volume
diskutil apfs listSnapshots disk3s1

Each snapshot entry shows:

  • Name — who created it (Time Machine, backup tool, Apple OS mechanism)
  • Creation date
  • Purgeable: Yes/No — whether it can be auto-evicted

Deleting a specific snapshot

Time Machine snapshots:

tmutil deletelocalsnapshots YYYY-MM-DD-HHMMSS

Non-Time Machine snapshots (orphaned backup tool snapshots):

diskutil apfs deleteSnapshot disk3s2 -name "com.bombich.ccc.XXXXXXXX"

Do not delete SSV snapshots

Do not delete snapshots named com.apple.os.update-* — these are the SSV boot snapshot. Deleting them will prevent your Mac from booting.

Why diskutil is ground truth

diskutil bypasses the VFS layer entirely for these operations. It communicates directly with the APFS kernel extension via IOKit. When it reports Capacity Consumed for a volume, it’s reading the space manager’s actual block allocation tables — not walking a directory tree, not summing inode sizes. This is the same data source that Disk Utility.app uses.

See also

Graph View

Backlinks