Mac Purgeable Storage Explained (And Why Apple Does That)

You’re trying to download a 30 GB game. Finder says you have 47 GB free. The download fails three quarters of the way through with “not enough space.” You check again — still 47 GB free. What just happened is one of macOS’s quietest design choices: a big chunk of that “free” space wasn’t actually free. It was purgeable.

Purgeable storage is Apple’s clever — and occasionally maddening — system for letting your Mac use space for cached and synced content while pretending it’s available the moment something else needs it. Most of the time, it’s invisible and works. When it doesn’t, it produces some of the weirdest “out of space” errors on macOS.

What Counts as Purgeable

Purgeable storage is space holding files that macOS believes it can recreate or re-download on demand. The system tracks these files internally and frees them when free space drops below thresholds it picks. The big categories:

• iCloud Drive files with a “downloaded copy” but the canonical version is in iCloud
• Photos library when “Optimize Mac Storage” is on (full-resolution images cached locally)
• Apple Music and TV downloads marked offline-available but also in iCloud
• Mail attachments downloaded for searching but available on the server
• Time Machine local snapshots older than the most recent
• Spotlight metadata that can be reindexed
• Some Trash contents depending on how long they’ve been there

The system marks these with the file flag dataless or treats them as evictable cache. From your perspective, they’re files. From the disk’s perspective, they’re optional.

Why Apple Designed It This Way

The pre-purgeable model was harsh: if you had Photos with 500 GB of iCloud photos and a 256 GB Mac, you couldn’t keep your library on your computer at all. Either you stored locally and ran out of space, or you didn’t, and every photo took multiple seconds to fetch.

Purgeable storage is the compromise. macOS keeps as much locally as it can — recent photos, downloaded songs, frequently-opened iCloud Drive documents — and then automatically evicts the least-recently-used items when free space gets tight. From the user’s perspective, the photo library “just works” until disk pressure hits, at which point old photos quietly become thumbnails.

It’s a great idea when it works. It produces baffling failures when it doesn’t.

Power users use SweepSweep handles all the cleanup that articles like this describe. Get Sweep free →

How to See What’s Actually Free

The Storage bar in System Settings → General → Storage shows two numbers: “Available” and “Used.” But the Available number includes purgeable space. To see the truth:

df -h /

That’ll output something like:

Filesystem     Size   Used  Avail Capacity  iused      ifree %iused  Mounted on
/dev/disk3s5  926Gi  712Gi  201Gi    79%   3104102 2107536138    0%   /

The “Avail” number from df is closer to truly free space — it doesn’t include purgeable.

For an even more granular view:

diskutil info /System/Volumes/Data

Look for “Container Free Space,” “Volume Used Space,” and “Volume Available Space.” The container free space is the real “I can write this many bytes right now” number. Volume available is inflated by purgeable.

When Purgeable Lies

The system is supposed to evict purgeable files automatically before you ever notice. In practice, three failure modes:

1. The eviction is too slow for the operation. A big file copy or download wants space now, and macOS hasn’t had time to evict enough. The operation fails with a “not enough space” error even though space technically exists. Solving this means manually triggering the eviction or freeing real space.

2. Files marked purgeable that the system can’t actually purge. This happens when the cloud copy of a file is incomplete, when iCloud is paused, or when Photos has lost track of which versions are canonical. macOS thinks 30 GB is purgeable, tries to evict, and finds it can’t.

3. Apps that bypass the file APIs. Some apps write directly to the disk in ways that don’t trigger eviction. The classic example is virtual machine disk images — VMware, Parallels, and similar tools may pre-allocate huge files that the system doesn’t realize are filling space until it’s too late.

Triggering Eviction Manually

There’s no official “evict now” command, but you can force the system’s hand:

Empty Time Machine local snapshots:

sudo tmutil thinlocalsnapshots / 10000000000 4

That recovers up to 10 GB at urgency 4 (the most aggressive). Time Machine snapshots are a major purgeable category.

Force Photos to evict the local cache by quitting Photos and toggling “Optimize Mac Storage” off then on (you’ll temporarily push originals to iCloud, then get them back as the system has space).

Run a big file operation that genuinely needs the space. macOS will evict aggressively when it sees a write that won’t otherwise fit. Some users create a temporary 50 GB sparseimage just to scare the system into evicting:

hdiutil create -size 50g -fs APFS -volname Force /tmp/force.sparseimage

Mount it, write some data, delete it. The act of needing the space frees the purgeable.

What Counts as Purgeable on Your Mac Right Now

To see specific purgeable categories:

sudo /usr/libexec/PlistBuddy -c "Print" /Library/Preferences/com.apple.spaceman.plist 2>/dev/null

That’s not always populated, but when it is, it shows the system’s view of what’s reclaimable.

For a directory-by-directory view of “downloaded” iCloud Drive content:

brctl monitor com.apple.CloudDocs

brctl is the iCloud daemon’s diagnostic tool. It’ll print live status of files being uploaded, downloaded, and evicted. Run it for 30 seconds, hit Ctrl+C, and you’ll see what iCloud is doing in the background.

There’s a faster waySweep does this kind of cleanup automatically. Try Sweep free →

The Photos Library Specifically

Photos is the single largest source of purgeable storage on most Macs. With “Optimize Mac Storage” enabled in Photos → Settings → iCloud, the library size on disk is governed by:

• Available free space (more free space = more cached locally)
• Recent access patterns
• A floor of “thumbnail and metadata” data that’s never evicted

The library itself at ~/Pictures/Photos Library.photoslibrary looks huge in Get Info because Get Info doesn’t account for purgeable. The actual on-disk reality might be a fraction of that.

If you turn off “Optimize Mac Storage” with limited free space, Photos will warn you and refuse — it won’t try to download a 500 GB library onto a 256 GB SSD. If you have space, it’ll start pulling everything down, which can take days.

iCloud Drive’s File-on-Demand

iCloud Drive uses the same purgeable model. A file with a cloud icon next to it in Finder is “available but not downloaded.” A file without an icon is local. To force-download:

brctl download <file-path>

To force-evict (push back to cloud-only):

brctl evict <file-path>

These are useful when iCloud’s automatic evict-and-restore decisions don’t match what you actually need.

When Purgeable Hurts You

Three scenarios where purgeable’s behavior actively works against you:

1. Travel without internet. A file marked “downloaded but purgeable” can be evicted while you’re offline. You sit down at the airport, open the doc, and Finder says “this file isn’t available.” The eviction happened sometime in the last week and you didn’t notice.

To pin a file as downloaded, you can brctl pin it on macOS Sonoma+ (the syntax has shifted across versions; check brctl --help). Or right-click in Finder → “Keep Downloaded.”

2. App installs that report failure. A package installer pre-checks for free space using a measurement that doesn’t include purgeable. You’re “out of space” by the installer’s math even though the system has plenty.

3. Disk imaging and clones. Tools that clone block-by-block can copy purgeable files as if they were real, inflating the size of your clone. Use cp -R or rsync instead of disk-level cloning if this matters.

What to Do With This Knowledge

Purgeable storage is mostly a feature, not a problem. The mental model that helps:

• “Available” in System Settings is optimistic. Trust df -h / for real free space.
• If something fails with “not enough space” but Available looks fine, eviction was too slow. Free real space, then retry.
• Time Machine local snapshots are the chunkiest purgeable category. Thinning them is usually the fastest win.
• iCloud Photos and Drive use purgeable aggressively. That’s the deal — your library is bigger than your disk in exchange for occasionally needing to wait for a download.

For most people on most days, purgeable is invisible and works. Knowing what it is gives you a path when it doesn’t.