Homebrew Package Manager

Homebrew cheatsheet — install packages, casks, taps, update, cleanup. brew install, brew upgrade, brew tap, brew cask install, brew doctor. Full macOS package management.

6 min read

What it is

Homebrew is a package manager for macOS and Linux that simplifies the installation of software, libraries, and command-line tools.

Installation

macOS

Open Terminal and run:

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

Linux

Open Terminal and run:

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

Follow the on-screen instructions, which will likely involve adding Homebrew to your PATH.

Windows (via WSL)

Install Windows Subsystem for Linux (WSL) first. Then, within your WSL distribution (e.g., Ubuntu), follow the Linux installation instructions.

Core Concepts

Formulae: These are Ruby scripts that define how to build and install a particular piece of software. They specify dependencies, source code locations, and build instructions.
Casks: These are used for installing macOS GUI applications that don’t have a command-line interface. They typically install .app bundles.
Taps: These are Git repositories that contain formulae and casks. Homebrew’s default tap is homebrew/core. You can add third-party taps for software not included in the default set.
Cellar: This is the directory where Homebrew installs packages (usually /usr/local/Cellar on macOS or /home/linuxbrew/.linuxbrew/Cellar on Linux). Each package is installed in its own versioned subdirectory.

Commands / Usage

Finding and Installing Software

Search for a formula or cask:
```
brew search wget
```
Searches for formulae and casks related to "wget".
Install a formula:
```
brew install git
```
Installs the "git" command-line tool.
Install a cask (GUI application):
```
brew install --cask google-chrome
```
Installs the Google Chrome application.
Install multiple packages:
```
brew install node python3
```
Installs both "node" and "python3".
Install a specific version of a formula:
```
brew install node@16
```
Installs version 16 of Node.js (if available as a versioned formula).

Managing Installed Software

List installed formulae:
```
brew list
```
Lists all installed command-line tools.
List installed casks:
```
brew list --cask
```
Lists all installed GUI applications.
Upgrade all outdated formulae:
```
brew upgrade
```
Upgrades all installed command-line tools to their latest versions.
Upgrade a specific formula:
```
brew upgrade git
```
Upgrades only the "git" command-line tool.
Upgrade all outdated casks:
```
brew upgrade --cask
```
Upgrades all installed GUI applications to their latest versions.
Upgrade a specific cask:
```
brew upgrade --cask firefox
```
Upgrades only the "firefox" application.
Uninstall a formula:
```
brew uninstall node
```
Removes the "node" command-line tool.
Uninstall a cask:
```
brew uninstall --cask visual-studio-code
```
Removes the Visual Studio Code application.
Uninstall all unused dependencies (cleanup):
```
brew autoremove
```
Removes formulae that were installed as dependencies but are no longer needed by any installed formulae.
Clean up old versions of installed formulae:
```
brew cleanup
```
Removes old versions of installed formulae, keeping only the latest.
Get information about a formula or cask:
```
brew info node
```
Displays detailed information about the "node" formula, including its version, dependencies, and installation path.
```
brew info --cask firefox
```
Displays detailed information about the "firefox" cask.
Reinstall a formula:
```
brew reinstall git
```
Uninstalls and then reinstalls the "git" formula.

Updating Homebrew Itself

Update Homebrew and formulae lists:
```
brew update
```
Fetches the latest version of Homebrew and updates the formulae and casks from all tapped repositories.
Check for issues and suggest fixes:
```
brew doctor
```
Runs a series of checks to diagnose potential problems with your Homebrew installation.

Managing Taps

List all installed taps:
```
brew tap
```
Lists the Git repositories (taps) that Homebrew is tracking.
Add a third-party tap:
```
brew tap jesseduffield/lazygit
```
Adds the "lazygit" formula from the "jesseduffield/lazygit" tap.
Remove a tap:
```
brew untap jesseduffield/lazygit
```
Removes the "jesseduffield/lazygit" tap and its associated formulae.

Advanced Usage

Install from a local formula file:
```
brew install ./my-formula.rb
```
Installs a formula defined in a local Ruby file.
Install from a URL:
```
brew install https://example.com/path/to/my-formula.rb
```
Installs a formula directly from a URL.
Link a formula (if it wasn’t linked automatically):
```
brew link node
```
Makes the executables of the "node" formula available in your PATH. Use brew link --overwrite node if there’s a conflict.
Unlink a formula:
```
brew unlink node
```
Removes the symlinks for the "node" formula from your PATH.
Get the installation path of a formula:
```
brew --prefix git
```
Prints the installation prefix for the "git" formula (e.g., /usr/local/Cellar/git/2.38.0).
Get the installation path of a cask:
```
brew --caskpath visual-studio-code
```
Prints the installation path for the "visual-studio-code" cask (e.g., /Applications/Visual Studio Code.app).
Generate a formula for a given URL:
```
brew creategit@2.38.0 https://github.com/git/git/archive/v2.38.0.tar.gz
```
Attempts to automatically generate a formula file for Git version 2.38.0.

Common Patterns

Update Homebrew, upgrade all packages, and clean up:
```
brew update && brew upgrade && brew cleanup
```
A common maintenance command to keep everything up-to-date and tidy.
Install a tool and then check its version:
```
brew install jq && jq --version
```
Installs the jq JSON processor and immediately verifies the installation.
Find where a command is installed:
```
brew --prefix node
```
Shows the directory where the node executable is located within the Homebrew cellar.
Install a development tool and its dependencies:
```
brew install cmake autoconf automake pkg-config
```
Installs common build tools often needed for compiling software from source.
Install a specific version of Python and create a virtual environment:
```
brew install python@3.9
python3.9 -m venv my_project_env
source my_project_env/bin/activate
```
Installs Python 3.9 via Homebrew, then creates and activates a virtual environment.

Gotchas

Permissions Issues: On macOS, if you installed Homebrew with sudo (which is not recommended), you might encounter permission errors. The standard installation avoids this by using your user’s permissions. If you run into issues, brew doctor is your first stop.
PATH Configuration: Homebrew usually adds itself to your PATH automatically. If commands aren’t found after installation, check your shell configuration files (.zshrc, .bash_profile, etc.) to ensure Homebrew’s bin directory is included. The output of brew doctor often points this out.
Cask vs. Formula: Remember that brew install is for command-line tools (formulae) and brew install --cask is for GUI applications. Mixing them up will lead to errors.
brew update vs. brew upgrade: brew update only updates Homebrew’s list of available formulae and casks. brew upgrade actually downloads and installs newer versions of your installed packages. You need to run both to get the latest versions.
Linking Issues: Sometimes, especially with multiple versions of a package installed, Homebrew might not automatically link the desired version to your PATH. You may need to use brew link <formula> or brew unlink <formula> to manage this. Use brew link --overwrite <formula> with caution if you have conflicting files.
Rosetta 2 on Apple Silicon: When running Homebrew on Apple Silicon Macs, some older formulae might still be compiled for Intel architecture. Rosetta 2 handles this translation, but performance might be impacted. Native Apple Silicon (ARM64) versions are preferred when available.