# A practical guide to Homebrew

> A practical guide to Homebrew on macOS, Linux, and WSL: install Homebrew, find packages, install formulae and casks, update, upgrade, and uninstall them.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2019-12-27 | Updated: 2026-07-18 | Topics: [CLI](https://flaviocopes.com/tags/cli/) | Canonical: https://flaviocopes.com/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](https://brew.sh/) is:

```bash
/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:

```bash
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](https://docs.brew.sh/Installation) 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:

```bash
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:

```bash
brew search ripgrep
```

Get details before installing:

```bash
brew info ripgrep
```

You can also browse formulae and casks at [formulae.brew.sh](https://formulae.brew.sh/).

## Install command-line tools

Install a formula with `brew install`:

```bash
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:

```bash
brew list --formula
```

## Install applications with casks

Casks install prebuilt applications and other macOS packages:

```bash
brew install --cask firefox
```

List installed casks:

```bash
brew list --cask
```

Some cask applications update themselves outside Homebrew. The [Homebrew FAQ](https://docs.brew.sh/FAQ) explains how that affects `brew upgrade`.

## Update Homebrew and installed packages

These commands do different jobs:

```bash
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:

```bash
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:

```bash
brew uninstall ripgrep
brew uninstall --cask firefox
```

Remove old downloads and package versions with:

```bash
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:

```bash
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](https://docs.brew.sh/Manpage), and locally with:

```bash
man brew
```