Installing Homebrew on macOS: A Step-by-Step Guide for Beginners

Introduction / Why You Need This

Homebrew (or simply brew) is a package manager for macOS that simplifies the installation, updating, and removal of thousands of open-source programs and libraries. Instead of manually downloading .dmg files, hunting for dependencies, and configuring environment variables, you use a single command:

brew install <program_name>

This guide shows how to properly install Homebrew from scratch on any modern version of macOS (from Monterey to Sonoma) on both Intel and Apple Silicon (M1/M2/M3) processors.

Prerequisites / Preparation

Before you begin, ensure that:

1. You have a user account with administrator privileges (ability to use sudo).
2. Xcode Command Line Tools are installed. Homebrew will offer to install them automatically, but if you prefer to do it beforehand, run in Terminal:

   xcode-select --install
   

3. You have a stable internet connection.

Step-by-Step Instructions

Step 1: Run the Official Installation Script

This is the only and most important step. Never install Homebrew from untrusted sources. Use only the official script:

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

What the command does:

• curl -fsSL ... — downloads the install script from GitHub, following redirects (-L), hiding progress (-s), and failing silently on errors (-f).
• $(...) — executes the downloaded script in the current shell.
• /bin/bash -c — explicitly runs the script in bash, even if your terminal defaults to zsh (relevant for macOS Catalina+).

Step 2: Enter Your Administrator Password

After running the script, the system will prompt for your password. Type it all in lowercase; characters will not be displayed (not even asterisks) — this is a macOS security feature. Simply type your password and press Enter.

Step 3: Wait for Installation to Complete

The script will perform the following actions:

1. Check for Xcode Command Line Tools and install them if necessary (you may need to click "Install" in a separate popup window).
2. Create the necessary directories (/usr/local for Intel or /opt/homebrew for Apple Silicon).
3. Download and unpack the latest stable version of Homebrew.
4. Configure environment variables in your shell profile (.zprofile for zsh, .bash_profile for bash).

Do not interrupt the process! It can take up to 10 minutes, especially on the first run when installing Xcode Tools.

Step 4: Activate Homebrew in the Current Session

After installation completes, the script will output instructions. To make the brew command available immediately in your current Terminal window, run:

• For macOS on Apple Silicon (M1/M2/M3):

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

• For macOS on Intel:

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

Alternatively, simply close and reopen Terminal — the changes will take effect automatically.

Verification

Confirm the installation was successful:

1. Check the version:

   brew --version
   

   
   Output should look like: Homebrew 4.x.x.
2. Run diagnostics:

   brew doctor
   

   
   Ideal output: Your system is ready to brew. If there are warnings — follow their advice.
3. Try installing a simple utility (e.g., wget):

   brew install wget
   

   
   After a successful install, run wget --version.

Troubleshooting

Error: Permission denied or Operation not permitted

Cause: Terminal is not running with administrator rights, or the script cannot write to the target directory. Solution: Ensure you entered your password when prompted. If the problem persists, try running the script with sudo (though the official instructions do not require this):

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

Error: Command Line Tools already installed

Cause: Xcode Command Line Tools are already present, but their path is not configured. Solution: Run sudo xcode-select --reset or set the path explicitly: sudo xcode-select -s /Library/Developer/CommandLineTools.

Error: brew: command not found after installation

Cause: The PATH variable was not updated in the current session. Solution: Follow Step 4 above (activation via eval) or restart Terminal.

Slow Installation or Interruptions

Cause: Network issues or problems with GitHub. Solution: Install Homebrew via a domestic mirror (like Tsinghua source) or use a VPN. To switch repositories, run:

cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
git remote set-url origin https://mirror.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git

Frequently Asked Questions (FAQ)

Can I uninstall Homebrew? Yes. For a complete removal, run the official uninstall script:

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

Then manually remove residual files: rm -rf ~/.brew (if it exists) and the lines from .zprofile/.bash_profile.

How do I update Homebrew and installed packages? Update Homebrew: brew update. Upgrade all packages: brew upgrade. To clean up old versions: brew cleanup.

What are Formulae and Casks?

• Formulae — packages with command-line utilities and libraries (e.g., python, git).
• Casks — packages with GUI applications in .dmg/.pkg format (e.g., firefox, visual-studio-code). Installed with brew install --cask <name>.

Can I use Homebrew alongside MacPorts or Fink?No. These package managers conflict because they use identical paths. Choose one. Homebrew is the most popular and recommended for most users.