three free-space numbers, one disk, and none of them is lying

what purgeable space is, and what it is not

purgeable space is the total of files macOS has agreed it may delete on its own, without asking, the moment something needs the room. local Time Machine snapshots. photos and iCloud Drive files whose full copy is in the cloud and whose local copy is a convenience. caches an app has flagged as rebuildable. it is counted as used, because it is used — the blocks hold data — and counted as available, because the system has a standing permission to take it back.

what it is not is a folder. there is no purgeable directory, and there is no attribute on the disk that marks a block as expendable. this is the part that makes the number behave strangely, so it is worth being precise about.

the categories themselves — snapshots, the hidden volumes, which volume to run tmutil against — are on the page about the number they hide inside: what «system data» is actually using

no flag on the file: who keeps the list

APFS itself has no notion of purgeable. the file system knows a block is allocated or free, and that is all df, diskutil and every POSIX tool can ask it. the list of what could be freed lives one layer up, in a system service called CacheDelete — the deleted daemon — which keeps a registry of providers, each responsible for one kind of disposable data, and asks them how much they could give back if pressed.

so purgeable space is not a measurement of the disk. it is a sum of promises from a handful of services, refreshed on a schedule, and what Finder shows you as available is free blocks plus that sum.

the providers, the log entries and the phases of a purge, traced on macOS 26: eclecticlight.co — caches and purging in macOS Tahoe

what registers as purgeable

• local Time Machine snapshots, when they exist — which needs a backup destination configured. on the Mac measured here there were none, and purgeable space was 7.39 GB regardless.
• optimised storage: Photos with «Optimise Mac Storage» on, iCloud Drive files that can be evicted to a placeholder, Music and TV downloads. the cloud holds the original; the local copy is on loan.
• caches that macOS knows how to rebuild — the system's own, and any third-party file whose app has set the isPurgeable resource flag on it. an app that never sets it is invisible to the purge, however large its cache.
• and a thing snapshots make worse rather than better: a file you deleted stays on disk until every snapshot that references it has expired. deleting it freed nothing, and the space shows up as purgeable instead of free.

the flag an app sets to volunteer a file: isPurgeableKey — Apple Developer

who purges it, and when: on request, not on a threshold

the common picture is a watchdog: the disk crosses some percentage, macOS wakes up and starts deleting. that is not how it works, and the difference explains most of the confusion.

the purge is triggered by a demand. an app about to write something large asks the system, through a resource key called volumeAvailableCapacityForImportantUsage, how much room it can count on. that key returns free blocks plus purgeable, and asking it is what starts the machinery: deleted checks whether the promise can be kept, and if the write goes ahead and needs the room, it works through its providers in rounds of rising urgency — snapshots thinned first, then caches, until the goal is met. copying a file in Finder is a request. a macOS update is a request. a process writing to a log is not.

Apple's own distinction between the two questions an app can ask — space for something the user wants now, or space for something speculative: checking volume storage capacity — Apple Developer

why «disk full» appears on a disk that says it has room

this is the whole mechanism behind the forum thread titled «disk full but it isn't». the Storage screen and Finder show available space, which includes the promise. an installer or a build tool that checks free space the POSIX way — df, statfs, a plain write that fails — sees only the blocks, and never made the request that would have cashed the promise. both are right. one of them asked a question the other cannot hear.

the same thing in reverse: you delete ten gigabytes, df goes up by ten, Finder barely moves — because those files were already counted as purgeable, and Finder had been showing you the room all along.

a cleaner that reports purgeable space as reclaimable is counting that promise as a gain — the arithmetic of the number it shows, measured: what the space a cleaner finds is made of

the reserve below df: the third number

there is a second key, volumeAvailableCapacityForOpportunisticUsage, meant for things an app would like to download but nobody asked for — the next episode, a prefetched update. on this Mac it reports 28.23 GB against df's 36.48: eight gigabytes lower than the blocks that are actually free. macOS keeps a reserve it will not hand to speculative writes, so that an important one always has somewhere to go.

so the three figures from the lead are one measurement and two policies. free blocks; free blocks plus what can be purged for something important; free blocks minus what is held back from something optional. three questions, one disk.

why df, Finder and the storage screen show different free space

with the mechanism in hand, the tools sort themselves out: each asks the file system, asks CacheDelete, or keeps an old copy of the answer.

the Finder figure is cached

Finder's number is the one people quote, and it is the least current of the four. it does not read CacheDelete on every glance; it reads a stored value and refreshes it when something nudges it, which is why emptying the Trash can leave Get Info unchanged for a while and why a reboot appears to «fix» free space. nothing was fixed. a cache was dropped.

if you want a figure that means something right now: df for the blocks, Disk Utility for the blocks and the promise side by side.

which tool reads which source, with the daemon's own figures alongside: eclecticlight.co — where does macOS get its free space figures from?

one of the providers is the swap volume, and when that is what keeps growing, the disk is the symptom rather than the problem: fix «your system has run out of application memory»

the other way a disk lies: clones and shared space

purgeable explains why available runs ahead of free. there is a second disagreement, in the opposite direction, and it comes from the file system rather than from any daemon: folders adding up to more than the disk holds.

du says three gigabytes, df lost two

a small experiment on the same Mac. write one gigabyte of random data to a file. duplicate it with cp -c, which is what Finder's Duplicate and ⌘D do on APFS. copy it again with a plain cp. now du reports 3.0 GB for the folder, and df has dropped by 2.1 GB. the clone cost nothing: it shares every block with the original, and will keep sharing them until one of the two files is edited, at which point only the changed blocks get their own copy.

du, Finder's folder sizes and every «what is taking space» scan count each file at its full length. the disk charges once. so the folder-by-folder total can exceed what the disk says is used, and deleting a clone can free nothing at all.

one container, several volumes

the last piece is that your Mac's disk is not one volume. it is a container holding several — the sealed system, your data, Preboot, Recovery, VM for swap — and they draw from one pool of free space. run diskutil apfs list and each volume shows the whole container's free space as its own, because that is genuinely what each could grow into. the total is not the sum of the parts, by design.

Apple on space sharing: the container allocates on demand, and available is the container minus every volume in it: file system formats available in Disk Utility — Apple Support

when the scan does find a real folder — an app's leftovers rather than a clone of something you kept — that is the part a tool can act on: the uninstaller in hop, and what it leaves alone

how to get purgeable space back, and what is theatre

most advice for «clearing» purgeable space does nothing or does something else. the mechanism tells you which.

• make the request. copy a large file onto the disk, or start the export you needed the room for. that is the signal the purge waits for, and it releases exactly as much as the job needs. this is the intended path, and it is why purgeable exists — you were never going to be refused.
• thin snapshots directly: tmutil thinlocalsnapshots /System/Volumes/Data 20000000000 4 asks for twenty gigabytes at the highest urgency, and it is the same call the daemon makes. only useful if you have snapshots — check with tmutil listlocalsnapshots on the data volume first.
• turn off optimised storage in Photos or iCloud Drive if you want the local copies to stay local. that does not free space; it converts purgeable into ordinary used, which is the opposite of what most people mean.
• rebooting refreshes Finder's cached figure and drops some caches. it does not purge anything. if the number improves, it was stale, not full.
• restarting Time Machine, the fix that circulates most, drops the local snapshots as a side effect — they were going to expire within twenty-four hours anyway.

the retention rules for local snapshots and the condition for having any: about Time Machine local snapshots — Apple Support

if the thing taking room is neither purgeable nor a clone but an app you removed months ago, that is a different job with its own rule about bundle identifiers: uninstall an app with its leftovers

and if the disk is full enough that swap has nowhere to go, the warning you get is about memory, not storage — the reading behind it: what memory pressure actually measures

frequently asked questions

what is purgeable space on a Mac?

files macOS has permission to delete on its own when something needs the room: local Time Machine snapshots, cloud-backed photos and documents whose local copy is optional, and caches flagged as rebuildable. it counts as used and as available at the same time.

is purgeable space safe to delete?

it is safe by definition — the system would delete it itself. the point is that you do not need to: it is released automatically when an app asks for space. removing it by hand gains nothing you were going to be denied.

how do i clear purgeable space on Mac?

start the job you need the space for; the purge is triggered by the request. if you have local snapshots, tmutil thinlocalsnapshots on /System/Volumes/Data releases them directly. rebooting only refreshes the displayed figure.

why does Finder show more free space than Disk Utility or df?

Finder shows free space plus purgeable, from a cached value. df shows only free blocks, because the file system has no idea what is purgeable. Disk Utility shows both separately. none of them is wrong; they are answering different questions.

why does my Mac say the disk is full when it isn't?

the app that failed checked free blocks and found none, while Finder was showing you available space that includes purgeable. the purge only runs when something asks for space through the system's own API, and many tools never ask.

does restarting clear purgeable space?

no. a restart drops Finder's cached figure and some caches, so the number often changes, but nothing is purged. the purge needs a request for space.

does purgeable include Time Machine snapshots?

yes, when they exist — which requires a backup destination and automatic backups on. without Time Machine there are no snapshots, and purgeable space still exists: on the Mac measured here it was 7.39 GB with zero snapshots.