Installing and Using Homebrew on macOS: A Complete Guide

Introduction / Why You Need This

Homebrew (often called simply brew) is an indispensable tool for any macOS user who works in the terminal. It solves the main problem of installing Unix-compatible software: it automatically builds and installs all necessary dependencies.

What you'll gain by mastering Homebrew:

• Speed: Installing complex tools (like ffmpeg, node, wget) takes seconds instead of hours of manual setup.
• Manageability: All programs installed via brew are in one system. They can be easily updated with a single command or completely removed.
• Isolation: Packages are installed in separate directories (/usr/local/Cellar or /opt/homebrew/Cellar), without cluttering system folders.
• Compatibility: Many modern development tools (Docker, Kubernetes CLI, programming languages) recommend installation specifically through Homebrew.

This guide will take you from your first command to confident usage.

Prerequisites / Preparation

Before you begin, ensure:

1. You have an administrator account on your Mac.
2. Xcode Command Line Tools are installed. Homebrew can offer to install them automatically, but it's better to check beforehand. Run in the terminal:

   xcode-select --install
   

   If the command returns an error or a message that the tools are already installed, you're fine.
3. You are familiar with the basics of working in Terminal (Terminal.app or iTerm2).
4. You have a stable internet connection.

Step 1: Installing Homebrew

The official and only recommended way to install is to run the script from the official website.

1. Open Terminal (via Spotlight Cmd+Space → "Terminal" or from /Applications/Utilities/).
2. Paste and execute the following command:

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

   What the command does: curl downloads the installation script, -fsSL are flags for silent and secure downloading, bash -c executes the received script.
3. The script will output informational messages and ask if you want to continue. Press Enter to confirm.
4. You will be prompted to enter your administrator password. Password input in the terminal is not displayed (characters do not appear) — this is normal. Just type your password and press Enter.
5. Installation will take between 5 and 15 minutes depending on your internet speed. At the end, the script will output success messages and may suggest commands to add Homebrew to your PATH.

⚠️ Important: If you are using an Apple Silicon Mac (M1/M2/M3), Homebrew will install by default to /opt/homebrew. For Intel Macs — to /usr/local. The script automatically detects the architecture.

Step 2: Environment Setup (PATH)

After installation, you may need to configure the PATH environment variable so your system "sees" the brew command and programs installed with it.

1. The installation script usually suggests the necessary commands automatically. If you skipped this step, execute the following depending on your shell:
   • For Zsh (the default shell in macOS starting with Catalina):

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

   • For Bash (if you use it):

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

2. Restart Terminal or run source ~/.zprofile / source ~/.bash_profile.

Step 3: Verifying the Installation

Run two key commands for diagnostics:

brew --version

The output should show the Homebrew version (e.g., Homebrew 4.2.0).

brew doctor

This command checks your system for potential Homebrew configuration issues.

• Ideal result: Your system is ready to brew.
• If there are warnings (e.g., about broken symlinks or outdated Xcode versions), read them carefully and follow the provided instructions to fix them.

Step 4: Your First Homebrew Commands

Now Homebrew is ready. Master the basic cycle: Search → Install → Use → Update/Uninstall.

4.1 Searching for Packages

To find a program, for example, a video downloading utility yt-dlp:

brew search yt-dlp

Or for a broader search:

brew search wget

4.2 Getting Package Information

Before installing, it's useful to learn what's in a package, its dependencies, and its license:

brew info wget

The output will show: the current version, description, list of dependencies, size, and the install command.

4.3 Installing a Package

Install wget — a powerful file download utility:

brew install wget

Homebrew will automatically download the source code (or binary), verify integrity, build (if needed), and install the package with all its dependencies.

4.4 Running the Installed Software

After installation, the program's commands are available immediately in the terminal. Check wget:

wget --version

4.5 Updating Formulae (Core Packages)

Regularly update the list of available packages and the packages themselves:

brew update        # Updates Homebrew's internal repository (formulae)
brew upgrade       # Upgrades all installed packages to the latest versions

4.6 Uninstalling a Package

If you no longer need a program:

brew uninstall wget

This removes the package files but preserves configuration files in your home directory (if they were created).

4.7 Cleanup

Over time, old package versions and build temporary files accumulate in the cache. Free up space:

brew cleanup        # Deletes old versions of installed packages
brew cleanup -s     # Also deletes the download cache (downloaded .tar.gz archives)

Step 5: Working with Casks (Installing GUI Applications)

Homebrew isn't limited to console tools. Homebrew Cask is an extension for managing graphical applications (.dmg, .pkg).

• Search for GUI apps: brew search --cask firefox
• Install: brew install --cask firefox (or simply brew install firefox if the name doesn't conflict with a formula).
• Uninstall: brew uninstall --cask firefox
• List installed Cask apps: brew list --cask

This is a convenient way to install programs like google-chrome, visual-studio-code, discord, spotify without visiting websites.

Verification

You have successfully mastered Homebrew if you can:

1. Install a popular console tool (e.g., tree for displaying folder structure) and see it in the list: brew list.
2. Update that tool to the latest version: brew upgrade tree.
3. Find and install a simple GUI app via --cask (e.g., brave-browser).
4. Run brew doctor and get the message Your system is ready to brew.

Potential Issues

Issue: "Permission denied" or "Operation not permitted" during installation

Cause: The installation script did not get write permissions to the target directory (/usr/local or /opt/homebrew). Solution: Ensure you are logged in with an administrator account. Restart the installation. If the problem persists, check the directory permissions:

sudo chown -R $(whoami) /opt/homebrew  # For Apple Silicon
# or
sudo chown -R $(whoami) /usr/local    # For Intel

Then repeat the installation.

Issue: brew command not found after installation

Cause: The path to Homebrew (/opt/homebrew/bin or /usr/local/bin) is not added to the PATH variable of your current shell. Solution: Run the commands from Step 2 again. Make sure you are editing the correct profile file (~/.zprofile for Zsh, ~/.bash_profile for Bash). After adding the line, restart the terminal.

Issue: brew update doesn't work or is very slow

Cause: Problems with DNS or access to GitHub (where the formulae repositories are hosted). Cache reset may also help. Solution:

1. Check access: ping -c 3 github.com.
2. If necessary, configure DNS (e.g., to 8.8.8.8).
3. Force reset the cache and update:

   cd "$(brew --repo)/Library/Taps/homebrew/homebrew-core"
   git fetch --unshallow  # If the repository was not full
   git reset --hard origin/master
   brew update
   

Issue: Name conflict (formula and cask with the same name)

Cause: Some names exist both as a console package (formula) and a GUI application (cask). Solution: Explicitly specify the type:

brew install <formula_name>       # For the console utility
brew install --cask <cask_name>   # For the application

Or use brew search <name> to see both options.

Issue: Build error (for formulae built from source)

Cause: Missing dependencies (e.g., Xcode Command Line Tools) or library version conflicts. Solution: First run brew doctor and follow its recommendations. Often, reinstalling the Command Line Tools helps:

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

Then try installing the problematic package again. As a last resort, look for pre-built binary versions (bottles) or use --build-from-source with the --verbose flag for a detailed error log.