Homebrew cleanup: free space with brew cleanup and autoremove

What Homebrew keeps on your disk

Homebrew uses space in two places.

The prefix is where installed software lives: /opt/homebrew on Apple silicon Macs and /usr/local on Intel Macs. Inside it, Cellar holds every version of every formula you've installed, and Caskroom holds casks. When you upgrade a formula, the old version can stay in the Cellar until something cleans it up.

/opt/homebrew

Homebrew

Made by

Homebrew

What it is

Homebrew and every command-line tool and app you installed with it.

Does it come back?

Doesn't come back

Without it

brew and every tool it installed would stop working until you install them again.

The download cache holds the bottles and installers Homebrew fetched. On macOS it's ~/Library/Caches/Homebrew by default (Homebrew Docs). Every upgrade adds new downloads.

~/Library/Caches/Homebrew

Homebrew downloads

Made by

Homebrew

What it is

Downloads Homebrew kept after installing or upgrading packages.

Does it come back?

Comes back when it's needed

Without it

Homebrew downloads them again if it needs to reinstall something.

How to manage it

brew cleanup

To see how much each uses:

du -sh "$(brew --cache)" "$(brew --prefix)/Cellar" "$(brew --prefix)/Caskroom"

brew --cache and brew --prefix print the paths, so this works on both Apple silicon and Intel Macs.

What does brew cleanup do?

According to Homebrew's manual, brew cleanup does three things:

• removes stale lock files and outdated downloads for all formulae and casks
• removes old versions of installed formulae
• removes cached downloads more than 120 days old

The 120 days can be changed with the HOMEBREW_CLEANUP_MAX_AGE_DAYS environment variable. Give it formula or cask names and it cleans up only those.

Homebrew also cleans up on its own. Unless HOMEBREW_NO_INSTALL_CLEANUP is set, brew install, brew upgrade and brew reinstall clean up the formulae they touched, and every 30 days they clean up everything (HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS). That's why a manual cleanup sometimes frees little. On a Mac where Homebrew hasn't run for a while, or where automatic cleanup is turned off, it can free much more.

Run a Homebrew cleanup

1. 1

   See what cleanup would remove

   In Terminal, run brew cleanup --dry-run. It lists old versions and cached downloads it would remove, and how much space that frees, without removing anything.

2. 2

   Run the cleanup

   Run brew cleanup. It removes old versions of installed formulae, stale lock files and downloads older than 120 days.

3. 3

   Clear the rest of the download cache

   Run brew cleanup --prune=all to remove every cached download, not only old ones. Homebrew downloads them again if it needs to reinstall something.

4. 4

   Find dependencies nothing needs

   Run brew autoremove --dry-run. It lists formulae that were installed only as dependencies and are no longer needed.

5. 5

   Remove them

   If nothing on the list is a tool you use directly, run brew autoremove.

As commands:

brew cleanup --dry-run

brew cleanup

brew cleanup --prune=all

brew autoremove --dry-run

brew autoremove

The dry run prints a "Would remove" line for each old version and download, and ends with an estimate of how much disk space the real cleanup would free. If that estimate is small, Homebrew's automatic cleanup has already done most of the work.

brew cleanup and brew autoremove remove files directly. They don't use the Trash. That's fine for downloads and old versions, which Homebrew can fetch again, but read the dry-run output first.

Clean the Homebrew cache

brew cleanup keeps recent downloads. To clear the cache completely:

brew cleanup --prune=all

--prune takes a number of days, so --prune=7 removes cached files older than a week. There's also brew cleanup -s (scrub), which removes downloads even for the latest versions. The manual notes that downloads for installed formulae and casks still aren't deleted that way, and gives rm -rf "$(brew --cache)" for removing those too. That deletes the whole cache folder permanently. It's safe, since it only holds downloads, but --prune=all is usually enough.

Or use Finder, with the Trash as a safety net

Homebrew's commands remove files directly. If you'd rather go through the Trash, the cache is an ordinary folder:

1. In Finder, choose Go > Go to Folder, type ~/Library/Caches/Homebrew and press Return.
2. Select everything in it with ⌘A.
3. Press ⌘Delete to move it all to the Trash.

Installed formulae and casks don't depend on these files, so brew keeps working. Empty the Trash when you're ready to get the space back. If Homebrew needs an installer again, it downloads it.

Remove old versions of formulae

Old versions are what brew cleanup removes from the Cellar. To clean up one formula only:

brew cleanup python@3.13

If you rely on an older version of something, protect it before running cleanups. HOMEBREW_NO_CLEANUP_FORMULAE takes a comma-separated list of formulae that Homebrew will refuse to clean up or autoremove. Versioned formulae such as python@3.12 are separate formulae, so cleanup doesn't remove them.

Find the biggest formulae

To see which installed formulae use the most space, largest last:

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

A formula with several version folders inside its Cellar folder is one brew cleanup will shrink. A single large formula you never use is a candidate for brew uninstall.

Make Homebrew clean up more often

If you'd rather Homebrew kept less around, set its cleanup variables in your shell profile, such as ~/.zprofile:

export HOMEBREW_CLEANUP_MAX_AGE_DAYS=30
export HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS=7

The first makes cleanup remove downloads older than 30 days instead of 120. The second makes Homebrew's automatic full cleanup run weekly instead of every 30 days. Both are documented in Homebrew's manual. Open a new Terminal window for them to take effect.

Clean up unused Homebrew packages

Dependencies pile up. You install a tool, it brings ten libraries, and when you uninstall the tool the libraries stay. brew autoremove uninstalls formulae "that were only installed as a dependency of another formula and are now no longer needed," in the manual's words.

Always run it with --dry-run first. If you started using one of those dependencies directly, for example a library's command-line tool, it can still appear on the list.

For the packages you installed on purpose, list the top-level ones:

brew leaves --installed-on-request

Uninstall any you no longer use with brew uninstall <formula>, or brew uninstall --cask <cask> for apps. brew uninstall --zap also removes a cask's support files, but the manual warns it "may remove files which are shared between applications," so use it only for apps you're sure about. For apps installed outside Homebrew, see how to uninstall apps completely.

What brew cleanup doesn't touch

brew cleanup only knows about Homebrew's own files. It leaves alone:

• The current versions of everything you've installed
• Apps installed as casks in /Applications, and the data those apps keep in your Library
• Caches that Homebrew-installed tools create themselves, like npm's ~/.npm, pip's cache or Cargo's registry

Those belong to each tool and have their own commands. For JavaScript projects, see how to delete node_modules. Docker installed with Homebrew still keeps its images in its own disk image; see Docker taking up space.

What's safe to remove, and what isn't

Safe:

• The download cache (brew cleanup --prune=all, or ~/Library/Caches/Homebrew)
• Old versions of formulae you've upgraded
• Dependencies brew autoremove lists, after reading the dry run

Think first:

• An old version a project still needs. Add it to HOMEBREW_NO_CLEANUP_FORMULAE.
• brew uninstall --zap, which can remove files other apps share

Don't:

• Delete folders inside /opt/homebrew or /usr/local by hand. Homebrew tracks what's installed, and removing files behind its back breaks brew and the tools it manages. Use brew uninstall.

How MacClearings does it

MacClearings has a Suggestions rule for the Homebrew download cache. It's checked for you, because those downloads are safe to lose and Homebrew only fetches them again when it installs or upgrades something.

Suggestions rule · Package managers

Homebrew downloads

Installers Homebrew already used. Installed formulae and casks stay as they are.

• ~/Library/Caches/Homebrew

Checked for you, because it's safe to lose and doesn't come straight back.

That's all it touches. MacClearings doesn't remove old versions from the Cellar or uninstall dependencies: Homebrew keeps its own records of what's installed, so brew cleanup and brew autoremove are the right tools for those. The field guide in the Map marks /opt/homebrew as Homebrew itself, which doesn't come back if removed.

Checked items wait in the Cleanup tray until you open Review & Clean Up… and click Move to Trash. MacClearings checks each item again right before moving it, and every cleanup can be undone from History while the items are still in the Trash. MacClearings never empties the Trash, so the space comes back when you empty it.

History also measures the cache folder again after a day, a week and a month, so you can see how quickly your upgrades refill it. The developer page lists every package manager cache MacClearings knows about, from npm to Cargo.