clenoGet cleno · $9.99

What brew cleanup removes, and what it leaves behind

brew cleanup deletes old versions of formulae you've upgraded, outdated downloads in Homebrew's cache, any download older than 120 days, and stale lock files. See what it would remove before it removes anything:

brew cleanup -n

Homebrew already runs cleanup by itself after installs and upgrades, so it often frees very little. On the Mac this guide was tested on, Homebrew took 7.5 GB and brew cleanup -n listed nothing to remove. The space was in installed packages, which cleanup never touches. Below: every cleanup option, then how to find and remove what really uses the space.

The cleanup commands

Preview

brew cleanup -n

Lists each file it would remove and the total it would free. It prints nothing when there's nothing to clean.

Clean up

brew cleanup

To clean up one package only, name it: brew cleanup node.

Go further

  • brew cleanup --prune=7 removes cache files older than 7 days instead of 120. --prune=all removes them whatever their age.
  • brew cleanup -s scrubs the cache, including downloads for the latest versions. Downloads for anything still installed stay.

Add -n to either one to preview it. On the test Mac, --prune=all would have freed 5.8 KB and -s 4.5 KB, out of a 44 MB cache.

Empty the whole download cache

This deletes every Homebrew download

Installed software keeps working. Anything you reinstall or upgrade downloads again. Run brew --cache first and check the path it prints is Homebrew's cache (usually ~/Library/Caches/Homebrew).

rm -rf "$(brew --cache)"

This is the command brew help cleanup itself suggests for removing downloads that cleanup keeps.

Homebrew already cleans up on its own

  • After brew install, brew upgrade and brew reinstall, Homebrew runs cleanup for those packages.
  • Every 30 days, one of those commands also runs it for everything.
  • Upgrading a formula removes its old version.
  • Downloads older than 120 days go.

So unless you've turned it off, there's usually little left for brew cleanup to do. Three settings change this, set with export in your ~/.zshrc:

  • HOMEBREW_NO_INSTALL_CLEANUP=1 stops the automatic cleanup. Old versions then pile up until you run brew cleanup.
  • HOMEBREW_NO_CLEANUP_FORMULAE=foo,bar keeps old versions of just those formulae.
  • HOMEBREW_CLEANUP_MAX_AGE_DAYS=30 changes the 120-day limit for downloads.

Where Homebrew's space actually goes

brew --prefix prints where Homebrew lives: /opt/homebrew on Apple silicon, /usr/local on Intel Macs. Measure it and the cache:

du -sh "$(brew --prefix)" "$(brew --cache)"

Then see which folders inside it are biggest:

du -hd1 "$(brew --prefix)" 2>/dev/null | sort -hr | head

And which formulae are biggest:

du -sh "$(brew --prefix)"/Cellar/* | sort -hr | head

On the test Mac, the 7.5 GB broke down like this (as du reports it):

  • share, 3.6G: the Flutter SDK, installed as a cask.
  • Cellar, 2.5G: 88 formulae. The biggest were boost (375M) and mysql (293M).
  • lib, 981M: 878M of it global npm packages in lib/node_modules, because Node came from Homebrew.
  • var, 244M: MySQL and PostgreSQL data.
  • .git, 166M: Homebrew's own code.
  • The download cache, 44M.

Cleanup only ever touches old versions, downloads and lock files. Everything above is software you installed or data you made, so the only way to shrink it is to remove what you don't use.

Free the space: remove what you don't use

Formulae nothing else depends on, usually the ones you installed on purpose:

brew leaves

Casks:

brew list --cask

On the test Mac, 17 of the 88 formulae were leaves; the other 71 were dependencies of something else installed.

Uninstalling removes the software

Anything that uses it stops working. Databases keep their data in $(brew --prefix)/var: export what you need before removing one, and don't delete folders in var by hand.

brew uninstall <name>

Then remove the dependencies nothing needs any more. Preview first:

brew autoremove -n
brew autoremove

If your Node came from Homebrew, global npm packages sit in lib/node_modules. List them with npm ls -g --depth=0 and remove one with npm uninstall -g <name>.

Where cleno fits

cleno doesn't run brew or look inside Homebrew's folder. Its Storage tab measures ~/Library/Caches, where Homebrew keeps its downloads, and lists the largest folders there next to every other app's cache, so you can see whether Homebrew's cache is worth clearing. Double-click a folder to show it in Finder. See what cleno does.

For space outside Homebrew, see how to find large files on a Mac and how to delete node_modules folders.