Fixing zsh command not found: brew? (installing Homebrew)

Learn fixing zsh command not found: brew? (installing homebrew) with practical examples, diagrams, and best practices. Covers macos, homebrew, apple-m1 development techniques with visual explanations.

Fixing 'zsh: command not found: brew' on macOS (Installing Homebrew)

Hero image for Fixing zsh command not found: brew? (installing Homebrew)

Encountering 'zsh: command not found: brew' is a common hurdle for new macOS users or those setting up a fresh development environment. This guide will walk you through installing Homebrew, the essential package manager for macOS, and resolving common path issues, especially on Apple Silicon (M1/M2/M3) Macs.

Homebrew is an indispensable package manager for macOS, allowing you to easily install command-line tools, applications, and utilities that Apple doesn't provide by default. When you try to use brew and get the zsh: command not found: brew error, it typically means Homebrew isn't installed or its executable path isn't correctly configured in your shell's environment variables. This article will guide you through the installation process and ensure brew is accessible from your terminal.

Understanding the 'command not found' Error

The zsh: command not found error indicates that your shell (Zsh, the default on modern macOS) cannot locate the executable file for the command you typed. When you type brew, Zsh searches through a list of directories specified in your PATH environment variable. If brew isn't in any of those directories, or if Homebrew itself isn't installed, you'll see this error. This is particularly common on new macOS installations or after migrating to an Apple Silicon machine, where Homebrew might install to a different default location.

flowchart TD
    A[User types 'brew' in Zsh] --> B{Is 'brew' in PATH?}
    B -- No --> C["zsh: command not found: brew"]
    B -- Yes --> D{Is 'brew' executable?}
    D -- No --> E["Permission Denied / Corrupt Install"]
    D -- Yes --> F[Execute 'brew' command]

Flowchart illustrating the shell's process when a command is entered.

Installing Homebrew on macOS

The official Homebrew installation script handles most of the heavy lifting, including setting up the correct paths. It's designed to be run directly from your terminal. Before you begin, ensure you have Xcode Command Line Tools installed, as Homebrew relies on them.

1. Install Xcode Command Line Tools

Open your Terminal application (found in Applications/Utilities) and run the following command. This will prompt you to install the necessary tools if they aren't already present.

2. Run the Homebrew Installation Script

Once the Xcode Command Line Tools are installed, paste the following command into your terminal and press Enter. You might be asked for your administrator password during this process. The script will download and install Homebrew, and crucially, it will attempt to add Homebrew to your shell's PATH.

3. Verify Homebrew Installation

After the installation script completes, it's good practice to verify that Homebrew is correctly installed and accessible. Run the following command:

xcode-select --install

Command to install Xcode Command Line Tools.

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

Official Homebrew installation command.

brew help

Verify Homebrew installation by checking its help message.

💡

If you're on an Apple Silicon Mac (M1, M2, M3), Homebrew will typically install to /opt/homebrew. On Intel Macs, it installs to /usr/local. The installation script usually handles adding the correct path to your shell configuration file (e.g., ~/.zprofile or ~/.zshrc).

Manually Fixing PATH Issues (If 'brew help' Fails)

If brew help still results in command not found after installation, it means Homebrew's path wasn't correctly added to your shell's configuration. You'll need to manually add it. For Zsh, this involves editing your ~/.zprofile or ~/.zshrc file.

1. Determine Homebrew's Installation Path

First, find out where Homebrew was actually installed. You can often guess based on your Mac's architecture, but this command will confirm it:

2. Edit Your Shell Configuration File

Open your ~/.zprofile file (or ~/.zshrc if you prefer, though zprofile is recommended for login shells) using a text editor like nano or vim. If the file doesn't exist, it will be created.

3. Add Homebrew to PATH

Add the following lines to the end of the file. Replace /opt/homebrew/bin with the path you found in the previous step if it's different (e.g., /usr/local/bin for Intel Macs).

4. Save and Exit

If using nano, press Ctrl+X, then Y to confirm saving, and Enter to confirm the filename.

5. Source the Configuration File

Apply the changes to your current terminal session without restarting it. Alternatively, you can close and reopen your terminal.

6. Verify Again

Now, try running brew help again. It should work!

find / -name brew -type f 2>/dev/null

Command to locate the 'brew' executable.

nano ~/.zprofile

Opening the .zprofile file with nano.

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

Recommended line to add to .zprofile for Homebrew path configuration.

ℹ️

The eval "$(/opt/homebrew/bin/brew shellenv)" command is the official and most robust way to set Homebrew's environment variables, as it dynamically determines the correct paths. Avoid hardcoding paths if possible.

source ~/.zprofile

Sourcing the .zprofile file to apply changes.