DEV Community

Leon Wong 282
Leon Wong 282

Posted on • Originally published at leonwong282.com

What I Wish I Knew About Homebrew Before Wasting 2 Hours Troubleshooting

#productivity

What I Wish I Knew About Homebrew Before Wasting 2 Hours Troubleshooting

Last Tuesday, I decided to finally install Homebrew on my new MacBook to create a testing environment for writing blog posts. I'd heard it was the "must-have" tool for Mac developers. The installation looked simple enough—copy a command, paste it into Terminal, wait a few minutes. Easy, right?

Thirty minutes later, I was staring at brew: command not found errors. An hour after that, I'd accidentally broken my entire setup with sudo and was desperately Googling "how to fix Homebrew permissions." By hour two, I was questioning every life choice that led me to this moment.

The frustrating part? Every single issue I hit was completely preventable. They're mistakes that thousands of beginners make every day, and they all have simple fixes—if you know what to look for.

If you just installed Homebrew and it's not working, or you're stuck in troubleshooting hell right now, this guide will save you hours. I'm sharing the 5 critical mistakes I made so you don't have to make them too.

Mistake #1: Not Adding Homebrew to Your PATH

The symptom: You successfully install Homebrew, but typing brew install git gives you brew: command not found.

This is the #1 issue beginners face, and it's especially common if you have an Apple Silicon Mac (M1, M2, M3, or M4).

Why it happens:

On Intel Macs, Homebrew installs to /usr/local/bin, which is already in your system's PATH. Your Terminal knows to look there for commands, so everything works automatically.

On Apple Silicon Macs, Homebrew installs to /opt/homebrew/bin instead. This location is not in your PATH by default. When you type brew, your Terminal has no idea where to find it.

During installation, Homebrew displays a message telling you to add it to your PATH. But it's buried in a wall of installation text that most people skim past. I know I did.

The 2-minute fix:

Copy these two lines into your Terminal and press Enter after each:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Enter fullscreen mode Exit fullscreen mode

What this does: The first line adds Homebrew to your shell configuration file permanently. The second line activates it immediately without restarting Terminal.

Verify it worked:

brew --version
Enter fullscreen mode Exit fullscreen mode

If you see Homebrew 4.x.x, you're golden. If not, close Terminal completely (Command + Q) and open it again.

Pro tip: This is only needed on Apple Silicon Macs. If you have an older Intel Mac and brew isn't working, the problem is something else—jump to Mistake #2.

Mistake #2: Using sudo with Homebrew (The Fatal Error)

The symptom: You see "Permission denied" errors and decide to add sudo to your command. It seems to work... until everything breaks.

This is the mistake I regret most. It took me an hour to undo the damage.

Why beginners do this:

On Linux, when you see permission errors, you typically add sudo to run commands as administrator. It's muscle memory for anyone with a bit of Unix experience.

So when Homebrew shows a permission error, your instinct is: "Ah, I need admin privileges. Let me try sudo brew install git."

Why this is catastrophic:

Homebrew is designed to run without sudo. When you use sudo, you create files and directories owned by root (the superuser) instead of your user account.

Now your Homebrew installation is partly owned by you and partly owned by root. Future Homebrew commands fail because they can't modify root-owned files. And the errors snowball from there.

I spent 45 minutes fixing permission issues because of one sudo brew command.

The iron-clad rule:

# ❌ NEVER do this:
sudo brew install git
sudo brew update
sudo anything-with-brew

# ✅ ALWAYS do this:
brew install git
brew update
Enter fullscreen mode Exit fullscreen mode

If you already used sudo, here's how to fix it:

sudo chown -R $(whoami) /opt/homebrew/*
Enter fullscreen mode Exit fullscreen mode

This resets ownership of all Homebrew files back to your user account. Then run brew doctor (more on that in Mistake #3) to verify everything is fixed.

What I wish I knew: Homebrew manages its own permissions elegantly. If you see permission errors, it means something is already wrong with your setup—not that you need sudo. The correct first step is always brew doctor, not sudo.

Mistake #3: Ignoring brew doctor Warnings

The symptom: Homebrew works sometimes but gives weird errors. Software installs but doesn't run correctly. You're not sure if things are actually broken or just quirky.

Why it happens:

Most beginners don't know that Homebrew includes a built-in diagnostic tool. They only discover brew doctor after Googling errors for 30 minutes.

Even when you run it and see warnings, it's tempting to ignore them if things seem to be working. I did this. The warnings felt like suggestions, not requirements.

They're not suggestions.

The preventive fix:

brew doctor
Enter fullscreen mode Exit fullscreen mode

This single command diagnoses 90% of Homebrew issues. It checks your installation, identifies problems, and tells you exactly how to fix them.

What you might see:

Warning: "You have unlinked kegs in your Cellar"

  • What it means: A package is installed but not accessible in your PATH
  • Fix: brew link <package-name>

Warning: "You have not agreed to the Xcode license"

  • What it means: Apple's Command Line Tools need license acceptance
  • Fix: sudo xcodebuild -license then type "agree"

Warning: "Config scripts exist outside your system"

  • What it means: You have conflicting installations from other package managers
  • Fix: Follow the specific instructions Homebrew provides

When to run brew doctor:

  • Immediately after installing Homebrew
  • After installing any complex package (like Python or Node.js)
  • Any time something doesn't work as expected
  • Monthly, as part of your maintenance routine

If brew doctor says "Your system is ready to brew," you're good. If not, read every warning and fix them in order. Don't skip any.

What I wish I knew: Running brew doctor before I tried random Stack Overflow fixes would've pointed me directly to the PATH issue and saved me two hours.

Mistake #4: Not Understanding Formulae vs Casks

The symptom: Error: No available formula with the name "visual-studio-code" even though you know VSCode is available through Homebrew.

Or you install something and can't figure out where it went or how to launch it.

Why it happens:

Homebrew has two types of packages:

Formulae are command-line tools that get compiled and installed. Think: git, python, wget, node.

Casks are GUI applications that get downloaded as pre-built apps. Think: visual-studio-code, firefox, slack, zoom.

The command syntax is different, and beginners constantly forget the --cask flag.

The fix:

For command-line tools (formulae):

brew install git
brew install python
brew install wget
Enter fullscreen mode Exit fullscreen mode

For GUI applications (casks):

brew install --cask visual-studio-code
brew install --cask firefox
brew install --cask slack
Enter fullscreen mode Exit fullscreen mode

How to check which type you need:

brew search visual-studio-code
Enter fullscreen mode Exit fullscreen mode

The output shows whether it's in "Formulae" or "Casks." If it says Casks, you need the --cask flag.

Rule of thumb: If you want something with a graphical interface that normally lives in your Applications folder, you almost always need --cask. Command-line tools never need it.

What I wish I knew: I wasted 15 minutes trying to install VSCode without --cask, convinced the package name was wrong. A quick brew search would've told me exactly what I needed.

Mistake #5: Skipping the Caveats

The symptom: Software installs successfully, but when you try to use it, nothing happens. Or it works but not the way you expected.

Why it happens:

After installing a package, Homebrew displays "Caveats"—important post-installation instructions. These often include:

  • Commands to add the tool to your PATH
  • How to start services (like databases)
  • Configuration steps required before first use
  • Version-specific warnings

Beginners see a wall of text, assume it's optional, and close Terminal. Or they don't scroll back up to read what was printed 50 lines ago.

Example caveat that breaks things if ignored:

==> Caveats
To start mysql now and restart at login:
  brew services start mysql

Or, if you don't want to run it as a service:
  mysql.server start
Enter fullscreen mode Exit fullscreen mode

If you don't run one of these commands, MySQL is installed but not running. You'll get "connection refused" errors and think the installation failed.

The fix:

After every installation, scroll back and read the caveats. Actually read them, word by word. If they tell you to run a command, run it.

Viewing caveats later:

brew info <package-name>
Enter fullscreen mode Exit fullscreen mode

This shows the package information including all caveats, even if you closed Terminal hours ago.

What I wish I knew: Those caveats aren't suggestions or nice-to-know tips. They're required steps to make the software actually work. Treat them like installation instructions, not optional reading.

Bonus Mistake: Forgetting to Update

The symptom: Packages you know exist show "formula not found" errors. Or you install outdated versions with known security issues.

Why it happens:

Homebrew's package definitions live in a Git repository. Over time, they get stale on your local machine. New packages aren't visible, and version information gets outdated.

The fix:

brew update
Enter fullscreen mode Exit fullscreen mode

Run this before installing anything new. It takes 5-30 seconds and updates Homebrew itself plus all package definitions.

Make it a habit: Update weekly as part of your maintenance routine:

brew update && brew upgrade && brew cleanup
Enter fullscreen mode Exit fullscreen mode

This updates definitions, upgrades all installed packages, and removes old versions to free disk space.

The 5-Minute Troubleshooting Checklist

When Homebrew isn't working, run these commands in order:

# 1. Is Homebrew in your PATH?
which brew

# 2. What's wrong?
brew doctor

# 3. Are your package definitions current?
brew update

# 4. Is the specific package available?
brew search <package-name>

# 5. Check ownership (Apple Silicon)
ls -la /opt/homebrew | head
Enter fullscreen mode Exit fullscreen mode

90% of the time, brew doctor identifies the exact problem and tells you how to fix it.

Key Takeaways

Two hours of troubleshooting taught me what five minutes of preparation could have prevented:

  • Add Homebrew to your PATH (Apple Silicon Macs require manual setup)
  • Never use sudo with Homebrew commands (it breaks permissions permanently)
  • Run brew doctor first, Google second (diagnostics before desperation)
  • Use --cask for GUI apps (VSCode, Firefox, Slack need this flag)
  • Read the caveats every time (they're required steps, not optional)

The pattern is always the same: skip the setup instructions, ignore the warnings, spend hours troubleshooting what could've been prevented in minutes.

Next steps:

  1. Run brew doctor right now (even if things seem to work)
  2. Bookmark this guide for when you hit issues
  3. Read the official Homebrew documentation for deeper understanding

What was your biggest Homebrew mistake? I'd love to hear if you've hit these same issues or discovered other gotchas I missed. Drop a comment below.

Related Resources

  • How I Stopped Manually Installing Software on Mac (And You Should Too) — Complete Homebrew tutorial for beginners
  • Why Your Mac Software Installation is Broken (And How to Fix It in 10 Minutes) — Why package managers matter
  • Homebrew Official Documentation — Full command reference and guides

Top comments (1)

Collapse
 
roshan_sharma_7deae5e0742 profile image
roshan sharma •

That’s a super practical write-up! You nailed every mistake beginners make with Homebrew and explained the fixes clearly. Really solid mix of storytelling and actionable advice.