The brew doctor command is failing because Homebrew doesn’t have the necessary write permissions to modify files and directories it owns.
Here are the most common reasons and how to fix them:
1. Incorrect Ownership of Homebrew Directories
Diagnosis: Homebrew’s core directories (/usr/local/Cellar, /usr/local/Homebrew, etc.) are owned by root instead of your user. This prevents your user from writing to them.
Check:
ls -ld /usr/local/Cellar
ls -ld /usr/local/Homebrew
Look for root as the owner.
Fix:
sudo chown -R $(whoami) /usr/local/Cellar
sudo chown -R $(whoami) /usr/local/Homebrew
This recursively changes the owner of the specified directories to your current user.
Why it works: By making your user the owner, you gain the necessary write privileges to install, update, and remove packages.
2. Incorrect Ownership of Homebrew Binaries
Diagnosis: Executable files within Homebrew’s bin directory might be owned by root.
Check:
ls -l /usr/local/bin
Scan the output for any files owned by root.
Fix:
sudo chown -R $(whoami) /usr/local/bin
This ensures your user owns all executables in the bin directory.
Why it works: When you try to run a brew command or a command installed by brew, it needs to be executed from a directory where your user has read and execute permissions.
3. Incorrect Permissions on Homebrew Directories (Less Common)
Diagnosis: While ownership is usually the culprit, sometimes the permissions themselves are too restrictive, even if ownership is correct.
Check:
ls -ld /usr/local/Cellar
ls -ld /usr/local/Homebrew
Look for permissions that are not drwxr-xr-x (755) or drwxrwxrwx (777) for directories.
Fix:
sudo chmod -R u+w /usr/local/Cellar
sudo chmod -R u+w /usr/local/Homebrew
This command ensures the owner (u) has write (w) permissions recursively (-R) on these directories.
Why it works: Explicitly granting write permissions to the owner bypasses any restrictive settings that might be inherited or misconfigured.
4. Permissions Issues with /usr/local/opt
Diagnosis: This directory is a symlink target for various package installations. If its permissions or ownership are wrong, installations can fail.
Check:
ls -ld /usr/local/opt
Ensure it’s owned by your user and has appropriate permissions.
Fix:
sudo chown -R $(whoami) /usr/local/opt
This command fixes ownership for the opt directory.
Why it works: Homebrew uses /usr/local/opt to create symbolic links to the actual installed versions of packages, allowing for easy switching between versions. Incorrect permissions here can break these links.
5. Permissions on /usr/local/lib and /usr/local/include
Diagnosis: Similar to bin, Homebrew needs to write to its library and include directories.
Check:
ls -ld /usr/local/lib
ls -ld /usr/local/include
Verify ownership and permissions.
Fix:
sudo chown -R $(whoami) /usr/local/lib
sudo chown -R $(whoami) /usr/local/include
This ensures your user can write to these essential directories.
Why it works: These directories store compiled libraries and header files that are crucial for linking and building software, and Homebrew needs to manage them.
6. Homebrew Installed with sudo (Very Bad)
Diagnosis: If you ever ran brew install or brew update using sudo, you likely made Homebrew’s core components owned by root. This is the most severe case.
Check:
ls -ld /usr/local/Homebrew
If the owner is root, this is the problem.
Fix:
The most robust fix is to re-take ownership as described in point 1. However, if you suspect widespread sudo misuse, a full reset might be cleaner. Proceed with caution.
# Backup your installed formulae list
brew list > ~/brew_formulae_backup.txt
# Uninstall Homebrew (this is destructive!)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
# Reinstall Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Reinstall your packages
xargs brew install < ~/brew_formulae_backup.txt
This process completely removes and reinstalls Homebrew, then reinstalls all your previously installed packages.
Why it works: This method purges all potentially misconfigured files and directories and sets up Homebrew fresh with correct ownership from the start.
After applying these fixes, run brew doctor again. If it still reports issues, it might be a more obscure permission problem or a configuration issue within Homebrew itself.
The next error you’ll hit is zsh: command not found: brew if you’ve accidentally removed Homebrew from your PATH during troubleshooting.