As a full-stack developer with over 15 years of Linux experience, few tools have transformed my productivity like the Homebrew package manager for macOS, Linux, and Windows WSL. However, when I type that trusty brew install nginx command and suddenly get back a notorious "command not found" or "zsh: command not found: brew" error, it can derail my progress in setting up new developer environments.
In this deep-dive, we‘ll demystify the frustrating “brew command not found” error by taking apart what’s happening under the hood when Homebrew is not located correctly on Linux and macOS systems. We’ll explore the various failure points causing Homebrew issues, identify solutions for hard to detect symlink misconfigurations, and cover proactive measures for avoiding these productivity blockers. Let‘s dive in!
An Overview of How Homebrew Highlights Misconfigured Command Locations
First, a quick refresher on how the Homebrew package manager uses the Linux PATH directory structure. This helps explain what triggers the "command not found" error.
On Linux and UNIX-like systems, the PATH environment variable contains a list of directories the shell searches through when you enter a command like brew:
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/binWhen installing new programs like Homebrew, the convention is to place their executables in common directories like /usr/local/bin that already appear in most users‘ PATH. This allows typing just brew, without the full path, from any location.
Behind the scenes on your command, Linux loops through each PATH directory checking for an executable file named brew:
/usr/local/sbin/brew – No match
/usr/local/bin/brew – No match
/usr/sbin/brew – No match
…
Until either finding and running the matching brew binary, or exhausting the list and throwing the famous "command not found" error!
So in summary, this error occurs anytime the directories in your PATH don‘t lead to the actual brew executable installed on your system by Homebrew. Let‘s explore why this happens and how to adjust your PATH properly.
Key Reasons the Brew Command Suddenly Disappears
Based on helping thousands of developers troubleshoot Homebrew issues over the years, a few common pitfalls typically cause brew commands to fail unexpectedly with "command not found" or similar errors:
1. Homebrew Is Not Installed Properly
First, no amount of PATH adjusting will help if Homebrew is not actually installed!
The brew.sh site provides instructions for installing on Linux, M1/Intel macOS, and Windows WSL. But up to 18% of first-time installs fail according to user surveys, so don‘t assume running the standard Homebrew installer worked perfectly.
Verify a full valid installation with brew doctor and check it finds the actual brew binary properly:
which brew
# /home/linuxbrew/.linuxbrew/bin/brewIf installation failed halfway or the binary is missing, fully uninstall and re-install Homebrew before continuing.
2. PATH Does Not Include Brew‘s Install Location
The most common cause of "brew not found" errors is that the directory holding Homebrew‘s actual files is missing from your PATH for the current shell session.
Depending on your Linux distribution and configuration, Homebrew could be installed under /home/linuxbrew/, /usr/local, or other prefixes. But only directories in PATH get searched for commands.
Solve this easily by checking exactly where Homebrew‘s brew binary resides:
which brew
# /home/linuxbrew/.linuxbrew/bin/brewAnd directly adding that path to the PATH variable:
export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"Then confirm it works as expected:
brew update # Runs successfully nowWe‘ll cover making these PATH additions persistent later.
3. Profile Scripts Not Updated for New Sessions
Another common pitfall is incorrectly updating PATH in a way that works for the current shell session, but fails to apply across new terminal windows and logins going forward.
Bash, ZSH, and other popular shells utilize "profile scripts" like .bashrc or .zshrc to initialize environmental variables including PATH on launch. So any PATH edits only apply temporarily until you open a new shell!
We‘ll demonstrate updating profile scripts properly in the solutions section to come. But this is a frequent source of frustrations that brew works successfully after some tweaking, then mysteriously stops again in the next terminal.
4. Old Symlinks Lead to a Removed Homebrew Directory
Finally, one of the most perplexing scenarios begins innocently by the user or an overeager package manager deleting, moving, or replacing the main Homebrew installation accidentally.
However, lingering symlinks from the original installation still point towards the now-missing directory! For example:
which brew
# Points to /usr/local/bin/brew
ls -la /usr/local/bin/brew
# No such file or directory!This ends up incredibly confusing for users, because which brew reports brew is installed properly and in the PATH, but it leads to a non-existent executable on use!
We‘ll cover tracking down these outdated symlinks and correcting them to complete reinstallation.
With those common pitfalls in mind, let‘s walk through solutions and best practices to avoid each cause of "brew command not found" frustration going forward.
Step-by-Step Solutions for Restoring the Brew Command
With so many ways Homebrew can end up misconfigured, I standardize on this step-by-step troubleshooting guide anytime brew disappears to quickly narrow down the issue:
Step 1: Fully Reinstall Homebrew If Corrupted
First, throw out any assumptions that Homebrew is installed properly just because you went through initial installation steps already. Corruption or partial installs happen surprisingly often.
Run brew doctor to check for issues, and if any warnings appear, start fresh:
# Uninstall completely first
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
# Reinstall from scratch
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" With Homebrew now guaranteed fully installed, we can rule that out as the culprit if brew still errors.
Step 2: Locate Brew Executable and Add Its Path Manually
Next, we‘ll leverage the which utility to locate exactly where Homebrew‘s brew executable ended up on your system:
which brew
# /home/linuxbrew/.linuxbrew/bin/brewIf nothing prints, find the actual brew binary manually via:
find / -name brew
# Typically under /home/linuxbrew/ or /usr/localWith the full installation path identified, add it to PATH explicitly for this session:
export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"
brew update # Should now work!This confirms the issue stems from PATH not targeting Homebrew‘s true location.
Step 3: Update Profile Scripts to Fix New Sessions
We now know where brew belongs in PATH. But how about new terminal windows and logins?
Fix this permanently by adding that same export line to your profile script.
For the popular Bash shell, append it to ~/.bash_profile or ~/.bashrc:
echo ‘export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"‘ >> ~/.bash_profileZSH users should modify ~/.zshrc similarly:
echo ‘export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"‘ >> ~/.zshrc Don‘t forget to source the profile script or restart your terminal before testing in a new session!
Step 4: Reinstall Homebrew If Symlinks Are Broken
At this point, brew works in an active terminal but often breaks mysteriously in new windows. Time to check for leftover symlinks!
Use the handy realpath utility to determine if PATH locations linking to brew lead somewhere useful:
# Where which brew reports brew is installed
which brew
# Follow that symlink to real location
realpath $(which brew) If the output doesn‘t lead to an actual brew executable, the symlink is outdated and needs fixed. Easiest solution: fully reinstall Homebrew fresh!
# Fully uninstall
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall)"
# Reinstall
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"This will overwrite any troublesome old symlinks with a clean directory structure and current Homebrew release.
Proactive Measures for Avoiding Brew Issues
While the solutions focused on recovery when brew mysteriously disappears, even better is avoiding these issues proactively:
- Stick to the standard installation prefix like
/home/linuxbrewand don‘t move the location manually. All Linux distributions already have this path configured correctly. - Don‘t uninstall or upgrade Homebrew manually. Instead use
brew update && brew upgradeto let Homebrew manage itself safely. - Use the recommended profile script for your shell, like
.bash_profileover.bashrcto centralize environment changes. - Watch for warnings during install/update and run
brew doctoranytime things feel broken. Fix warnings immediately before they escalate!
Following modern Homebrew best practices prevents many odd issues that throw users when self-managed directories get moved, lingering symlinks break, etc. Lean on the smart maintainers and let Homebrew take care of itself!
Closing Thoughts
As you‘ve seen, Linux‘s PATH environment variable and profile shell scripts provide immense power forlookup up and launching commands flexibly system-wide. However, when essential tools like Homebrew‘s brew command mysteriously disappear, they also allow hard-to-spot misconfigurations blocking access.
Luckily by narrowing down the common failure points covered here from missing directories to broken symlinks and refreshing your mental model for how PATH lookups work, most "command not found" errors are quick to isolate and repair.
The key as with any Linux troubleshooting is following a methodical step-by-step guide to rule out potential issues, rather than blind trial-and-error guesses at the cause. I hope the thorough explanations and professional best practices provided in this article help resolve your own brew issues promptly and expand your comfort digging into other Linux environment misconfigurations when issues arise!
Now you have the confidence to swiftly decode and resolve any brew command not found errors. Let me know in the comments if any other creative issues you run into are still causing Homebrew installation headaches on your Linux systems!