Installing Homebrew on macOS: A Complete Beginner's Guide

Introduction / Why This Is Needed

Homebrew (or simply brew) is an indispensable package manager for macOS that simplifies the installation, update, and removal of thousands of free utilities, libraries, and applications missing from the official App Store. After installation, you'll be able to install tools like git, python, node, wget, ffmpeg, and many more with a single command. It is the de facto standard for developers and system administrators on Mac.

Requirements / Preparation

Before you begin, ensure that:

1. You have a Mac with macOS 10.14 (Mojave) or newer.
2. You have access to an administrator account (to enter your password during installation).
3. You have Xcode Command Line Tools installed. If not, the first step of this guide will help you install them.
4. You have a stable internet connection.

Step-by-Step Guide

Step 1: Check for Xcode Command Line Tools

Homebrew directly depends on these tools. Open Terminal (via Spotlight Cmd+Space -> "Terminal" or in /Applications/Utilities/) and run:

xcode-select --install

If the tools are already installed, the system will notify you. If not, a dialog will appear—click "Install" and follow the instructions. The installation will take a few minutes.

Step 2: Download and Run the Official Installation Script

In the same Terminal window, run the command to download and execute the installation script:

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

⚠️ Important: Always verify the script's URL. The official Homebrew repository is github.com/Homebrew/install.

The script will explain in detail what it will do and will prompt for your password (characters are not displayed as you type—this is normal). Press Enter after typing it. Wait for the installation to complete.

Step 3: Configure the PATH Environment Variable

After installation, the script will output instructions for adding Homebrew to your PATH (the variable that determines where the system looks for executable files). This is a critical step.

1. Identify your Mac's architecture:
   • Apple Silicon (M1, M2, M3 and newer): Homebrew installs to /opt/homebrew.
   • Intel: Homebrew installs to /usr/local.
2. Open your shell's configuration file. For standard macOS (Zsh, starting with Catalina) this is ~/.zprofile:

   nano ~/.zprofile
   

   
   Or for older versions using Bash: nano ~/.bash_profile.
3. Add one of the following lines to the end of the file (depending on your architecture):
   • For Apple Silicon:

     eval "$(/opt/homebrew/bin/brew shellenv)"
     

   • For Intel:

     eval "$(/usr/local/bin/brew shellenv)"
     

4. Save (Ctrl+O, Enter) and exit the editor (Ctrl+X).
5. Apply the changes to your current Terminal session:

   source ~/.zprofile  # or source ~/.bash_profile
   

Step 4: Verify the Installation

Run the two main verification commands:

brew doctor

This command will analyze your system. In an ideal case, you will see Your system is ready to brew.. If there are warnings, read them carefully—brew doctor often suggests specific solutions.

brew --version

This command will show the installed Homebrew version (e.g., Homebrew 4.2.0). If the brew command is not found, go back to Step 3 and double-check your PATH configuration.

Verification of Results

A successful installation is confirmed by:

1. The brew --version and brew doctor commands working without errors.
2. You can install a simple application. For example, install the wget utility:

   brew install wget
   

   After it completes, try running wget --version.

Potential Issues

• Permission denied error when running the installation script.
  • Cause: You lack write permissions to system directories.
  • Solution: Ensure you are working from your primary user account (not via root or a guest account). Do not use sudo to install Homebrew. If the problem persists, check the permissions on the target folder (/usr/local or /opt/homebrew).
• brew command not found after installation.
  • Cause: The PATH is not configured correctly.
  • Solution: Carefully repeat Step 3. Ensure you added the line to the correct configuration file (~/.zprofile for Zsh) and applied the changes with the source command.
• Command Line Tools are already installed, but they are not configured. error from xcode-select.
  • Cause: The tools are installed, but the path to them is not set.
  • Solution: Run sudo xcode-select --reset or set the path explicitly: sudo xcode-select -s /Library/Developer/CommandLineTools.
• Download errors (curl: (7) Failed to connect).
  • Cause: Issues with network connectivity or a block by a corporate firewall/proxy.
  • Solution: Check your internet connection. If you are on a corporate network, you may need to configure a proxy for curl or use an alternative installation method.