How to Use Homebrew: The Beginner's Guide (Install, First Formula, First Cask, and the Brewfile Habit)

CodexFuse Team · 2026-10-29T10:13:28.315Z · 12 min read

Learning how to use Homebrew is the single highest-leverage skill a new Mac owner or beginner developer can pick up: in about ten minutes you gain a one-command installer for the thousands of tools, apps, and libraries the App Store will never carry. This guide walks you through the whole thing in one sitting — installing Homebrew, fixing the PATH step that trips up most beginners, installing your first formula and your first Mac app, keeping everything updated, and saving your entire setup in a Brewfile so your next Mac takes minutes, not an afternoon.

What is Homebrew?

Homebrew is a free package manager for macOS (and Linux, and the Windows Subsystem for Linux) that installs software from your terminal with a single brew install command. If you have ever pasted a sketchy multi-line install script from a project's README, Homebrew is the safe, repeatable replacement for that ritual: it fetches the package, puts its files in its own isolated directory (the "Cellar"), and links the commands so they just work.

It installs two kinds of packages. Formulae are command-line tools, libraries, and services built from open-source code — things like git, node, python, ffmpeg, and wget. Casks are pre-built Mac apps, fonts, and plugins — things like Firefox, Visual Studio Code, and Docker Desktop. You manage both with the same brew command. According to the official brew.sh homepage, formulae in the core repository require human review before they are accepted or updated, and must carry an open-source license compatible with the Debian Free Software Guidelines (brew.sh, fetched October 29, 2026).

If you are still getting comfortable with the terminal itself, read the Warp terminal beginner guide first — Homebrew lives in the terminal, and a modern terminal makes the whole experience friendlier.

What do you need before installing Homebrew?

You need a supported machine, an administrator account, and an internet connection — that is genuinely the whole list. Homebrew runs on Apple Silicon and Intel Macs, on most Linux distributions, and on the Windows Subsystem for Linux (Flavio Copes, "A practical guide to Homebrew," updated July 18, 2026).

On a Mac, the installer may ask to install the Xcode Command Line Tools first. These are Apple's free developer tools — the compilers and headers that Homebrew needs to build software. Say yes when prompted; the installer handles it and it takes a few minutes. You do not need the full Xcode app (which is many gigabytes) — the command-line tools alone are enough.

You also need to be comfortable entering your Mac password in the terminal. The installer asks for it once because it needs to create Homebrew's install directory and set ownership. It will never ask you to run Homebrew itself with sudo — more on that rule in a moment.

How do you install Homebrew?

Installing Homebrew takes one command, pasted from the official site. Here is the complete process:

1. Open Terminal. Press Cmd+Space, type "Terminal," and press Enter.
2. Copy the install command from brew.sh — never from a blog post, because the command can change. As of October 29, 2026, it is:
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3. Paste it into Terminal and press Enter. The script explains exactly what it will do and then pauses for confirmation. Read what it says before approving — it downloads and runs code from the network, and you should always know what is running on your machine (brew.sh, fetched October 29, 2026).
4. Enter your Mac password when asked. Nothing appears as you type — that is normal terminal behavior.
5. Do the PATH step at the end of the install. The installer prints two commands that add Homebrew to your shell's PATH. Run them exactly as shown, then open a new Terminal window. This step is where most installs appear to "fail" — the next section explains why.
6. Verify it worked by running brew --version and brew doctor. brew doctor reports possible problems; you do not have to fix every warning if everything otherwise works, but read what it says (Flavio Copes, updated July 18, 2026).

Prefer a graphical installer? On macOS, Homebrew also ships an official .pkg installer from its GitHub releases page, which suits interactive or managed (MDM) installs (brew.sh).

Why is the PATH step where beginners get stuck?

The PATH step fails silently for beginners because Homebrew installs itself in a different folder depending on your machine, and the terminal only finds commands that live in folders listed in your PATH. If you skip the installer's PATH instructions, your shell simply cannot see the brew command — and every command you type will fail with "command not found."

Here is where Homebrew lives, per the official homepage and documentation (brew.sh; Flavio Copes, July 18, 2026):

The Apple Silicon path catches people out because almost every old tutorial says /usr/local. On an Apple Silicon Mac, Homebrew chose /opt/homebrew deliberately so that an Apple Silicon install and a Rosetta 2 (Intel) install can coexist and both use pre-built bottles — those are Homebrew's pre-built binary packages, which make installs fast instead of compiling from source (docs.brew.sh FAQ, fetched October 29, 2026).

The installer prints the exact PATH commands for your machine — usually something like adding eval "$(/opt/homebrew/bin/brew shellenv)" to your ~/.zprofile on a modern Mac. Run them, open a fresh Terminal, and brew --version should answer. If it still does not, run the installer output again rather than guessing.

What is the difference between a formula and a cask?

A formula installs a command-line tool, library, or background service — software you run by typing its name in the terminal. A cask installs a pre-built Mac app, font, or plugin — software you launch from Launchpad or Applications. The difference is only in what gets installed; the how is nearly identical.

Install a formula with:

brew install ripgrep

Install an app with a cask using the --cask flag:

brew install --cask firefox

Behind the scenes, Homebrew installs each package into its own versioned directory inside the Cellar — for example /opt/homebrew/Cellar/ffmpeg/8.1.1/ — and then symlinks its files into the install prefix (brew.sh). That is why two versions of the same tool can coexist, and why uninstalling is clean: Homebrew knows exactly which files belong to which package.

Before installing anything, look it up. brew search ripgrep finds a package from the terminal, and brew info ripgrep shows its description, version, dependencies, and the exact install command before you commit (Flavio Copes, July 18, 2026). You can also browse everything at formulae.brew.sh.

How do you install your first formula?

Pick something small and useful — wget (a file downloader) or tree (a directory visualizer) are perfect first installs. The routine is the same every time:

1. Search: brew search wget — confirms the package exists.
2. Inspect: brew info wget — shows version, size, and what it depends on.
3. Install: brew install wget — Homebrew downloads a pre-built bottle when one exists for your machine, and builds from source only if it must.
4. Verify: wget --version — the command is now on your PATH.

To see everything you have installed, run brew list --formula. To remove something, brew uninstall wget takes it out cleanly. And here is the rule every beginner must learn on day one: never run Homebrew with sudo. The official FAQ is explicit — "Homebrew runs formula builds and installations as the owning account because upstream build scripts should not have unrestricted system access" (docs.brew.sh FAQ, fetched October 29, 2026). Homebrew owns its prefix; it never needs root.

How do you install your first app with a cask?

Casks turn app installation into a one-liner. Instead of downloading a .dmg, dragging an icon into Applications, and unmounting the disk image, you type one command and the app appears in /Applications.

brew install --cask visual-studio-code

Try it with a browser or an editor you actually use. brew list --cask shows your installed apps, and brew uninstall --cask firefox removes one — including its preference files if you add --zap.

One honest caveat, straight from the official homepage: some cask apps update themselves outside Homebrew (think browsers and their built-in updaters), so brew upgrade may skip them. If you want Homebrew to update those too, use brew upgrade --greedy (brew.sh).

What are the essential Homebrew commands?

You can run 95% of your Homebrew life with the commands in this table. Run them in this order and you will understand the whole maintenance rhythm:

How do you keep Homebrew and your packages updated?

Three commands do three different jobs, and mixing them up is the second most common beginner mistake after skipping the PATH step. brew update refreshes Homebrew's knowledge — the package definitions and Homebrew itself. brew outdated then shows which of your installed packages have newer versions available. Finally, brew upgrade actually installs those newer versions (docs.brew.sh FAQ).

Run them in that order once a week or so:

brew update
brew outdated
brew upgrade

To upgrade just one package, name it: brew upgrade ripgrep. To keep a package frozen at its current version — say a database whose upgrade would break your project — use brew pin postgresql, and brew unpin postgresql to release it (docs.brew.sh FAQ).

Two things to know about upgrades. First, an upgrade can pull in updates to other packages too, because Homebrew only supports and tests the latest combination of each formula and its dependencies — so if python or openssl needed an upgrade, it comes along for the ride (docs.brew.sh FAQ). Second, Homebrew automatically runs brew cleanup every 30 days, removing old package versions so your disk does not fill up silently (docs.brew.sh FAQ).

What is a Brewfile, and why should you keep one?

A Brewfile is a plain-text file that lists everything you have installed with Homebrew — formulae, casks, and even extra taps — so your setup is reproducible. Think of it as a recipe card for your machine: hand the card to a fresh Mac, run one command, and your whole toolchain comes back.

Create one from your current machine with:

brew bundle dump

This writes a Brewfile in your current directory that looks like this:

brew "ffmpeg"
cask "firefox"

On a new machine, install Homebrew, copy the file over, and run:

brew bundle

Homebrew installs every missing dependency and updates outdated ones (brew.sh). The bundle system also covers taps, Mac App Store apps, VS Code extensions, and background services via brew services — so one file can genuinely rebuild a whole development machine (brew.sh). Keep your Brewfile in a synced folder or a dotfiles repository and you will never again spend a Saturday reinstalling your tools one by one.

Homebrew vs MacPorts: which should you pick?

MacPorts is the other classic Mac package manager, and beginners often ask which to choose. The honest answer is that both work, but they have different philosophies:

For a beginner in 2026, Homebrew is the easier pick: the cask system covers your GUI apps too, and nearly every developer tutorial you will read assumes brew install commands. The comparison above is the author's synthesis of the two projects' documented designs, not a benchmark — both are maintained by volunteers and both are free.

7 mistakes every Homebrew beginner makes

Learn these from a list instead of from experience:

1. Using sudo. Never sudo brew install. Homebrew manages its own prefix; sudo breaks file ownership and is the number-one beginner mistake (docs.brew.sh FAQ).
2. Skipping the PATH step. "command not found" after a successful install is almost always the missing brew shellenv line — go back and run the installer's PATH commands.
3. Installing a GUI app as a formula. If the thing you want is a Mac app, it is a cask: brew install --cask, not brew install.
4. Never running brew update. Upgrading without updating first means upgrading against stale package definitions. Update, then upgrade.
5. Deleting files from the Cellar by hand. Homebrew tracks exactly which files belong to which package. Use brew uninstall — manual deletion corrupts its records.
6. Ignoring brew doctor. When something breaks, brew doctor is the first command, not Stack Overflow.
7. Forgetting the Brewfile. The day your drive dies is the wrong day to wish you had run brew bundle dump.

Where does Homebrew fit in your developer setup?

Homebrew is the foundation layer of a Mac development setup: the terminal is the interface, Homebrew is the installer, and everything else stacks on top. A natural next step is a proper terminal — the Warp beginner guide covers a modern terminal built for this workflow — and an editor, covered in the VS Code beginner guide. If you also touch Linux servers, the Ubuntu beginner guide teaches the system Homebrew's Linux side mirrors, and the VirtualBox beginner guide shows how to practice all of this in a safe virtual machine. Developers heading toward open source will also want the GitHub beginner guide for the first repository, first push, and first pull request.

Sources

• Homebrew official homepage — install command, install prefixes, formulae and casks definitions, pre-built bottles, Homebrew Bundle/Brewfile. https://brew.sh/ (fetched October 29, 2026)
• Flavio Copes, "A practical guide to Homebrew" — install flow, PATH setup, formulae vs casks, brew search/info/update/outdated/upgrade/uninstall/cleanup, brew doctor, brew config. https://flaviocopes.com/homebrew/ (updated July 18, 2026; fetched October 29, 2026)
• Homebrew Documentation FAQ — "why sudo is bad," default prefixes and their rationale, brew update/outdated/upgrade sequence, brew pin, automatic 30-day cleanup, dependency upgrades. https://docs.brew.sh/FAQ (fetched October 29, 2026)

Frequently Asked Questions

Is Homebrew safe to install?

Yes, with the same common sense as any software. Homebrew is a large open-source project whose core formulae require human review, and the installer explains what it will change and pauses for confirmation before doing anything (brew.sh). The main safety rule is yours to follow: copy the install command from brew.sh itself, never from a random blog, and never run Homebrew with sudo.

Does Homebrew work on Windows?

Homebrew runs natively on macOS and Linux, and on Windows it runs inside the Windows Subsystem for Linux (WSL) using the Linux prefix /home/linuxbrew/.linuxbrew (brew.sh; Flavio Copes, July 18, 2026). There is no native Windows build — WSL is the supported route.

Do I need the full Xcode app to use Homebrew?

No. On a Mac, the installer may prompt you to install the Xcode Command Line Tools, which are the free compilers and headers Homebrew needs — that is a small download handled by the installer itself. The multi-gigabyte full Xcode app from the App Store is not required.

Why does Homebrew say sudo is bad?

Because Homebrew is designed around a single owning account that manages its own install prefix, and it deliberately runs builds and installations as that account rather than as root. Per the official FAQ, "upstream build scripts should not have unrestricted system access" — running with sudo would hand those scripts root privileges and break Homebrew's file ownership (docs.brew.sh FAQ).

How do I uninstall Homebrew?

Homebrew provides an official uninstall script in the Homebrew/install repository on GitHub (docs.brew.sh FAQ). Run that rather than deleting folders by hand — and if you kept a Brewfile (see above), reinstalling later is a one-command job.