Homebrew

Also known as: brew

On this page 7

Homebrew is a free, open-source package manager for macOS that installs, upgrades and removes software from the command line with the brew command. It fills a gap that Apple leaves open: macOS ships with a Unix userland and Terminal, but it has no built-in system for installing developer tools such as Git versions, Python runtimes, database servers or image libraries. Homebrew resolves dependencies, downloads prebuilt binaries where possible and keeps every installed package in a predictable location.

Among the macOS fundamentals, Homebrew sits beside the Mac App Store as a second, independent distribution channel. The App Store serves sandboxed consumer apps signed through Apple, while Homebrew serves command-line utilities, libraries and many desktop apps that developers, administrators and power users need. It also runs on Linux, but its design decisions are shaped by the macOS file system, code signing and Apple silicon.

How Homebrew installs and tracks software

Homebrew works by reading package definitions written in Ruby, downloading the matching artifact, and linking it into a prefix that the shell searches. Each definition describes the source URL, the version, a SHA-256 checksum, dependencies and the build or install steps. When a user runs brew install wget, Homebrew checks the definition, installs any missing dependencies first, verifies the checksum and places the result in its own directory tree.

Most installations use bottles, which are precompiled binary packages built by Homebrew’s continuous integration for each supported macOS version and processor architecture. When no bottle exists for the current system, Homebrew falls back to building from source, which takes longer and requires the Command Line Tools for Xcode. Installed versions live in a folder called the Cellar, and symbolic links expose them in the prefix’s bin, lib and include directories.

The following table explains the vocabulary that Homebrew uses for its building blocks.

ConceptWhat it isTypical example
FormulaRuby definition for command-line software or a librarybrew install jq
CaskDefinition for a macOS app, font or driver distributed as a binarybrew install --cask firefox
BottlePrecompiled binary package for a specific macOS version and CPUDownloaded automatically during install
TapGit repository that adds extra formulae or casksbrew tap owner/repo
CellarDirectory holding every installed formula version/opt/homebrew/Cellar/jq/1.7.1
KegOne installed version of a formula inside the CellarA single versioned subfolder
Core Homebrew concepts

Install prefixes on Apple silicon and Intel Macs

Homebrew uses different default prefixes depending on the processor, and this detail explains many path problems. On Apple silicon Macs the prefix is /opt/homebrew, while on Intel Macs it is /usr/local. The separation lets an Apple silicon Mac keep a native ARM installation and, when needed, a second Intel installation that runs under Rosetta 2 without the two overwriting each other.

Because /opt/homebrew/bin is not on the default search path, the installer asks the user to add a shellenv line to the shell profile, usually ~/.zprofile for zsh, the default shell since macOS Catalina. Skipping this step is the most common reason a freshly installed tool reports command not found.

Mac typeDefault prefixBinary path to addNotes
Apple silicon/opt/homebrew/opt/homebrew/binNative ARM64 bottles
Intel/usr/local/usr/local/binPath is usually present by default
Apple silicon under Rosetta 2/usr/local/usr/local/binSeparate x86_64 installation
Default Homebrew locations by Mac architecture

Everyday brew commands

A small set of commands covers nearly all routine package management with Homebrew. The brew update command refreshes the local copy of package definitions, while brew upgrade actually replaces outdated software, a distinction that confuses many new users. Since Homebrew 4, definitions are fetched from a JSON API by default instead of cloning large Git repositories, which makes updates considerably faster.

CommandWhat it doesWhen to use it
brew install nameInstalls a formula and its dependenciesAdding a new tool
brew updateRefreshes package definitions onlyBefore checking for new versions
brew upgradeUpgrades all outdated packagesRegular maintenance
brew uninstall nameRemoves a packageCleaning up unused software
brew cleanupDeletes old versions and cached downloadsReclaiming disk space
brew doctorReports configuration problemsTroubleshooting failed installs
brew bundleInstalls everything listed in a BrewfileSetting up a new Mac
Frequently used commands and their purpose

The Brewfile deserves special mention. It is a plain text manifest of formulae, casks, taps and even Mac App Store apps, and brew bundle dump generates one from the current machine. Teams keep a Brewfile in version control so that every developer laptop gets the same toolchain with a single command.

Homebrew compared with other ways to get software on a Mac

Homebrew is one of several installation channels on macOS, and each channel suits a different kind of software. The Mac App Store provides Apple review, sandboxing and automatic updates but rarely carries command-line tools. Direct downloads in disk images are simple but leave updating to each app. MacPorts, an older package manager, builds a more self-contained tree and avoids system libraries more strictly.

ChannelBest suited forUpdate mechanismMain limitation
HomebrewDeveloper tools, libraries, many appsbrew upgradeRelies on community maintenance
Mac App StoreSandboxed consumer appsAutomatic through the storeFew command-line tools
MacPortsSelf-contained Unix software treesport upgrade outdatedSmaller app catalog, slower builds
Direct downloadSingle vendor appsEach app’s own updaterNo central inventory
Comparison of software installation channels on macOS

The choice is rarely exclusive. A typical professional Mac combines App Store apps, a few vendor installers and Homebrew for the toolchain. The important rule is to avoid installing the same tool through two channels, because conflicting copies on the search path produce confusing version mismatches.

Security model, risks and common mistakes

Homebrew’s security rests on checksums, maintainer review and HTTPS downloads, not on Apple’s App Review. Every bottle and source archive is verified against the SHA-256 value in its definition, and changes to the core repositories pass pull request review and automated tests. Casks install apps that the vendor signed and notarized, so Gatekeeper still checks them at first launch.

The weaker points are third-party taps and the installer itself. A tap is controlled by whoever owns its repository, so adding an unknown tap means trusting that owner with code that runs on the Mac. Homebrew deliberately refuses to run as root, which limits the damage a faulty package can cause to the user account and the prefix.

  • Running brew with sudo breaks file ownership in the prefix; fix ownership instead of escalating privileges.
  • Forgetting the shellenv line on Apple silicon leaves tools installed but invisible to the shell.
  • Never running cleanup lets old kegs and caches consume several gigabytes over time.
  • Pinning nothing in production scripts means a routine upgrade can change a major version unexpectedly.
  • Mixing Intel and ARM installations without intent causes libraries of the wrong architecture to load.

In simple terms

Homebrew is like a helpful shop assistant for your Mac who fetches software on request. Instead of searching websites, downloading files and dragging icons into folders, you type one short command, and Homebrew finds the right version, checks that the file is genuine and puts it where your Mac can find it.

It also remembers everything it installed. Later, one more command updates all of it at once, and another removes anything you no longer need. The key idea is a single, tidy list of your tools that you control from the Terminal.

A practical example

A small web agency hires two developers who receive new MacBook Pro laptops with Apple silicon. Instead of a two-page setup checklist, the team lead keeps a Brewfile in the company repository listing Git, Node.js, PostgreSQL 16, the GitHub CLI, a code editor delivered as a cask and a font for the editor.

Each developer installs Homebrew, adds the shellenv line to ~/.zprofile and runs brew bundle in the repository folder. In roughly fifteen minutes, mostly spent downloading bottles, both laptops have identical tool versions. When the team later moves to a newer PostgreSQL release, the lead edits one line in the Brewfile, and everyone updates with the same command, which removes an entire class of works-on-my-machine bugs.