Housekeeping for Homebrew

Here's how to keep Homebrew up to date and reduce disk usage.

Homebrew makes it easy to install programming languages and command-line utilities, so you may accumulate a disk full of tried-once and forgotten software. Make Homebrew housecleaning a regular habit to reduce clutter.

With the release of Homebrew 2.0.0 in February 2019, Homebrew began removing old packages automatically after running brew upgrade. It also runs brew cleanup every thirty days to remove packages that are no longer current. Expert users can disable automatic brew cleanup by setting an environment variable HOMEBREW_NO_INSTALL_CLEANUP=1 in the shell. Homebrew tries to keep your disk tidy but it is easy to accumulate packages you no longer need as well as recently outdated packages.

If you want to remove Homebrew entirely, see Uninstall Homebrew.

Before you get started

You'll need a terminal application to manage Homebrew. Apple includes the Mac terminal but I prefer Warp Terminal. Warp increases developer productivity, helping you remember easily-forgotten commands and adding troubleshooting with AI. Download Warp Terminal now; it's FREE and worth the effort.

Brew list

Use brew list to see all the packages in your local environment.

$ brew list

It will show dependencies as well as packages you've installed.

See Uninstall a Homebrew Package if you want to remove any packages you no longer use.

Brew outdated

The command brew outdated will list all installed packages that have a newer version available.

$ brew outdated

After running brew outdated, you can run brew upgrade to upgrade all packages or brew upgrade <package> to upgrade a specific package.

Brew upgrade (all packages)

The command brew upgrade will upgrade all installed packages.

$ brew upgrade

Be prepared for this command to take time (many minutes). Older versions of Homebrew had a brew upgrade --all option but the command has been simplified.

If you don't have time to upgrade all outdated packages, you can upgrade a specific package with brew upgrade <package>.

Brew update

The command brew update is for updating Homebrew itself, as well as the Homebrew core packages that are installed by default.

$ brew update

This updates Homebrew itself. It can take many minutes to run an update.

Homebrew core packages are updated as often as every day, so it is likely you will see updates.

Brew autoremove

The command brew autoremove will remove all unused dependencies remaining in the environment. If you've removed packages, it is likely that abandoned dependencies were left on disk if you didn't run brew autoremove immediately.

$ brew autoremove

Brew cleanup

Homebrew maintains a cache of downloaded packages so repeated installation goes faster. The command brew cleanup will remove outdated download files from the cache, as well as old versions of installed packages. By default, brew cleanup only removes files more than 120 days old. Force a more recent cleanup with --prune=all.

Unless the default has been changed by the user, the cached files are in ~/Library/Caches/Homebrew.

Run brew cleanup -n or brew cleanup --dry-run to see what will be removed without actually removing anything.

$ brew cleanup --prune=all --dry-run

If you like what you see, run brew cleanup without the --dry-run option.

$ brew cleanup --prune=all

Run brew cleanup after running brew upgrade to make sure old versions of packages have been removed.

That's Homebrew housekeeping! As a side effect of cleaning up after using Homebrew, you'll have a better understanding of how Homebrew works.