How to free up disk space on a Mac: a developer's guide

A developer's Mac fills up differently from anyone else's. The photos and the downloads folder are rarely the problem. The problem is that every project you have ever built left several gigabytes behind, every package manager kept a copy of everything it downloaded, and every application on the machine has been writing to its own cache folder for years. Almost all of it regenerates. Very little of it needs to be there.

Where the space actually goes

Before deleting anything, it helps to know which categories are worth your attention. These are the ones that reliably run to gigabytes, and what each one costs you if you remove it:

The pattern is consistent: everything on that list is a cache or a build product. None of it is your work, and none of it is irreplaceable — the only cost of deleting it is time, paid once, the next time you build or install.

Finding it without guessing

macOS gives you About This Mac → Storage, which is close to useless for this: it buckets almost everything a developer cares about into “System Data” and offers no way to look inside. The usual next step is a manual tour with du -sh *, which works but takes an afternoon and misses anything outside the directory you happened to be standing in.

The alternative is a tool that already knows where these things live. purge is a command-line scanner for exactly this: one pass over your home directory, everything grouped and sized, nothing deleted until you say so.

brew install soummyaanon/tap/purge   # Homebrew — brings its own Node
npm i -g purge-cli                   # or npm, Node 22.18+
purge                                # or: purge-cli

# or, no install — always the newest version:
npx purge-cli@latest

It requires macOS. The Homebrew install brings its own Node; the npm install needs Node 22.18 or later. Either way it has zero runtime dependencies, makes no network calls, and sends no telemetry. The scan itself is read-only — you get a full picture of what is reclaimable before any decision is required.

What is safe to delete, and what is not

Safe, in almost every case

• Xcode DerivedData — build intermediates and indexes. Regenerated on the next build; deleting it is a standard fix for stale-build weirdness.
• node_modules in idle projects — fully reproducible from a lockfile. Weigh it by how long the project has sat untouched.
• Build output — .next, .turbo, dist, build, cargo target, Python virtual environments.
• Package-manager caches — npm, bun, Homebrew, Gradle, Playwright browsers, Electron distributions. These are download caches; clearing one means a re-download, nothing more.
• Application and log caches — every app rebuilds its cache folder on demand, and nothing rotates ~/Library/Logs for you.

Not safe, whatever a cleaner tells you

• Anything inside iCloud Drive, Dropbox, Google Drive or OneDrive — a deletion there syncs to every other machine you own.
• Browser profiles — passwords, bookmarks, history and open sessions live next to the caches, and the distinction is not obvious from the folder names.
• Coding-agent session history — ~/.claude/projects, ~/.codex/sessions and their equivalents. Resume and rewind stop working without them.
• Xcode Archives — these are shipped builds, not build junk.
• Anything tracked in git — a committed dist/ looks exactly like build output and is not.

Clearing it in one pass

Running purge with no arguments scans everything and drops you into a keyboard checklist. Rows are grouped, sized and sorted, and the footer keeps a running total of what you have selected:

• space toggles an item, or a whole group from its header
• tab hops to the next checkbox, skipping headers
• / filters by path, a selects all or none
• enter deletes what is checked; q leaves without touching anything

To look at one category only, name the groups: purge builds xcode. To get machine-readable output instead of the review screen, use purge --json.

Keeping directories permanently off-limits

Client work, a directory you never want a cleaner to see, a build cache you are deliberately keeping warm — put a glob in ~/.purgerc and it is never shown and never deleted:

{
  "keep": ["**/work/**", "~/Developer/client-project/**"],
  "staleDays": 90,
  "minSize": 25,
  "trash": true
}

staleDays sets how long a build directory must sit untouched before it is offered at all, and minSize is the megabyte floor below which items are not listed — both exist to keep the review screen short enough to actually read.

Undo, and a record

Run with --trash (or set "trash": true in ~/.purgerc) and nothing is deleted: every item is moved into ~/.Trash, instantly and unchanged. Empty the Trash when you are sure; run purge undo if you were not, and the last trash run goes back where it came from. Undo never overwrites a path that exists again and never moves anything that is not inside the Trash.

A plain run deletes for real, and purge writes a manifest of every run to ~/.purge/runs/: every path, its size, when it went and — for trash runs — where it went. If something you expected is missing a week later, purge history tells you whether it was this tool that took it.

Frequently asked questions

Try it

brew install soummyaanon/tap/purge   # or: npm i -g purge-cli, or: npx purge-cli@latest
purge                                # or: purge-cli

MIT-licensed and open source — the source is on GitHub, the package is on npm and in a Homebrew tap, and the landing page shows the review screen in action.