Getting Started with Homebrew on macOS

The command line is a text-based way to interact with your machine, and developers lean on it heavily to automate workflows. While macOS shares a lot of DNA with other Unix-like systems, it ships without a built-in package manager. Homebrew fills that gap — it's a , open-source tool that lets you developer essentials like Python, Ruby, and Node.js directly from the terminal.

This guide walks you through the entire process: ing Xcode's Command Line Tools as a prerequisite, running the Homebrew setup script, managing packages, ing graphical apps via Homebrew Cask, and cleanly removing Homebrew if you ever need to.

To reach the command line, open the Terminal app. You can find it through Finder → Applications → Utilities → Terminal, or more quickly by pressing ⌘ Space to open Spotlight and typing Terminal.

Once Terminal is open, you have a fully functional Unix shell at your disposal. If you're new to the command line, familiarising yourself with basic Linux/Unix concepts will make everything in this guide much easier to follow.

With Terminal running, the next step is to Homebrew's primary dependency.

Xcode is Apple's official IDE for building software across its platforms. Even if you don't plan to use Xcode itself, its Command Line Tools package provides essential compilers and utilities that Homebrew depends on.

Run the following in Terminal to kick off the ation:

xcode-select --

A dialog will appear asking you to confirm and accept the software license. The ation then proceeds automatically — no further input required.

Once that finishes, your system is ready for Homebrew.

ing Homebrew is a two-step process: the ation script, inspect it, then execute it.

First, the script using :

 -fsSL -o .sh https://raw.githubusercontent.com/Homebrew//HEAD/.sh

The flags used with each serve a specific purpose:

• -f / --failSuppress HTML error output from the server on failure.
• -s / --silentHide the progress meter during the .
• -S / --show-errorCombined with -s, still display error messages if something goes wrong.
• -L / --locationAutomatically follow HTTP redirects to the final destination.
• -o <file>Save the output to a local file rather than printing it to the screen.

Before running any script ed from the internet, inspect its contents first:

less .sh

Once you're confident in what the script will do, execute it with bash:

/bin/bash .sh

The script will summarise its planned actions and ask for your confirmation before making any changes. You'll also be prompted for your password — note that characters won't appear as you type, which is standard security behaviour. Press Return when done, and type y to confirm any prompts.

Configure your PATH

After ation, add Homebrew's binary directory to your PATH so your shell can find packages ed through it. First, check which shell you're using:

echo $0

Open the appropriate configuration file — ~/.zshrc for Zsh (default on modern macOS) or ~/.bash_profile for Bash:

# Add Homebrew's executables to the front of PATH
export PATH=/usr/local/bin:$PATH

Save the file (Ctrl+O then Return in nano, then Ctrl+X to exit), then reload your shell config:

source ~/.zshrc

Confirm everything is working correctly:

brew doctor

Your system is ready to brew.

If you receive a suggestion to run brew update or another command, follow the on-screen instructions before continuing.

With Homebrew ready, try ing a package. The tree command displays directory structures visually and makes for a good first test.

brew  tree

Updating Homebrew...

==> ing tree-1.8.0.catalina.bottle.tar.gz
######################################################################## 100.0%
==> Pouring tree-1.8.0.catalina.bottle.tar.gz
🍺  /usr/local/Cellar/tree/1.8.0: 8 files, 117.2KB

Homebrew s files to /usr/local by default, which keeps them separate from system directories and avoids interference with macOS updates. Verify the location with:

which tree

/usr/local/bin/tree

Confirm the version as a final sanity check:

tree --version

To upgrade a specific package, pass its name to brew upgrade. Omitting the name upgrades everything Homebrew manages:

brew upgrade tree     # upgrade one package
brew upgrade          # upgrade all packages

Homebrew retains older versions after an upgrade. up disk space by removing them with brew cleanup.

To remove a package entirely:

brew un tree

Uning /usr/local/Cellar/tree/1.8.0... (8 files, 117.2KB)

Homebrew isn't limited to command-line utilities. Homebrew Cask extends its reach to full graphical applications and is bundled with Homebrew — no extra setup required.

What is a Cask?

Where standard Homebrew formulae handle terminal software, casks automate the and ation of GUI apps. A cask script handles fetching the .dmg or .zip, unpacking it, and placing the app in your /Applications folder — all managed through the same familiar brew commands.

Search for a Cask

Check whether an application is available before ing:

brew search firefox

==> Casks
firefox    firefox-beta    firefox-developer-edition    firefox-esr    firefox-nightly

a Cask Application

Visual Studio Code as a practical example:

brew  --cask visual-studio-code

==> ing https://update.code.visualstudio.com/1.58.2/darwin/stable
######################################################################## 100.0%
==> ing Cask visual-studio-code
==> Moving App 'Visual Studio Code.app' to '/Applications/Visual Studio Code.app'
==> Linking Binary 'code' to '/usr/local/bin/code'
🍺  visual-studio-code was successfully ed!

The app will appear in your /Applications folder just as if you'd ed it manually. Always use the --cask flag for clarity — it explicitly tells Homebrew you want a GUI application rather than a formula.

Manage ed Casks

brew list --cask                        # list all ed cask apps
brew info --cask visual-studio-code     # show version and  date

Remove a Cask Application

brew un visual-studio-code

For a deeper removal that also clears associated configuration files and preferences, add the --zap flag:

brew un --cask --zap visual-studio-code

If you ever need to remove Homebrew entirely, the official un script handles everything cleanly.

the script with :

 -fsSL -o un.sh https://raw.githubusercontent.com/Homebrew//master/un.sh

Inspect the script before running it:

less un.sh

Review available options with the --help flag:

bash un.sh --help

Run a dry-run first to see exactly what will be deleted:

bash un.sh -d

Once you're satisfied with the list, run the script without flags to proceed:

bash un.sh

This removes Homebrew and all packages it ed from your system.

Many development tools — databases, web servers, message queues — need to run continuously in the background. Homebrew's brew services subcommand manages these processes through macOS's native launchd, giving you a simple interface to start, stop, and monitor them.

Here's a practical example using PostgreSQL:

brew  postgresql          #  the database
brew services start postgresql  # start it and enable auto-start on login

==> Successfully started `postgresql` (label: homebrew.mxcl.postgresql)

List all Homebrew-managed services and their status:

brew services list

Name        Status  User       File
postgresql  started your_user  ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

Stop the service when you no longer need it running:

brew services stop postgresql

A Brewfile is a plain-text manifest that lists every package, cask, and repository tap your setup depends on. It lets you recreate your entire development environment on a new machine with a single command.

Generate a Brewfile

Navigate to the directory where you want the file saved and run:

brew bundle dump

A typical Brewfile looks like this:

# Taps
tap "homebrew/cask-fonts"
tap "homebrew/core"

# Formulae
brew "git"
brew "node"
brew "tree"

# Casks
cask "visual-studio-code"
cask "docker"

from a Brewfile

On a fresh machine, place the Brewfile in your home directory and run:

brew bundle 

Homebrew reads the file, s missing packages, and skips anything already present. It's safe to run multiple times. Committing a Brewfile to a project repository ensures every team member has the same tools.

A default Homebrew ation covers a broad core collection of formulae, but thousands of additional packages live in external repositories called taps. The brew tap command adds these repositories to Homebrew, making their packages available to .

For example, many programming fonts are available as casks without any extra tap:

brew  --cask font-fira-code

Taps significantly expand what Homebrew can — from specialised developer tools to niche utilities maintained by the community.

Homebrew is generally reliable, but occasional problems do crop up. Your starting point for almost any issue is Homebrew's built-in health check:

brew doctor

This scans your setup for known problems and usually provides the exact commands needed to resolve them. Beyond that, the following two commands cover the majority of common situations:

Outdated Homebrew

Many ation errors for formulae or casks occur because your local Homebrew copy is stale. Running these two commands before investigating further solves a surprising number of issues:

brew update    # refresh Homebrew's formula list
brew upgrade   # upgrade all ed packages

"Command Not Found" After ation

If your shell can't find a tool you've just ed, the culprit is almost always a missing or incorrect PATH entry.

1. Confirm Homebrew's ation prefix:

brew --prefix

• Apple Silicon (M1/M2/M3): /opt/homebrew
• Intel: /usr/local

2. Check your current PATH:

echo $PATH

3. If the Homebrew bin directory is missing, add the appropriate line to ~/.zshrc:

export PATH="/opt/homebrew/bin:$PATH"

export PATH="/usr/local/bin:$PATH"

Advanced Diagnostics

Two additional commands provide deeper insight when standard troubleshooting doesn't resolve the issue:

• brew configDisplays a full summary of your system as Homebrew sees it — useful when filing a bug report.
• brew deps --tree <formula>Shows the full dependency tree for a package, helping you understand what was ed and why.

brew deps --tree wget

wget
├── gettext
├── libunistring
├── libidn2
│   ├── libunistring
│   └── gettext
└── openssl@3
    └── ca-certificates