Homebrew is one of the few package managers on macOS that ships with a decent built-in cleanup command, and yet its cache still catches people out — mostly because brew cleanup on its own does less than most people assume. Here is what it actually removes, what it leaves behind, and the flag that closes the gap.
Where Homebrew's cache lives
Homebrew downloads every formula's source tarball or precompiled bottle to ~/Library/Caches/Homebrew before installing it. This is separate from the installed software itself, which lives under /opt/homebrew on Apple Silicon or /usr/local on Intel Macs. The cache is purely the downloaded install artefacts — the equivalent of npm's tarball cache, but for system packages.
Check the size directly:
du -sh ~/Library/Caches/Homebrew
On a Mac that has installed and upgraded a lot of formulae over a few years, this routinely reaches several gigabytes, because by default Homebrew does not delete old download artefacts the moment a formula is upgraded.
What brew cleanup actually does
brew cleanup
This removes cached downloads for formula and cask versions that are older than the currently installed version, plus old versions of formulae themselves if a newer one has replaced them, plus Homebrew's own internal log files past a certain age. Crucially, by default it only removes items older than 120 days, unless the formula in question has already been superseded by an upgrade. This default staleness threshold is why a brew cleanup run can look like it did nothing — it is deliberately conservative.
You can preview what it would do without deleting anything:
brew cleanup --dry-run
--prune=all: the flag that changes the outcome
brew cleanup --prune=all
This overrides the 120-day default and removes every eligible cached download regardless of age, not just ones tied to an upgrade. If your goal is reclaiming disk space right now rather than keeping a rolling buffer of recent downloads for potential rollback, this is the version of the command you actually want. It is the single biggest lever in Homebrew's own tooling for freeing space.
Running brew cleanup -s additionally scrubs the cache of any cached bottles for formulae that are no longer installed at all, not just old versions of currently installed ones.
brew autoremove: a different kind of cleanup
brew autoremove
This does not touch the download cache. Instead, it removes formulae that were installed automatically as a dependency of something else, but are no longer required by anything currently installed — the equivalent of apt autoremove on Linux. If you installed a tool that pulled in openssl@3 as a dependency, then later uninstalled that tool, openssl@3 stays behind until you run autoremove, even though nothing depends on it any more.
Recent Homebrew versions run autoremove automatically as part of brew cleanup, but it is worth running explicitly and separately if you want to see exactly what it identifies as orphaned before it happens:
brew autoremove --dry-run
The difference in one table
| Command | Removes | Scope |
|---|---|---|
brew cleanup |
Old cached downloads (120+ days, or superseded by upgrade) | Cache + old formula versions |
brew cleanup --prune=all |
All eligible cached downloads regardless of age | Cache |
brew autoremove |
Installed formulae no longer needed as a dependency | Installed packages, not the cache |
brew uninstall <formula> |
One specific formula you choose | Installed packages |
None of these touch formulae you installed directly and are still using — Homebrew is conservative about removing anything you asked for by name.
Casks and Homebrew's other quiet space costs
If you install GUI applications through brew install --cask, the downloaded .dmg or .pkg installers go through the same cache and are cleaned by the same brew cleanup command. Casks tend to be larger individually than command-line formula bottles — a browser or IDE installer can be several hundred megabytes — so a Mac that has installed and upgraded a handful of cask applications over time often has a disproportionate share of ~/Library/Caches/Homebrew taken up by just two or three of them.
Homebrew's own log and cache housekeeping settings
Homebrew exposes a couple of environment variables that change this behaviour by default rather than requiring you to remember flags every time. Setting HOMEBREW_CLEANUP_MAX_AGE_DAYS in your shell profile lets you lower the 120-day default threshold globally, so routine brew cleanup runs (including the automatic cleanup Homebrew occasionally triggers on its own after an install or upgrade) are more aggressive without needing --prune=all every time. There's also HOMEBREW_NO_INSTALL_CLEANUP, which disables Homebrew's automatic post-install cleanup entirely if you'd rather control exactly when cleanup runs — useful on a machine where you want predictable timing rather than a cleanup pass sneaking into the middle of an unrelated brew install.
Neither setting is necessary for the article's main recommendation to work, but they're worth knowing if you find yourself running brew cleanup --prune=all by hand often enough that automating the threshold makes sense.
Checking what's actually installed versus what's just cached
It's easy to conflate "installed" with "cached" when looking at Homebrew's footprint. brew list shows what's currently installed and usable; the cache described in this article is a separate, purely historical record of what's been downloaded, some of which may correspond to formulae you've since uninstalled entirely. Running brew cleanup -s clears exactly this category — cached bottles for formulae that aren't installed at all any more — which is easy to overlook if you only ever run the bare brew cleanup command and assume it covers everything.
A sensible routine
brew cleanup --dry-runto see what a normal run would remove.brew cleanup --prune=allto actually reclaim the space, including anything under the 120-day default threshold.brew autoremove --dry-runfollowed bybrew autoremoveto clear dependency formulae nothing needs any more.du -sh ~/Library/Caches/Homebrewafterwards to confirm the win.
Running this combination every few months keeps the cache from silently accumulating gigabytes of superseded downloads you will never install again.
Where VolumeLens fits in
Homebrew's own cleanup commands do a reasonable job once you know to run --prune=all instead of the bare command, but they can only tell you about Homebrew's own footprint — not how it compares to everything else competing for space on your Mac. VolumeLens scans your whole disk and shows ~/Library/Caches/Homebrew sized honestly next to your Xcode data, your Docker images, and every other cache on the machine, so you know whether Homebrew is actually worth chasing before you spend time on it. Download it and see the full picture in one scan.