Fix Homebrew Error: "The following directories are not writable by your user"

Why This Happens

Homebrew usually works like a charm, but it gets grumpy about file permissions. You will likely see this error when running brew install or brew upgrade. It is a common headache after a major macOS update, like moving to Sonoma, or after migrating data to a new M3 MacBook Pro. Sometimes, it is simply because you accidentally ran a command using sudo, which handed ownership of your folders over to the system root.

On Apple Silicon Macs, Homebrew lives in /opt/homebrew. Older Intel Macs keep it in /usr/local. The error means Homebrew wants to drop files into the zsh folders, but your user account doesn't have the keys to the front door.

Error: The following directories are not writable by your user:
/opt/homebrew/share/zsh
/opt/homebrew/share/zsh/site-functions

The Debug Process

Let's see who actually owns those folders. Open your terminal and run this command:

ls -ld /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

Check the third column of the output. If it says root, that is your problem. Your terminal output will look like this:

drwxr-xr-x  3 root  admin  96 Oct 24 10:00 /opt/homebrew/share/zsh
drwxr-xr-x  2 root  admin  64 Oct 24 10:00 /opt/homebrew/share/zsh/site-functions

Homebrew is designed to run without root privileges to keep your Mac secure. It will refuse to install anything until you, the user, own these directories again.

The Solution

The fix is straightforward. We use the chown (change owner) command to take back control. You will need to use sudo just this once to authorize the hand-off.

1. Fix Ownership for Specific Directories

To fix the specific folders mentioned in the error, run:

sudo chown -R $(whoami) /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

Here is what that command does:

• sudo: Gives you temporary admin powers to change system folders.
• -R: Tells the command to fix everything inside those folders too.
• $(whoami): A shortcut that automatically types your Mac username for you.

2. The "Fix Everything" Approach (Recommended)

If you see multiple permission errors, it is faster to fix the entire Homebrew path at once. This saves you from playing "whack-a-mole" with future errors.

For Apple Silicon (M1, M2, M3):

sudo chown -R $(whoami) /opt/homebrew

For Intel Macs:

sudo chown -R $(whoami) /usr/local/bin /usr/local/etc /usr/local/sbin /usr/local/share /usr/local/var

3. Double-Check Permissions

Ownership is usually the culprit, but sometimes the write permissions themselves are wrong. Directories should generally be set to 755. If you want to visualize these settings before applying them, check out a Unix Permissions Calculator. It helps ensure you aren't making folders too open, like the risky 777 setting.

chmod u+w /opt/homebrew/share/zsh /opt/homebrew/share/zsh/site-functions

Verification

Run the Homebrew diagnostic tool to make sure everything is healthy:

brew doctor

If the fix worked, you will see: Your system is ready to brew. Now you can go back to installing your packages, like brew install node or brew install python, without any further issues.

Pro-Tips for the Future

• Avoid sudo with brew: Never run sudo brew install. It is the number one cause of broken permissions.
• Post-Update Ritual: macOS updates often reset permissions on shared folders. If things feel slow or broken after an update, run brew doctor immediately.
• User vs. Root: Most Homebrew issues stem from ownership (who owns the file) rather than permissions (what can be done to the file). Always check the owner first.