Setting up a development environment on macOS usually starts with a simple command-line package manager. Homebrew simplifies installing command-line tools, programming languages, and desktop apps without digging through custom installers or dragging files into the Applications folder. If you've ever tried to compile software or fetch the latest version of Git on a Mac, you know Apple's default command-line tools only get you so far.
Installing Homebrew requires pasting a single line of code into your Terminal application and waiting a few minutes for the script to download, compile, and configure the necessary directories. Whether you're configuring a brand-new Apple Silicon Mac or setting up an older Intel-based machine, this guide covers the exact installation steps, post-install configuration, troubleshooting common pitfalls, and everyday package management commands.
Prerequisites and System Requirements
Before running the installation script, verify your Mac meets the baseline software and hardware requirements. Homebrew supports modern versions of macOS and requires a few foundational command-line utilities.
- macOS Version: macOS Catalina (10.15) or newer is required for recent Homebrew releases. If you're running an older operating system, Homebrew will either fail to install or drop support for package updates.
- Command Line Tools for Xcode: Homebrew compiles software from source when precompiled binaries aren't available. You need the Xcode Command Line Tools installed. You don't need the full Xcode application, which saves over 30 gigabytes of disk storage.
- Administrator Privileges: You must have an administrator account with permission to run
sudocommands, as the installer writes files to system-protected directories. - Shell Environment: Modern macOS versions use
zshas the default interactive shell. Homebrew integrates directly into your shell profile to ensure installed packages are immediately accessible in your PATH.
Step-by-Step Installation
The official installation script handles downloading the core repository and configuring your directory paths automatically. Follow these exact steps to get up and running. If you want more about the context here, Associated Press offers an informative breakdown.
Step 1: Open Terminal
Press Command + Spacebar to open Spotlight search, type Terminal, and press Return. You'll see a command prompt displaying your username and local machine name ending with a percentage sign or dollar sign.
Step 2: Install Xcode Command Line Tools
Before executing the Homebrew script, verify your command line tools are present. Paste this command into Terminal and press Return:
xcode-select --install
A dialog box will appear prompting you to install the software. Click Install, agree to the terms, and wait for the download and installation to finish. This process can take anywhere from two to ten minutes depending on your internet connection.
Step 3: Run the Homebrew Installer Script
Copy the official installation command from the Homebrew Documentation or use the standard script below. Paste it directly into your Terminal window and press Return:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
The script will output a detailed list of directories it plans to create and modify. Press Return when prompted to confirm your password and proceed with the installation.
Step 4: Add Homebrew to Your PATH
Once the script completes, it will display a Next steps block at the bottom of your Terminal screen. On Apple Silicon (M1, M2, M3, M4) Macs, Homebrew installs into /opt/homebrew, while Intel Macs use /usr/local.
To ensure your shell can find the brew command, run the specific commands provided by the script output. For Apple Silicon Macs, run:
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"
Step 5: Verify the Installation
Test that everything works correctly by running the diagnostic command:
brew doctor
If the output reads Your system is ready to brew, you're fully configured. If it reports warnings, follow the suggested terminal fixes provided in the diagnostic output.
Core Package Management Commands
Once installed, Homebrew relies on a straightforward syntax for managing software. Here are the primary commands you'll use daily.
- Search for a package: To find if a tool or application is available, run
brew search [package-name]. - Install a package: To download and install a tool, run
brew install [package-name]. For example,brew install gitfetches the latest version of Git. - Update Homebrew: To fetch the newest package definitions from GitHub, run
brew update. - Upgrade installed packages: To update all outdated software on your system, run
brew upgrade. - Uninstall a package: To remove a tool cleanly, run
brew uninstall [package-name].
Managing Desktop Applications with Casks
Homebrew isn't just for command-line utilities. Through an extension called Homebrew Cask, you can install standard macOS graphical applications—like browsers, code editors, and chat clients—straight from the terminal.
Instead of visiting download pages, mounting disk images, and dragging apps to your Applications folder, you can install apps with a single command:
brew install --cask firefox
Casks manage updates for your graphical software just like command-line tools. Running brew upgrade --cask checks all installed GUI apps for available updates and installs them in the background.
Common Installation Mistakes and Troubleshooting
Even with a streamlined installer, edge cases and permission errors can occasionally occur. Knowing how to troubleshoot saves hours of frustration.
- Permission Denied Errors: If you see permission warnings during installation, your local user folders may have incorrect ownership settings. Fix ownership on Apple Silicon Macs by running
sudo chown -R $(whoami) /opt/homebrew. - Command Not Found: If Terminal replies with
zsh: command not found: brew, your PATH variable wasn't updated correctly. Re-run theeval "$(/opt/homebrew/bin/brew shellenv)"command matching your Mac architecture. - Slow Downloads: If the installation script stalls or downloads slowly, check your DNS settings or corporate firewall restrictions. GitHub raw content domains must be accessible for the installation script to fetch repository files.
Frequently Asked Questions
Do I need to uninstall Homebrew when updating macOS?
No. Homebrew persists across macOS system updates. However, major operating system upgrades occasionally require you to run brew update and brew doctor to recompile certain packages that depend on specific macOS SDK versions.
Where does Homebrew store downloaded files?
Homebrew downloads source code and precompiled bottles into a local cache directory. You can check your cache size or clear old downloads safely by running brew cleanup in your terminal.
Can I use Homebrew without administrator privileges?
Homebrew is designed to work best with standard administrator privileges. While unprivileged or custom prefix installations are possible, they require manual directory configuration and prevent certain cask applications from installing correctly.
How do I completely remove Homebrew from my Mac?
If you want to wipe Homebrew from your system entirely, you can download and run the official uninstallation script provided in the Homebrew GitHub Repository. This removes all installed taps, formulae, and directories created during setup.
