DEV Community

AttractivePenguin
AttractivePenguin

Posted on

Homebrew Broken After macOS Update? Here's Your Fix in 5 Minutes

#macos #homebrew #devops #tutorial

Homebrew Broken After macOS Update? Here's Your Fix in 5 Minutes

You ran brew install and got "Permission denied." Your updates are stuck. brew doctor is yelling at you. Let's fix it—permanently.

Why This Happens (and Why It Keeps Happening)

Every macOS update has the potential to break Homebrew. Here's why:

  • Permission resets: macOS updates often reset /usr/local or /opt/homebrew permissions to root:wheel
  • Path confusion: Apple Silicon Macs use a different Homebrew location than Intel Macs
  • Xcode Command Line Tools: Updates can break or reset the tools Homebrew depends on
  • Unfinished installations: A Ctrl+C at the wrong time leaves orphaned locks and partial files

If you've ever seen Error: Permission denied @ dir_s_mkdir or Error: Cannot write to /usr/local, you're not alone. This is one of the most common developer headaches on macOS.

The good news? It's fixable in minutes with the right commands.

The 3 Most Common Homebrew Problems

Problem 1: Permission Denied Errors

Symptoms:

Error: Permission denied @ dir_s_mkdir - /usr/local/Cellar
Error: Permission denied @ apply2files - /usr/local/bin
Enter fullscreen mode Exit fullscreen mode

The Fix:

For Intel Macs (pre-2020):

# Fix all Homebrew directories
sudo chown -R $(whoami) /usr/local/bin /usr/local/etc /usr/local/include /usr/local/lib /usr/local/sbin /usr/local/share /usr/local/var /usr/local/opt /usr/local/Cellar /usr/local/Homebrew

# Alternative: Fix just the Homebrew prefix
sudo chown -R $(whoami) "$(brew --prefix)"/*
Enter fullscreen mode Exit fullscreen mode

For Apple Silicon Macs (M1/M2/M3):

# Apple Silicon uses /opt/homebrew
sudo chown -R $(whoami) /opt/homebrew/bin /opt/homebrew/etc /opt/homebrew/include /opt/homebrew/lib /opt/homebrew/sbin /opt/homebrew/share /opt/homebrew/var /opt/homebrew/opt /opt/homebrew/Cellar /opt/homebrew/Homebrew

# Or use the Homebrew prefix directly
sudo chown -R $(whoami) "$(brew --prefix)"/*
Enter fullscreen mode Exit fullscreen mode

Why this works: macOS updates reset ownership to root:wheel. Homebrew needs your user to own these directories to install and update packages.

Problem 2: "brew update" Stuck or Failing

Symptoms:

Error: Fetching /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core failed!
fatal: could not read Username for 'https://github.com': terminal prompts disabled
Enter fullscreen mode Exit fullscreen mode

The Fix:

# Step 1: Update Homebrew core (run this twice—yes, really)
brew update
brew update

# Step 2: Run diagnostics
brew doctor

# Step 3: Fix whatever brew doctor reports
brew doctor | xargs brew install

# If that doesn't work, reset the Homebrew core tap
cd "$(brew --repository homebrew/core)"
git fetch --unshallow 2>/dev/null || git fetch
git reset --hard origin/master
brew update
Enter fullscreen mode Exit fullscreen mode

Pro tip: Running brew update twice ensures all taps are synchronized. The first run might partially succeed; the second completes the job.

Problem 3: Wrong Path on Apple Silicon

Symptoms:

which brew
# /usr/local/bin/brew  ← Wrong! (Intel path on Apple Silicon)

brew install node
# Error: Cannot install on Intel-only path
Enter fullscreen mode Exit fullscreen mode

The Fix:

# Check your current Homebrew path
brew --prefix

# Apple Silicon should show: /opt/homebrew
# Intel should show: /usr/local

# If you're on Apple Silicon but seeing /usr/local, reinstall Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add to your shell config (~/.zshrc or ~/.bashrc)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

# Verify
which brew
# Should output: /opt/homebrew/bin/brew
Enter fullscreen mode Exit fullscreen mode

Why this matters: Apple Silicon Macs need Homebrew in /opt/homebrew to work correctly. The Intel path (/usr/local) can cause subtle issues with package compilation and library linking.

The Complete Homebrew Health Check

Run this diagnostic sequence to catch everything:

# 1. Update Homebrew itself
brew update

# 2. Check for issues
brew doctor

# 3. List what needs attention
brew missing

# 4. Fix permission issues (Intel)
sudo chown -R $(whoami) /usr/local/{bin,etc,include,lib,sbin,share,var,opt,Cellar,Homebrew}

# OR fix permission issues (Apple Silicon)
sudo chown -R $(whoami) /opt/homebrew/{bin,etc,include,lib,sbin,share,var,opt,Cellar,Homebrew}

# 5. Remove old versions
brew cleanup

# 6. Check for broken packages
brew doctor

# 7. Reinstall anything broken
brew missing | xargs brew install
Enter fullscreen mode Exit fullscreen mode

Real-World Scenarios

Scenario 1: Fresh macOS Install After Update

You just updated macOS and now brew install fails.

# Full repair sequence
sudo chown -R $(whoami) "$(brew --prefix)"/*
brew update-reset
brew update
brew doctor
brew upgrade

# If Xcode Command Line Tools are broken
xcode-select --install
# Or reset them:
sudo xcode-select --reset
sudo xcode-select --install
Enter fullscreen mode Exit fullscreen mode

Scenario 2: Team Shared Mac with Multiple Users

Multiple developers use the same Mac. Homebrew permissions are chaos.

# Create a homebrew group
sudo dscl . create /Groups/homebrew
sudo dscl . create /Groups/homebrew PrimaryGroupID 500

# Add users to the group
sudo dscl . append /Groups/homebrew GroupMembership user1
sudo dscl . append /Groups/homebrew GroupMembership user2

# Set group ownership
sudo chgrp -R homebrew "$(brew --prefix)"
sudo chmod -R g+w "$(brew --prefix)"

# Each user runs this once:
echo 'export HOMEBREW_BREW_FILE_CHECKDIR_VERBOSE=1' >> ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Scenario 3: CI/CD Pipeline Failing

Your GitHub Actions workflow fails on brew install.

# .github/workflows/test.yml
jobs:
  test:
    runs-on: macos-latest
    steps:
      - name: Fix Homebrew permissions
        run: |
          sudo chown -R $(whoami) "$(brew --prefix)"/*
        # Note: GitHub Actions usually has correct permissions
        # Only needed for self-hosted runners

      - name: Install dependencies
        run: |
          brew update
          brew install node@20 python@3.12
Enter fullscreen mode Exit fullscreen mode

For self-hosted macOS runners, run this once:

# As root on the runner
sudo chown -R runner:runner "$(brew --prefix)"/*
Enter fullscreen mode Exit fullscreen mode

Prevention: How to Avoid This in the Future

1. Never Use sudo with brew install 

# ❌ NEVER do this
sudo brew install something

# ✅ Always use regular user
brew install something
Enter fullscreen mode Exit fullscreen mode

If you need elevated permissions, something is wrong. Fix the permissions instead.

2. Run brew doctor After macOS Updates

Make it a habit:

# After every macOS update
brew update && brew doctor && brew upgrade
Enter fullscreen mode Exit fullscreen mode

3. Use a Brewfile for Reproducible Setups

Create a Brewfile:

# Brewfile
tap "homebrew/core"
tap "homebrew/cask"

# Development
brew "git"
brew "node"
brew "python@3.12"
brew "terraform"

# Applications
cask "visual-studio-code"
cask "docker"
cask "rectangle"

# Mas apps (Mac App Store)
mas "Xcode", id: 497799835
Enter fullscreen mode Exit fullscreen mode 
# Install everything
brew bundle install

# Restore after disaster
brew bundle install --file=Brewfile
Enter fullscreen mode Exit fullscreen mode

4. Check Your Path Regularly

Add to your shell config:

# ~/.zshrc or ~/.bashrc
# Apple Silicon Homebrew path
if [[ -d /opt/homebrew/bin ]]; then
    eval "$(/opt/homebrew/bin/brew shellenv)"
fi

# Intel Homebrew path (for older Macs or Rosetta)
if [[ -d /usr/local/bin && ! -d /opt/homebrew/bin ]]; then
    eval "$(/usr/local/bin/brew shellenv)"
fi
Enter fullscreen mode Exit fullscreen mode

FAQ: Common Questions

Why does brew doctor show warnings I can ignore?

brew doctor is cautious. Some warnings are cosmetic:

  • "Your Homebrew is not at the correct location" → Only worry if brew --prefix is wrong
  • "Some kegs are not linked" → Fine for version managers (nvm, pyenv)
  • "Unbrewed files in /usr/local" → Normal for some CLI tools

Rule of thumb: Fix errors (red ✗), evaluate warnings (yellow ▲), ignore info (blue ℹ).

Can I reinstall Homebrew without losing my packages? 

# Export your installed packages
brew bundle dump --file=/tmp/Brewfile

# Uninstall Homebrew
/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)"

# Restore your packages
brew bundle install --file=/tmp/Brewfile
Enter fullscreen mode Exit fullscreen mode

How do I check if my Homebrew is Intel or Apple Silicon? 

brew --prefix
# /opt/homebrew → Apple Silicon (correct)
# /usr/local → Intel (correct on Intel Macs, wrong on Apple Silicon)
Enter fullscreen mode Exit fullscreen mode

Or check the architecture:

arch
# arm64 → Apple Silicon
# i386 → Intel (or Rosetta)

# Check which architecture brew is running as
file $(which brew)
Enter fullscreen mode Exit fullscreen mode

My brew install is downloading forever. Help?

This is usually a slow mirror or network issue:

# Check if it's stuck
brew config | grep -E "HOMEBREW_BOTTLE_DOMAIN|HOMEBREW_API_DOMAIN"

# Use faster mirrors (optional)
export HOMEBREW_BOTTLE_DOMAIN=https://ghcr.io/v2/homebrew/core
export HOMEBREW_API_DOMAIN=https://formulae.brew.sh/api

# Add to ~/.zshrc for persistence
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://ghcr.io/v2/homebrew/core' >> ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

What's the difference between brew install and brew install --cask?

  • brew install formula → CLI tools, libraries, languages (installed to $(brew --prefix))
  • brew install --cask app → macOS applications (installed to /Applications)
  • brew install --formula node → Explicit formula install
  • brew install node → Auto-detects (formula for node)

Should I use Homebrew or MacPorts?

For most developers: Homebrew. It's the de facto standard:

  • Larger package ecosystem
  • Better integration with development tools
  • Simpler binary packages (no long compiles)
  • Active maintenance and community

MacPorts is fine if you need specific Unix packages not in Homebrew, but you'll likely need both.

The 5-Minute Fix Checklist

If you're in a hurry, run this sequence:

# ✅ Fix permissions (copy-paste the right one for your Mac)
# Apple Silicon:
sudo chown -R $(whoami) /opt/homebrew/{bin,etc,include,lib,sbin,share,var,opt,Cellar,Homebrew}

# Intel:
sudo chown -R $(whoami) /usr/local/{bin,etc,include,lib,sbin,share,var,opt,Cellar,Homebrew}

# ✅ Update Homebrew
brew update && brew update

# ✅ Diagnose issues
brew doctor

# ✅ Fix reported issues
brew doctor | grep -E "Error|Warning" | xargs -I {} sh -c 'echo "Fix: {}"'

# ✅ Clean up old versions
brew cleanup

# ✅ Verify everything works
brew --version
brew config
Enter fullscreen mode Exit fullscreen mode

Conclusion

Homebrew permission issues are frustrating but fixable. The key commands to remember:

  1. sudo chown -R $(whoami) "$(brew --prefix)"/* — Fix permissions
  2. brew update (run twice) — Synchronize taps
  3. brew doctor — Diagnose everything
  4. brew cleanup — Remove old versions

If you just upgraded macOS and Homebrew is broken, the 5-minute fix above will almost certainly solve it.

Your Action Items

  • [ ] Run brew doctor right now and fix any errors
  • [ ] Check your Homebrew path matches your Mac architecture
  • [ ] Create a Brewfile for easy restores
  • [ ] Add Homebrew path setup to your shell config

When did Homebrew last break for you? Was it a macOS update, or something else? Drop a comment—I'm curious what the most common triggers are.

Top comments (0)