How to Fix macOS Homebrew Installation Error

In this tutorial, you'll learn about How to Fix macOS Homebrew Installation Error. We cover key concepts, practical examples, and best practices.

The Problem

You run the Homebrew installation command and get:

curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused

Or:

/usr/local/bin is not writable. You should change the ownership
of /usr/local/bin to your user.

Homebrew installation fails because of network restrictions, file permission issues, or missing dependencies.

Quick Fix

Step 1: Check internet connectivity and DNS

ping -c 3 raw.githubusercontent.com

If the ping fails, check your DNS settings:

networksetup -setdnsservers Wi-Fi 8.8.8.8 8.8.4.4

Some corporate networks block GitHub URLs. Try using a VPN or mobile hotspot.

Step 2: Install Xcode Command Line Tools first

xcode-select --install

Homebrew requires the command line tools. If the dialog does not appear:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Step 3: Use the official installation command correctly

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Copy the command directly from brew.sh to avoid typos.

Step 4: Fix /usr/local permissions (Intel Macs)

sudo chown -R $(whoami):staff /usr/local

This changes ownership of /usr/local to your user, allowing Homebrew to install without sudo.

Step 5: Fix /opt/homebrew permissions (Apple Silicon)

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

Apple Silicon Macs install Homebrew to /opt/homebrew.

Step 6: Add Homebrew to PATH

After installation, add to your shell profile:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

For Intel Macs:

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc

Step 7: Resolve "Command Line Tools are outdated"

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Step 8: Use a mirror for the installation script

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Mirrors can bypass regional network restrictions.

Prevention

• Keep Xcode Command Line Tools updated.
• Install Homebrew on a clean macOS setup.
• Run brew doctor periodically to check for issues.

Common Mistakes with homebrew error

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world MACOS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech Tool Reference

Doda Browser's Package Manager Monitor tracks Homebrew installation progress and logs errors to a searchable file for post-hoc debugging.