Homebrew on macOS: The Complete 2026 Package Manager Guide

Homebrew is the de facto package manager for macOS — the open-source tool that installs, updates, and removes the command-line utilities, developer libraries, and desktop applications that Apple does not ship by default. If you have ever typed brew install to pull down Git, Node, PostgreSQL, or Visual Studio Code, you have already relied on it. This guide explains how Homebrew works on modern Apple Silicon and Intel Macs, walks through the commands IT teams and developers use every day, covers Brewfile-driven automation for fleet provisioning, and closes with a structured troubleshooting playbook for the errors that will eventually show up in your terminal.

Homebrew turned ten years old in 2019 and has since become the single most important piece of infrastructure that Apple did not build. The project reached version 5.1.0 in March 2026 and now enforces stricter security controls — including mandatory Apple codesigning and notarization for all official casks by September 1, 2026 [Homebrew Documentation]. For IT teams managing Mac fleets, for developers onboarding new hardware, and for security leaders standardizing baseline tooling, understanding Homebrew is no longer optional. It is part of the macOS operating model.

What Homebrew Actually Is — and Why macOS Needs It

Homebrew describes itself as "the missing package manager for macOS" [Homebrew]. Unlike Linux distributions, which ship with apt, dnf, or pacman built in, macOS has no native system for installing open-source software from the command line. Apple's App Store handles signed consumer apps, but it does not ship Git, Python toolchains, database servers, CLI utilities like wget and ripgrep, or the thousands of other tools that modern developers and engineers depend on every day.

Homebrew fills that gap. It is a Ruby-based project (though users rarely touch Ruby) that maintains a massive catalog of "formulae" — build instructions for open-source packages — and "casks" — installers for macOS GUI applications like Visual Studio Code, Docker Desktop, and Slack. A single brew install command resolves dependencies, downloads pre-compiled bottles when available, and places everything in a predictable location that will not collide with macOS system files.

The fact that Homebrew lives in user-writable directories rather than in /System or /Library is a deliberate design choice. It keeps macOS upgrades from breaking your development environment, keeps installations reversible, and avoids the System Integrity Protection (SIP) conflicts that plagued earlier macOS package managers. For organizations rolling out managed workstations, this also makes Homebrew compatible with standard Apple device management — IT teams can automate Homebrew installs without needing deep system-level privileges on every machine.

Homebrew lives in the terminal — a single command replaces dozens of manual downloads and drag-to-install steps.

How Homebrew Fits Into the macOS Stack

Before installing anything, it helps to understand what Homebrew is actually doing when you run brew install git. The diagram below shows the high-level flow: your command goes through the local brew CLI, which consults a local clone of the Homebrew tap (essentially a Git repository of formulae), fetches a pre-built bottle from GitHub Packages when one exists, and installs it into the Homebrew prefix on disk.

Conceptual view of the same flow — from remote tap to local install, with the distribution CDN in the middle.

The filesystem layer is worth calling out explicitly. On Apple Silicon Macs, Homebrew installs everything under /opt/homebrew. On Intel Macs it uses /usr/local. This split matters because any Brewfile, shell profile, or documentation that hardcodes one path will break when a user moves to the other architecture — a common gotcha during M-series migrations.

Installing Homebrew on Apple Silicon and Intel

Homebrew's official support policy covers macOS Sonoma (14) and newer on officially supported Apple hardware [Homebrew Documentation]. Sonoma, Sequoia, and the current Tahoe release are all fully supported. Older releases from Catalina through Ventura may still work in practice but are listed as unsupported, meaning you may encounter problems that upstream will not help debug. Mojave and earlier are not supported at all.

Prerequisites

Before you run the Homebrew installer, install Apple's Xcode Command Line Tools. This gives Homebrew access to the compilers it needs to build formulae from source when no pre-built bottle is available:

xcode-select --install

A GUI prompt will appear. Accept, and wait several minutes for the download to complete. If the command reports that the tools are already installed, you are ready to proceed.

Running the installer

The canonical install command is a one-line curl pipe that fetches and runs the official shell installer. Paste the following into Terminal:

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

The installer pauses before making any changes, shows the directories it will create, and asks for your macOS password to escalate where needed. Read the prompt. Do not blindly paste sudo-requiring commands you did not expect.

Post-install: configure your PATH

On Apple Silicon Macs, /opt/homebrew/bin is not in the default shell PATH. You must add it explicitly so your shell can find the brew command. The installer prints the two commands you need at the end of its output, but the canonical pattern is:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

For Intel Macs, replace /opt/homebrew with /usr/local in the snippet above. For bash users, write to ~/.bash_profile instead of ~/.zprofile. After running these two lines, close and reopen Terminal, then verify:

brew --version
brew doctor

A clean install should report a recent version (5.1.0 or later as of this writing) and Your system is ready to brew. If brew doctor flags warnings, read them carefully — most are harmless, but outdated Command Line Tools and unbrewed dylibs in /usr/local/lib genuinely do cause installation problems later [Homebrew Troubleshooting].

Essential brew Commands Every User Should Know

Homebrew's command surface is small and consistent. The following eight commands cover roughly 95 percent of daily use:

Sample workflow — standing up a fresh developer machine

Here is what a typical developer's first hour with Homebrew looks like in practice:

# Core command-line tools
brew install git wget curl jq ripgrep fd bat

# Language runtimes
brew install node python go rust

# Databases and services
brew install postgresql@16 redis

# Start a service (managed by launchd)
brew services start postgresql@16

# Verify
brew services list

Notice brew services. It wraps macOS's launchd and lets you start, stop, and auto-launch daemons like PostgreSQL, Redis, or nginx with a single command — no more hand-written plist files.

Casks: Installing GUI Apps From the Terminal

Casks extend Homebrew to macOS GUI applications. Instead of downloading a .dmg file, mounting it, and dragging an icon into /Applications, you can install apps like Visual Studio Code, Docker Desktop, Google Chrome, or Slack with a single command:

brew install --cask visual-studio-code
brew install --cask docker
brew install --cask google-chrome
brew install --cask slack
brew install --cask 1password

For IT teams, casks are the missing piece that makes Homebrew viable for fleet deployment. You can write a single shell script that installs a complete set of approved developer and productivity applications, and every workstation ends up with the same, auditable software state.

Brewfile and brew bundle — Declarative Mac Provisioning

The single most underrated feature of Homebrew is brew bundle. It lets you describe your entire set of installed packages — formulae, casks, Mac App Store apps, and VSCode extensions — in a plain-text Brewfile, then reproduce that state on any machine with one command [Homebrew Documentation].

A minimal Brewfile looks like this:

tap "homebrew/bundle"

# CLI tools
brew "git"
brew "node"
brew "python@3.12"
brew "postgresql@16", restart_service: true
brew "ripgrep"
brew "jq"

# GUI apps
cask "visual-studio-code"
cask "docker"
cask "1password"
cask "slack"
cask "google-chrome"

# Mac App Store apps (requires 'mas' CLI)
mas "Xcode", id: 497799835
mas "The Unarchiver", id: 425424353

# VSCode extensions
vscode "ms-python.python"
vscode "dbaeumer.vscode-eslint"

With that file saved as ~/Brewfile, the following command installs — or verifies — everything listed:

brew bundle install --file=~/Brewfile

To capture the current state of a working machine into a Brewfile you can commit to Git:

brew bundle dump --file=~/Brewfile --force

And to verify that a target machine matches the declared state — useful in CI or as a pre-flight check — use:

brew bundle check --file=~/Brewfile

As of early 2026, brew bundle also supports Go packages, Cargo packages, uv tools, Flatpak, and krew kubectl plugins — so one Brewfile can describe a polyglot developer environment across multiple language ecosystems [Homebrew Bundle Documentation].

Real-World Use Cases for IT Teams and Developers

Homebrew is often introduced as a developer tool, but the most valuable applications show up at the team and fleet level. Four stand out.

1. Standardized developer onboarding

Every hour a new hire spends manually hunting down installers is an hour they are not writing code or shipping work. A Brewfile checked into the engineering repo turns onboarding into a single command. New hire plugs in their laptop, runs brew bundle install, walks to coffee, and returns to a machine that matches the team's standard.

2. IT fleet provisioning and drift control

For companies running dozens or hundreds of Macs, Homebrew combined with a device management platform (Jamf, Kandji, Intune) becomes a baseline software policy engine. The Brewfile defines what "compliant" means. A scheduled brew bundle check catches drift. This is especially relevant for regulated industries where you need to prove which software is running on which machine — if you need broader managed IT services support for your Mac fleet, this kind of declarative baseline is where we usually start.

A single Brewfile becomes the source of truth for what every Mac in the fleet should have installed.

3. Security tooling distribution

Endpoint protection, password managers, and VPN clients are among the most common casks IT teams ship. ITECS is an authorized 1Password reseller and managed services partner — the 1password and 1password-cli casks make it straightforward to deploy 1Password to every Mac in an organization as part of a broader credential hygiene program. Combine that with endpoint detection and response tooling and you have a lightweight, auditable way to keep baseline security software current without touching each machine individually.

4. CI and build environment parity

When local development happens on macOS and CI runs on macOS runners (common for iOS, Mac, or cross-platform projects), a shared Brewfile keeps the environments aligned. Contributors installing a weird local version of Node or Python no longer produces the dreaded "works on my machine" builds.

Troubleshooting: The Errors You Will Actually See

Homebrew is generally stable, but a few issues show up often enough to be worth a playbook. Run this checklist before you reach for a reinstall.

"Permission denied" or "Could not symlink"

The root cause of most permission errors is incorrect ownership of Homebrew's directories. Somewhere along the way, something was run with sudo that should not have been. Restore ownership with:

sudo chown -R $(whoami) /opt/homebrew
sudo chmod -R u+w /opt/homebrew

On Intel, replace /opt/homebrew with /usr/local. Run brew doctor afterward to confirm the fix.

"command not found: brew" after install

This is almost always a missing PATH entry, particularly on Apple Silicon. Re-run the shellenv setup from the installation section and make sure you edited the correct shell profile — ~/.zprofile for zsh (the macOS default), ~/.bash_profile for bash.

"No such file or directory" or "Operation not permitted"

These typically indicate a stale install, a corrupted tap, or a macOS Full Disk Access setting blocking Homebrew's helper processes. Start with brew update-reset to wipe and re-clone the local tap repositories, then re-run the failing command. If the error persists, run brew doctor to surface the underlying cause [Homebrew Common Issues].

Slow downloads or intermittent failures

Bottle downloads come from GitHub Packages. If your network blocks or throttles GitHub endpoints, set the HOMEBREW_BOTTLE_DOMAIN environment variable to a mirror, or configure an HTTPS proxy. Corporate networks with deep packet inspection are a common culprit here — this often surfaces when onboarding the first Mac user at an enterprise that is primarily Windows-managed.

The nuclear option: reinstall

If your Homebrew install is genuinely corrupted and triage has not worked, the recommended recovery path is: dump your current state to a Brewfile, uninstall Homebrew entirely, reinstall, and re-apply the Brewfile. The entire loop typically takes fifteen minutes and produces a guaranteed-clean environment:

brew bundle dump --file=~/Brewfile.backup --force
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/uninstall/HEAD/uninstall.sh)"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew bundle install --file=~/Brewfile.backup

Best Practices for Teams Running Homebrew at Scale

A few operational habits separate smooth Homebrew environments from the ones that constantly break:

• Check Brewfiles into Git alongside your repo. Treat the Brewfile like any other configuration artifact — reviewed, versioned, and tied to release tags.
• Pin versioned formulae for databases, language runtimes, and other tools where minor version drift matters. Use postgresql@16 rather than bare postgresql.
• Run upgrades in batches, not ad-hoc. A weekly or monthly brew update && brew upgrade && brew cleanup window is easier to troubleshoot than surprise mid-sprint upgrades.
• Separate system tools from project dependencies. Use Homebrew for the shell tools every machine needs, and use project-specific managers (nvm, pyenv, asdf, uv) for per-project language runtimes.
• Audit casks before September 1, 2026. Anything that relies on an un-notarized installer will stop working; plan replacements now.

Related Resources

Sources

• Homebrew — The Missing Package Manager for macOS (or Linux)
• Homebrew Documentation — Installation
• Homebrew Documentation — Troubleshooting
• Homebrew Documentation — Common Issues
• Homebrew Documentation — Bundle and Brewfile
• Homebrew Documentation — Full brew(1) Manpage
• DEV Community — macOS Developer Setup: Essential Homebrew Commands for 2026