sodcalculator

10 Tech How-To

Install and Uninstall Homebrew on macOS

Guide 10-58078 · Updated · Step by step

Homebrew is the most widely used package manager for macOS, letting you install, update, and remove command-line tools and apps with simple commands like brew install wget. This guide walks you through the official installation and uninstallation process, explains what Homebrew actually does, and answers common questions about keeping it healthy.

What Homebrew Does and Why You Need It

macOS ships with a set of Unix tools, but many modern developer utilities—like git, python, ffmpeg, or node—are either outdated or missing entirely. Homebrew fills that gap by downloading pre-compiled binaries and managing their dependencies automatically. It installs everything into /opt/homebrew (on Apple Silicon) or /usr/local (on Intel), keeping your system files untouched. You interact with it through the brew command in Terminal.

Beyond command-line tools, Homebrew can also install GUI applications via brew install --cask firefox or brew install --cask visual-studio-code. This makes it a one-stop shop for both developer utilities and everyday apps, all updated with a single brew upgrade.

Prerequisites Before You Install

Before running the installer, make sure your Mac meets these requirements:

  • macOS Sonoma (14) or newer (older versions may still work but are not officially supported).
  • Command Line Tools for Xcode, which include compilers and other build essentials. The installer will prompt you to install them if they’re missing.
  • At least 2 GB of free disk space (more if you plan to install large packages).
  • An internet connection and a user account with administrator privileges.

You can check your macOS version by clicking the Apple menu → About This Mac. If you’re on an older system, you might still install Homebrew, but some formulae may require newer OS versions.

How to Install Homebrew (Official Method)

The official installer is a single command that you paste into Terminal. Here’s the step-by-step process:

  1. Open Terminal (found in /Applications/Utilities/).
  2. Paste the following command and press Enter:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  3. The script will explain what it’s about to do and ask for your password (it needs sudo to create the Homebrew directory). Type your password when prompted—it won’t show as you type, which is normal.
  4. If Command Line Tools are missing, the script will install them automatically. This can take several minutes.
  5. Once the script finishes, you’ll see a message like “Installation successful!” and a “Next steps” section that tells you to add Homebrew to your PATH.

On Apple Silicon Macs, the installer will tell you to run two commands to add /opt/homebrew/bin to your shell profile. On Intel Macs, the path is /usr/local/bin. Copy and paste those commands exactly as shown, then close and reopen Terminal.

To verify the installation, run brew --version. You should see something like Homebrew 4.4.0. Then run brew doctor to check for any configuration issues—it will warn you about missing dependencies or permissions that need fixing.

How to Uninstall Homebrew Completely

If you want to remove Homebrew entirely, the official uninstall script is the safest route. It removes the Homebrew installation, its caches, and the directories it created. Here’s how:

  1. Open Terminal.
  2. Run the uninstall script:
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
  3. The script will list what it plans to remove and ask for confirmation. Type y and press Enter.
  4. It may ask for your password again to delete system-level files.
  5. After it finishes, it will tell you to manually delete the Homebrew directory if it still exists. Run sudo rm -rf /opt/homebrew (or /usr/local on Intel) to remove any leftovers.

This process does not remove the packages you installed with Homebrew—it removes Homebrew itself. If you want to uninstall individual packages before removing Homebrew, use brew remove <formula> for each one, or brew autoremove to clean up unused dependencies. Some users prefer to keep a list of installed packages with brew list before uninstalling, so they can reinstall later.

Common Problems and How to Fix Them

Even with a smooth installer, you might run into issues. Here are the most frequent ones and their fixes:

  • “Command not found: brew” — This usually means Homebrew isn’t in your PATH. Check your shell profile (~/.zshrc for zsh, ~/.bash_profile for bash) and add the line export PATH="/opt/homebrew/bin:$PATH" (or /usr/local/bin on Intel). Then run source ~/.zshrc.
  • Permission errors during install — The installer needs write access to /opt/homebrew. If you see “Permission denied”, make sure you own the directory: sudo chown -R $(whoami) /opt/homebrew.
  • Homebrew is slow or times out — This often happens due to network issues. Try brew update --force or set a longer timeout with export HOMEBREW_CURL_RETRIES=5.
  • “Your system is ready to brew” but nothing works — Run brew doctor and follow its suggestions. It often points out missing dependencies or conflicting installations.

If you’re upgrading from an old Intel-based Homebrew to Apple Silicon, the cleanest path is to uninstall and reinstall with the new architecture. The installer script handles the switch automatically, but you may need to reinstall your packages.

Alternatives to Homebrew

Homebrew isn’t the only option. MacPorts is an older package manager that compiles from source—it’s more traditional but slower. Fink is another, though it’s less actively maintained. For Python-specific packages, pip is the standard; for Node.js, npm or yarn are common. However, these language-specific managers don’t handle system-level dependencies, which is where Homebrew shines. For most users, Homebrew is the recommended choice due to its large library and active community.

Frequently Asked Questions

Do I need to install Xcode to use Homebrew?

No, but you need the Command Line Tools for Xcode, which the installer will prompt you to install. These include compilers like clang and make that some formulae need to build from source. You don’t need the full Xcode app unless you’re developing for Apple platforms.

Will Homebrew slow down my Mac?

No. Homebrew itself runs only when you execute a brew command. It doesn’t start background processes or consume memory. The packages you install might, but that’s up to each tool.

Can I install Homebrew on an external drive?

Officially, no. Homebrew is designed to install to a fixed system path. You can set HOMEBREW_PREFIX to a custom location, but it’s not officially supported and can cause issues with dependencies. Stick with the default.

How do I update Homebrew and its packages?

Run brew update to update Homebrew itself, and brew upgrade to upgrade all installed formulae. You can upgrade a specific package with brew upgrade <formula>. It’s a good idea to run brew update regularly.

Is Homebrew safe to use?

Yes, but exercise caution. The official installer is safe, but be careful with third-party taps (repositories). Stick to the default homebrew/core tap and well-known taps like homebrew/cask. Always review what a formula does before installing if you’re unsure.

What’s the difference between brew install and brew install --cask?

brew install installs command-line tools and libraries. brew install --cask installs GUI applications like browsers, editors, and other apps that you normally drag to /Applications. Casks are managed by Homebrew but are separate from formulae.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →