brew cleanup on Mac: free space from Homebrew caches and old versions

By Pruneo TeamPublished: October 22, 2026Updated: October 25, 2026

If you use Homebrew every day, it slowly collects files you never see: downloaded bottles and cask installers, old versions of formulae you upgraded, and dependencies left behind after you uninstalled the tool that needed them. Homebrew has its own commands to clean all of this, and they are the safest way to do it. This guide explains each one, what it removes and what you lose.

All commands below are documented in the official Homebrew manpage and the Homebrew FAQ.

What takes space in Homebrew

There are three main places:

1. The download cache. Every bottle (precompiled package) and every cask installer (.dmg, .pkg, .zip) that Homebrew downloads is kept here. On macOS the default path is ~/Library/Caches/Homebrew, as the HOMEBREW_CACHE entry in the manpage says.
2. Old versions in the Cellar. When you upgrade a formula, the new version is installed next to the old one. Homebrew normally removes the old one, but if automatic cleanup is off, versions pile up.
3. Orphan dependencies. If you install ffmpeg and later uninstall it, the libraries it pulled in can stay installed even though nothing uses them.

Step 1: measure before you delete

Before you remove anything, check how big each part is. These commands only read:

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

brew --cache prints the download cache folder (“Display Homebrew’s download cache”, in the manpage). du -sh shows its size. The second du shows the size of the Cellar, where installed formulae live. Most of the Cellar is software you use, so do not delete it by hand.

To see which formulae have more than one version installed:

brew list --versions

A line with two or more version numbers means older versions are still on disk.

Step 2: preview with brew cleanup -n

brew cleanup has a dry run mode. The manpage describes -n, --dry-run as “Show what would be removed, but do not actually remove anything.”

brew cleanup -n

You get a list of files and folders and, at the end, an estimate of the space it would free. Read it: if you see a version of a formula you still need (for example, an old python@ or node@ version a project depends on), stop and keep it (see the section on automatic cleanup below).

Step 3: run brew cleanup

brew cleanup

According to the manpage, brew cleanup will “Remove stale lock files and outdated downloads for all formulae and casks, and remove old versions of installed formulae.” By default it removes downloads more than 120 days old. You can change that limit with HOMEBREW_CLEANUP_MAX_AGE_DAYS.

You can also clean a single formula or cask:

brew cleanup wget

Step 4: empty the whole cache with –prune=all

The normal brew cleanup keeps recent downloads. If you want to empty the cache completely, use --prune. The manpage says it will “Remove all cache files older than specified days. If you want to remove everything, use --prune=all.”

Preview first:

brew cleanup -n --prune=all

brew cleanup --prune=all

There is also -s, --scrub, which will “Scrub the cache, including downloads for even the latest versions.” For most people --prune=all is enough.

Step 5: remove unused dependencies with brew autoremove

brew autoremove uninstalls “formulae that were only installed as a dependency of another formula and are now no longer needed” (manpage). It also has a dry run:

brew autoremove -n

Check the list. If you see a formula you use directly (for example, you started using openssl or python on your own after another tool installed it), add it to HOMEBREW_NO_CLEANUP_FORMULAE (explained below): the manpage says Homebrew “will refuse to clean up or autoremove a formula if it appears on this list.”

brew autoremove

How automatic cleanup works

Homebrew already cleans up for you, which is why many Macs never build up much. The manpage explains that after brew install, brew upgrade and brew reinstall, unless HOMEBREW_NO_INSTALL_CLEANUP is set, “brew cleanup will then be run for the installed formulae and casks or, every 30 days, for all packages.” The 30 days come from HOMEBREW_CLEANUP_PERIODIC_FULL_DAYS, which you can change.

The FAQ adds that Homebrew automatically uninstalls old versions of a formula when you upgrade it with brew upgrade.

Useful variables, all documented in the environment section of the manpage:

When to keep old versions

If a project needs an exact version, turning off cleanup for everything is usually too much. A better option is to protect only that formula. Add this line to your ~/.zprofile (or the file your shell reads):

export HOMEBREW_NO_CLEANUP_FORMULAE="postgresql@16,node@20"

Change the names to the formulae you want to protect. If you set HOMEBREW_NO_INSTALL_CLEANUP=1, remember that space will grow until you run brew cleanup yourself.

Why you may have many old versions

If brew list --versions shows many versions, check whether HOMEBREW_NO_INSTALL_CLEANUP is set in your shell files:

grep -n HOMEBREW_ ~/.zprofile ~/.zshrc 2>/dev/null

It is common to copy it from a tutorial to make installs faster and then forget about it.

A safe routine

Once a month, or when your disk is getting full:

1. du -sh "$(brew --cache)" to see the size.
2. brew cleanup -n, read the list.
3. brew cleanup.
4. brew autoremove -n, read the list, then brew autoremove if it looks right.
5. Only if you need more space: brew cleanup --prune=all.

Do not delete folders inside the Cellar or the Homebrew prefix (/opt/homebrew on Apple Silicon, according to the installation page; run brew --prefix to see yours) by hand. Homebrew keeps links and records for each package, and removing files directly can leave broken links. Use brew uninstall instead.

Homebrew is rarely the biggest thing on a developer’s Mac. If you still need space, look at Xcode DerivedData, Docker and node_modules folders, which tend to grow much faster.

Summary

• brew cleanup -n shows what would be removed, without deleting.
• brew cleanup removes old versions and downloads older than 120 days.
• brew cleanup --prune=all empties the whole download cache.
• brew autoremove uninstalls dependencies nothing needs; preview it with -n.
• HOMEBREW_NO_INSTALL_CLEANUP turns off automatic cleanup, and HOMEBREW_NO_CLEANUP_FORMULAE protects specific formulae.

For a full picture of where your space goes, read how to free up space on Mac, or download Pruneo to see it in a few seconds.

FAQ