APFS Purgeable Space

What purgeable space is

APFS has a mechanism for marking allocated blocks as purgeable: they contain valid data, but the OS is permitted to delete them automatically under storage pressure because the data can be recovered (re-downloaded, re-derived, or is optional).

Purgeable space is allocated. It is not free. But the OS treats it as a reserve: under pressure, filecoordinationd and the storage management daemon will evict purgeable content to free real space.

What creates purgeable space

• Time Machine local snapshots — the biggest source by far. When TM creates a local snapshot, the blocks it retains are marked purgeable at the APFS level. If storage pressure occurs, the OS can delete old snapshots automatically. This is why local snapshots are a “soft” reserve, not a “hard” consumption.
• iCloud optimized storage — files that have been uploaded to iCloud and whose local copy is marked safe to evict.
• App Store re-downloadable content — downloaded apps/media that can be re-downloaded.
• Staged OS updates — the downloaded installer sitting in the Update volume.
• System caches that have registered themselves with the CacheDelete framework (Apple’s internal API for cache management).

How purgeable space breaks df

df on macOS inflates the “Available” column by including purgeable space. The kernel’s statvfs() implementation adds purgeable bytes to f_bavail. This means df -h says you have 200 GB free when your actual immediately writable free space might be 20 GB — the rest is purgeable blocks that look free but are actually allocated.

Finder and the “About This Mac” storage bar use a different API (NSURLVolumeAvailableCapacityForImportantUsageKey) that excludes purgeable space from the “available” figure. This is why Finder and df can show radically different available space numbers.

See macOS Disk Reporting for the full analysis.

Finding the real numbers

diskutil info /

Look for:

• Container Free Space — blocks truly free in the pool. Nothing is using them.
• Volume Used Space — blocks allocated to this volume’s live files.

"Volume Purgeable Space" may not exist

Some guides claim diskutil info shows a “Volume Purgeable Space” field. This field does not appear on all macOS versions or volume types. If it’s absent, purgeable space information is not directly exposed via diskutil info. The concept still exists at the APFS level, but there may not be a user-facing command to query it on your system.

The relationship: True writable free ≈ Container Free Space. Purgeable space is already allocated to something; the OS will only reclaim it if it needs to.

See also

• APFS - What It Is — purgeable space is an APFS-level concept
• APFS - Snapshots — Time Machine local snapshots are the biggest source of purgeable space
• macOS Disk Reporting — purgeable space is the main reason df inflates “Available”
• diskutil - The Ground Truth Tool — how to see the real numbers