Objective: map every directory Homebrew writes to, show which environment variables steer it, and trace a brew install from the metadata lookup all the way to the symlink that lands in your PATH. When you know where each byte lives, you stop guessing and start fixing.

Target audience: macOS and Linux practitioners, security engineers who audit developer endpoints, and anyone who has ever typed sudo chown -R at Homebrew in frustration.

Version baseline: written against Homebrew 7.0.x, released September 13, 2026. Behavior that changed in 6.0 (June 2026) or 7.0 is called out inline, because several long-standing assumptions (cloned core taps, path_helper, Linux Bubblewrap, homebrew.mxcl service labels) no longer hold.

Prerequisites and Architecture

Assumed knowledge

• Comfort with symlinks, PATH ordering and reading ls -l output.
• Basic shell startup file knowledge (~/.zprofile, ~/.bash_profile).
• Optional but handy: jq and tree (both installable with brew install jq tree).

Lab requirements

• Homebrew 7.0.x on Apple Silicon macOS 12 or later. Sequoia 15, Tahoe 26 and Golden Gate 27 are Tier 1 on Apple Silicon.
• Intel Macs work but are Tier 3 as of 7.0 (no new bottles, support ends September 2027). Paths differ, so the table below covers both.
• Linux hosts need a Tier 1 baseline (glibc 2.39 or newer, for example Ubuntu 24.04) to receive bottles.

The three layers

Homebrew is easiest to reason about as three layers that live in different places on disk:

• The program: the brew Bash entry point plus a Ruby codebase under Library/Homebrew, run by a bundled Portable Ruby. This is a Git repository.
• The metadata: signed JSON API data (the default since 4.0, consolidated into one internal API download in 6.0) plus any third-party taps you add.
• The payload: versioned install directories (kegs) in the Cellar and Caskroom, surfaced to your shell through symlinks in the prefix.

Component locations by platform

On Apple Silicon the prefix and the repository are the same directory, so /opt/homebrew is both a Git checkout and the root your packages link into. On Intel the repository is tucked into /usr/local/Homebrew so it does not collide with the rest of /usr/local. The separate Apple Silicon prefix is also what lets an Intel (Rosetta) install and a native install coexist on one Mac, which is a double-edged sword covered in Troubleshooting.

Step 1: Locate the Anchor Paths

brew --prefix        # where symlinks land
brew --repository    # the Git checkout of brew itself
brew --cellar        # formula kegs
brew --caskroom      # cask records and payloads
brew --cache         # downloads and API data
brew --prefix tree   # per-formula opt path

Verification: on Apple Silicon you should see output like this (your username will differ):

/opt/homebrew
/opt/homebrew
/opt/homebrew/Cellar
/opt/homebrew/Caskroom
/Users/<you>/Library/Caches/Homebrew
/opt/homebrew/opt/tree

Note that brew --prefix <formula> returns the opt path, not the versioned Cellar path. That distinction is the key to the whole linking model, as Step 3 shows. For a full dump of versions, paths and toolchain details, run brew config.

Step 2: Walk the Prefix Tree

ls -1 "$(brew --prefix)"

Verification: pick any executable and follow the symlink back to its keg.

readlink "$(brew --prefix)/bin/tree"
# ../Cellar/tree/<version>/bin/tree

Step 3: Anatomy of a Keg

brew install tree
find "$(brew --cellar)/tree" -maxdepth 3 | sort

Expected layout (versions vary):

Cellar/tree/<version>/
|-- .brew/tree.rb            snapshot of the formula used at install time
|-- INSTALL_RECEIPT.json     the install record (the "tab")
|-- bin/tree                 the actual binary
|-- share/man/man1/tree.1    man page
`-- README.md, LICENSE ...   upstream docs

The receipt is the source of truth for how a keg got there. It records whether it was poured from a bottle or built from source, whether you asked for it or it arrived as a dependency, and its runtime dependency graph.

jq '{poured_from_bottle, installed_on_request,
     installed_as_dependency, time, arch}' \
  "$(brew --prefix tree)/INSTALL_RECEIPT.json"

Why the opt symlink matters

Every formula gets $(brew --prefix)/opt/<name> pointing at its current version. Dependents are built against the opt path, not the versioned Cellar path, so upgrading OpenSSL does not break every binary that links to it. You can prove it on macOS with otool:

ls -l "$(brew --prefix)/opt/tree"
# opt/tree -> ../Cellar/tree/<version>

brew install wget
otool -L "$(brew --prefix)/bin/wget" | grep opt
# /opt/homebrew/opt/openssl@3/lib/libssl.3.dylib ...

On Linux, use ldd or readelf -d instead of otool -L.

Keg-only formulae

Some formulae are keg-only: they are installed into the Cellar and get an opt symlink, but are never linked into bin or lib, usually because macOS ships its own copy (curl, sqlite) or because linking would shadow something important (libpq). brew info <formula> states this explicitly, and the fix is to reference the opt path, not to force-link.

Bookkeeping under var/homebrew

Step 4: Anatomy of the Caskroom

brew install --cask iterm2
ls -la "$(brew --caskroom)/iterm2"
ls -la "$(brew --caskroom)/iterm2/.metadata"
ls -d /Applications/iTerm.app

• Caskroom/<token>/<version>/ is the versioned record. For app artifacts it is often nearly empty because the bundle was moved into /Applications.
• Caskroom/<token>/.metadata/<version>/<timestamp>/ holds a snapshot of the cask definition used, which brew uninstall and zap rely on later.
• Casks have their own INSTALL_RECEIPT.json (added in 4.4), mirroring the formula receipt.
• binary artifacts (CLI tools shipped inside apps) are symlinked into $(brew --prefix)/bin. As of 7.0, when a formula and a cask provide the same command, the formula link wins and brew warns you.

To send apps to a per-user folder instead of /Applications, set HOMEBREW_CASK_OPTS="--appdir=~/Applications" (see Step 8).

Step 5: The brew Program Itself

file "$(brew --repository)/bin/brew"
ls "$(brew --repository)/Library/Homebrew" | head -40
ls "$(brew --repository)/Library/Homebrew/vendor/portable-ruby"
git -C "$(brew --repository)" log -1 --oneline

The boot sequence runs in three hops:

Other directories worth knowing inside Library/Homebrew: extend/os/ (per-OS overrides), shims/ (the superenv compiler wrappers used for source builds) and vendor/ (Portable Ruby and gems). External commands are any executable named brew-<name> on your PATH, or a cmd/ directory inside a trusted tap.

Step 6: Metadata, the JSON API and Taps

ls -la "$(brew --cache)/api"
brew tap
brew tap-info --installed --json=v1 | jq -r '.[] | "\(.name) trusted=\(.trusted)"'

• 4.0 (2023): formulae and casks from homebrew/core and homebrew/cask come from hosted JSON rather than local Git clones. brew update got dramatically faster.
• 6.0 (June 2026): the smaller internal JSON API became the default, combining metadata into a single download. HOMEBREW_USE_INTERNAL_API is now deprecated because it is on for everyone.
• 7.0 (September 2026): parsed API data is reused on warm runs, but signatures are verified on every load, so speed does not cost authenticity checks.

Third-party taps still live as Git clones under Library/Taps/<user>/homebrew-<repo>. Since 6.0, tap trust requires a third-party tap to be explicitly trusted before Homebrew evaluates or runs its Ruby, and untrusted taps are no longer auto-tapped. Official taps are trusted by default. Run brew trust --help to see the trust subcommands in your build.

Step 7: Caches, Logs, Temp and User Config

du -sh "$(brew --cache)"
brew --cache tree                 # exact path of the cached bottle
brew cleanup --prune=all --dry-run
ls ~/Library/Logs/Homebrew        # macOS build logs, per formula

The user config directory is $XDG_CONFIG_HOME/homebrew when XDG_CONFIG_HOME is set, and ~/.homebrew otherwise. Since 5.0, the global Brewfile also defaults to this user configuration directory.

Step 8: Environment Variables

8a. shellenv: the only exports your profile needs

# ~/.zprofile (Apple Silicon)
eval "$(/opt/homebrew/bin/brew shellenv)"

Run brew shellenv by itself to see what it emits. You will get exports for HOMEBREW_PREFIX, HOMEBREW_CELLAR, HOMEBREW_REPOSITORY, plus prepends to PATH, MANPATH and INFOPATH. As of 7.0 it sets PATH directly instead of calling macOS path_helper, which removes a subprocess from every shell start. Representative output:

export HOMEBREW_PREFIX="/opt/homebrew";
export HOMEBREW_CELLAR="/opt/homebrew/Cellar";
export HOMEBREW_REPOSITORY="/opt/homebrew";
export PATH="/opt/homebrew/bin:/opt/homebrew/sbin:$PATH";

Put it in ~/.zprofile (login shells), not ~/.zshrc, so it runs once per session rather than on every subshell and does not keep re-prepending PATH.

8b. brew.env: persistent config without polluting your shell

Homebrew reads KEY=value lines from three files, applied in order so later files win: /etc/homebrew/brew.env (system), $HOMEBREW_PREFIX/etc/homebrew/brew.env (prefix), then the user file in your user config directory. Variables exported in your shell override all three unless HOMEBREW_SYSTEM_ENV_TAKES_PRIORITY is set in the system file, which is how fleet admins lock settings.

mkdir -p ~/.homebrew
cat > ~/.homebrew/brew.env <<'EOF'
HOMEBREW_NO_ANALYTICS=1
HOMEBREW_NO_ENV_HINTS=1
HOMEBREW_CLEANUP_MAX_AGE_DAYS=30
HOMEBREW_CASK_OPTS=--require-sha
EOF
brew config | grep -E 'NO_ANALYTICS|CLEANUP|CASK_OPTS'

8c. The variables worth knowing

Deprecated or disabled in 6.0 and 7.0

8d. Environment filtering: why your CFLAGS are ignored

Since 1.4, bin/brew rebuilds its environment from scratch. Only HOMEBREW_* variables and a short allowlist (such as PATH, HOME, SHELL, TERM and proxy variables like https_proxy) make it through. That means exporting CFLAGS or PKG_CONFIG_PATH in your shell has no effect on a formula build. Since 6.0, Homebrew also filters sensitive variables during Ruby evaluation and defers HOMEBREW_* secrets until download time, so a malicious formula has less to read.

export CFLAGS="-O0"                 # has no effect on brew builds
brew --env | grep -E '^(CC|CFLAGS|PATH)'

Step 9: The Plumbing, Stage by Stage

Observe each stage directly:

brew install --dry-run wget                   # 1-2: resolve and plan
brew deps --tree wget                         # 2: dependency graph
brew fetch wget && brew --cache wget          # 3: download and cache path
brew install --verbose wget                   # 3-7: full pour and link
brew linkage wget                             # 5: verify dylib linkage
brew link --dry-run wget                      # 5: preview the symlinks

When there is no bottle: the source build path

If no bottle exists for your OS and architecture (increasingly common on Intel after 7.0), stage 4 becomes a source build. Homebrew drops the compiler into superenv: CC points at shims in Library/Homebrew/shims/super that inject the right flags and strip unsafe ones. The build runs sandboxed: sandbox-exec on macOS (which in 7.0 also blocks reads of your home directory by default) and Landlock on Linux, replacing 6.0’s Bubblewrap. Build logs land in HOMEBREW_LOGS.

Porcelain versus plumbing commands

Verification and Validation

Run this sequence after any structural change (new prefix, brew.env edits, mirror settings):

brew doctor
brew config | grep -E 'HOMEBREW_(VERSION|PREFIX|CACHE)'
brew missing
brew linkage --test
brew vulns --severity=high

Expected success indicators:

• brew doctor prints Your system is ready to brew.
• brew config shows the prefix and cache paths you expect, and a 7.0.x version.
• brew missing and brew linkage --test produce no output and exit with status 0.
• brew vulns reports no high-severity findings, or a list you can remediate with brew upgrade.

For endpoint audits, this one-liner produces a clean name and version inventory you can ship to a CMDB or SIEM:

brew info --json=v2 --installed | jq -r \
  '.formulae[] | "\(.name) \(.installed[0].version)"'

Troubleshooting and Gotchas

Gotcha 1: Two Homebrews on one Mac

Symptom: packages install as the wrong architecture, brew doctor warns about another brew shadowing the current one, or you see an error about installing to the Intel default prefix on an ARM processor. This happens when a Rosetta install in /usr/local coexists with the native /opt/homebrew.

which -a brew
arch
brew config | grep -E 'HOMEBREW_PREFIX|Rosetta'

Resolution: keep only the native shellenv line in ~/.zprofile, and retire the Intel install. With Intel at Tier 3 in 7.0 and support ending September 2027, there is no reason to keep one on Apple Silicon.

Gotcha 2: Installed, but command not found

Symptom: brew install succeeds but the command is missing or macOS’s older copy runs instead. The formula is keg-only or unlinked.

brew info curl | grep -i keg-only
ls "$(brew --prefix)/var/homebrew/linked" | grep curl
echo 'export PATH="$(brew --prefix curl)/bin:$PATH"' >> ~/.zprofile

Resolution: reference the opt path as shown. Avoid brew link --force on keg-only formulae; it can shadow system libraries and break unrelated builds.

Gotcha 3: Permission errors and sudo

Symptom: Error: <path> is not writable or files owned by root inside the prefix, usually from someone once running sudo brew.

ls -ld "$(brew --prefix)"/*
find "$(brew --prefix)" -user root -maxdepth 2 | head
sudo chown -R "$(whoami)" "$(brew --prefix)"

Resolution: fix ownership on the prefix only, never on /usr/local wholesale on Intel. Never run brew with sudo. As of 7.0, setuid wrappers with mismatched real and effective user IDs are rejected outright; MDM and root automation should use brew as-console-user (added in 6.0).

Gotcha 4: A third-party tap stops working after upgrading

Symptom: formulae from a tap you have used for years will not install or upgrade after moving to 6.0 or later. The tap is not trusted.

brew tap-info --installed --json=v1 | jq -r '.[] | "\(.name) \(.trusted)"'
brew trust --help

Resolution: review the tap before trusting it, because trusting it means allowing its Ruby to run on your machine. Then trust it with the subcommand shown in brew trust --help, or remove it with brew untap, which in 7.0 offers to uninstall the tap’s packages first.

Key Takeaways

• Always resolve paths with brew --prefix and friends; never hardcode /opt/homebrew in scripts that might run on Intel or Linux.
• The Cellar holds reality, opt holds stable pointers, and bin and lib hold convenience symlinks. Upgrades swap pointers, not dependents.
• Put shellenv in ~/.zprofile and everything else in brew.env.
• Your shell environment mostly does not reach brew. Use HOMEBREW_* variables or they are ignored.
• On 7.0, the security surface moved: tap trust, signed API data, sandboxed builds and brew vulns are the controls to audit.