Homebrew

Written & tested for accuracy by a developer (not AI)

Housekeeping for Homebrew

Homebrew housekeeping on a Mac: brew outdated, brew upgrade for all packages, brew autoremove and brew cleanup to free the disk space old versions take up.

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

Homebrew makes it easy to install apps, 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.

Homebrew housekeeping is part of maintaining your Mac. See the guide to set up a Mac.

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.

Brew doctor

Run brew doctor now and then to check your Homebrew setup.

$ brew doctor
Your system is ready to brew.

If it finds a problem, it shows a warning with an explanation and, usually, a suggested fix. One warning often appears weeks after a new install, once you've installed git or python3 with Homebrew:

Warning: /usr/bin occurs before /opt/homebrew/bin in your PATH.
This means that system-provided programs will be used instead of those
provided by Homebrew.

The following tools exist at both paths:
  git

The $PATH is the list of folders the shell searches for commands, in order. Since June 2025, Homebrew's install script adds Homebrew's folder, /opt/homebrew/bin, to the end of the $PATH, after Apple's /usr/bin. That is enough to find brew. But when you install a command that macOS also has, the shell finds Apple's copy first, so git --version shows Apple's version, not the one you installed. A new install passes brew doctor, because no command is yet in both places, so the warning appears only later.

To fix it, add Homebrew's shellenv line to your ~/.zprofile file, which puts Homebrew's folder first:

$ echo >> ~/.zprofile
$ echo 'eval "$(/opt/homebrew/bin/brew shellenv zsh)"' >> ~/.zprofile

Open a new Terminal window and run brew doctor again. See Install Homebrew for what the line does, and Mac PATH for how the shell builds the $PATH. If brew itself isn't found, see zsh: command not found: brew.

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. See a list of Best Homebrew Packages and Apps.