Fix zsh: command not found: brew on macOS Sonoma

You updated to Sonoma, opened Terminal, typed brew install something, and got slapped with zsh: command not found: brew. Or maybe you opened a new tab and suddenly your shell acts like Homebrew never existed. This almost always shows up right after a major macOS upgrade — Sonoma 14.0 through 14.5 in particular — and it hits Intel and Apple Silicon Macs differently.

The error is misleading. Homebrew is still installed. Your packages are all there. What broke is the shell's PATH, or more accurately, whatever mechanism you were using to add Homebrew to that PATH.

Why this happens

Homebrew doesn't magically inject itself into your shell. Something has to run this line every time a new shell starts:

eval "$(/opt/homebrew/bin/brew shellenv)"

On Apple Silicon that lives at /opt/homebrew. On Intel it's /usr/local. That line normally sits in your ~/.zprofile or ~/.zshrc, added by the Homebrew installer back when you first set things up.

macOS updates have a nasty habit of doing one of three things:

Resetting or replacing your shell rc files during the upgrade.
Switching your login shell away from zsh (rare, but it happens if you'd customized it).
Changing the default PATH that launchd hands to new Terminal sessions, so your rc file never loads.

There's also the classic case: you ran the macOS migration assistant to a new Mac and it copied your ~/.zshrc but not the Homebrew directory itself, or vice versa.

And one more that trips people up — if you were using iTerm2 with a custom profile that sourced your rc files, and you switched back to the stock Terminal after the update, the rc files won't get sourced.

The fix

Confirm Homebrew is actually installed. Don't skip this. Run:
```
ls /opt/homebrew/bin/brew
ls /usr/local/bin/brew
```
One of these two paths should return the brew binary. If neither exists, Homebrew really is gone and you need to reinstall it from brew.sh. If one does exist, continue.
Find out which rc file you actually use. macOS uses zsh now, and zsh reads ~/.zprofile for login shells and ~/.zshrc for interactive shells. Check both:
```
ls -la ~/.zprofile ~/.zshrc ~/.zlogin
```
If ~/.zprofile doesn't exist, that's probably your problem right there. On Apple Silicon, Homebrew's installer normally writes to ~/.zprofile.
Add the shellenv line. Open the file that exists (or create ~/.zprofile) and append the correct line for your architecture.

Apple Silicon:
```
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
```
Intel:
```
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
```
Using brew shellenv instead of hardcoding the PATH matters — it sets HOMEBREW_PREFIX, MANPATH, and INFOPATH too. Hardcoding just PATH is the amateur move and breaks man brew.
Reload the shell. Don't just open a new tab — actually source it:
```
source ~/.zprofile
type brew
```
You should see brew is /opt/homebrew/bin/brew (or the Intel path). If you don't, the file isn't being read.
Verify with a real command.
```
brew --version
brew doctor
```
If brew doctor complains about permissions on /opt/homebrew or /usr/local, run sudo chown -R $(whoami) /opt/homebrew — Sonoma's migration sometimes resets ownership.

If it still doesn't work

Check a few things in order:

Confirm your login shell. Run echo $SHELL. It should say /bin/zsh. If it says /bin/bash or /bin/sh, you're reading the wrong rc files entirely and no amount of editing .zprofile will help. Fix with chsh -s /bin/zsh.
Check what's already in PATH. echo $PATH and look for /opt/homebrew/bin or /usr/local/bin. If they're absent, your rc file isn't loading — which usually means Terminal's "Shells open with" setting got reset to a custom command.
Check Terminal preferences. Terminal → Settings → General → "Shells open with" should be set to the default login shell, not "Command (complete path)" pointing somewhere weird.
Look for a broken rc file. A syntax error earlier in .zshrc will silently kill everything after it. Run zsh -x ~/.zshrc 2>&1 | tail -30 to see where it dies.
Duplicate installation. Run which -a brew. If you see two paths, you've got Homebrew in both /opt/homebrew and /usr/local. Pick one — usually the native one for your architecture — and remove the other.

One more thing: if you use a tool like asdf, nvm, or direnv, check the order of your rc file. Those tools often load before Homebrew's shellenv line and can clobber your PATH. Put the brew shellenv line first. I've seen this bite people for weeks because their nvm shim loaded a stale PATH on top.

If brew --version returns a version but brew install fails with permission errors, that's a different problem — usually a Sonoma ownership reset on /opt/homebrew. Run sudo chown -R $(whoami):admin /opt/homebrew and try again.