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 is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.
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.
What's next
My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.