A practical guide to Homebrew

Homebrew is a package manager for macOS, Linux, and the Windows Subsystem for Linux.

It installs command-line tools as formulae and applications, fonts, and plugins as casks. You manage both with the brew command.

Install Homebrew

The current install command from the Homebrew homepage is:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script explains what it will change and pauses for confirmation. Read it before approving it, especially because it downloads and runs code from the network.

On macOS, Homebrew also provides a .pkg installer from its official GitHub releases.

At the end of the installation, follow the printed instructions for adding brew to your shell environment. Then verify the installation:

brew --version
brew doctor

brew doctor reports possible problems. You do not have to fix every warning if Homebrew otherwise works, but read what it says.

The installation documentation lists the supported platforms and prerequisites.

Where Homebrew installs files

Do not assume Homebrew is in /usr/local.

The default prefix depends on the platform:

• /opt/homebrew on Apple Silicon macOS
• /usr/local on Intel macOS
• /home/linuxbrew/.linuxbrew on Linux and WSL

Ask Homebrew for the actual paths on your machine:

brew --prefix
brew --cellar
brew --caskroom

Each formula is installed in its own directory inside the Cellar. Homebrew then links its commands into the prefix.

Find a package

Search from the terminal:

brew search ripgrep

Get details before installing:

brew info ripgrep

You can also browse formulae and casks at formulae.brew.sh.

Install command-line tools

Install a formula with brew install:

brew install ripgrep

Homebrew usually downloads a prebuilt package called a bottle. If a compatible bottle is unavailable, it may build the formula from source.

List installed formulae:

brew list --formula

Install applications with casks

Casks install prebuilt applications and other macOS packages:

brew install --cask firefox

List installed casks:

brew list --cask

Some cask applications update themselves outside Homebrew. The Homebrew FAQ explains how that affects brew upgrade.

Update Homebrew and installed packages

These commands do different jobs:

brew update
brew outdated
brew upgrade

brew update refreshes Homebrew and its package definitions.

brew outdated shows installed packages with newer versions available.

brew upgrade upgrades outdated packages. To upgrade one package:

brew upgrade ripgrep

Homebrew may automatically update its package data before commands such as brew install and brew upgrade, but running the commands explicitly makes the sequence clear.

Uninstall packages

Remove a formula or cask with:

brew uninstall ripgrep
brew uninstall --cask firefox

Remove old downloads and package versions with:

brew cleanup

Use brew cleanup --dry-run first if you want to see what would be removed.

Useful diagnostic commands

When something does not work, start with:

brew info PACKAGE
brew doctor
brew config

brew config prints useful environment information for bug reports.

The complete command reference is available in the Homebrew manual, and locally with:

man brew

Related posts about cli: