Homebrew Package Manager

Complete Homebrew command reference and usage guide for installing, managing, and troubleshooting macOS packages.

When to Use

• Installing packages or applications (

  brew install X

  )
• Searching for available packages (

  brew search X

  )
• Updating and upgrading existing packages
• Checking package information and dependencies
• Troubleshooting installation issues
• Managing installed packages

Command Reference

Package Search & Information

brew search TEXT|/REGEX/

Usage: Find packages by name or regex pattern When to use: When user asks to find or search for a package Examples:

brew search python
brew search /^node/

brew info [FORMULA|CASK...]

Usage: Display detailed information about one or more packages When to use: Before installing to see dependencies, options, and details Examples:

brew info python
brew info chrome google-chrome

Installation & Upgrades

brew install FORMULA|CASK...

Usage: Install one or more packages or applications When to use: When user says "install X" or "use brew to install X" Notes:

• FORMULA = command-line tools (installed to /usr/local/bin)
• CASK = GUI applications (installed to /Applications)
• Can install multiple at once:

  brew install git python nodejs

  Examples:

brew install python
brew install google-chrome  # installs as cask
brew install git python nodejs

brew update

Usage: Fetch the newest version of Homebrew and all formulae When to use: When brew seems outdated or before major operations Notes: Doesn't upgrade packages, just updates the package list Examples:

brew update

brew upgrade [FORMULA|CASK...]

Usage: Upgrade installed packages or specific packages When to use: When user wants to update to newer versions Notes:

• Without args: upgrades all outdated packages
• With args: upgrades only specified packages Examples:

brew upgrade              # upgrade all outdated packages
brew upgrade python       # upgrade just python
brew upgrade python git   # upgrade multiple

Package Management

brew uninstall FORMULA|CASK...

Usage: Remove installed packages When to use: When user wants to remove/delete a package Notes: Can uninstall multiple at once Examples:

brew uninstall python
brew uninstall google-chrome

brew list [FORMULA|CASK...]

Usage: List installed packages or files from specific packages When to use: When user wants to see what's installed or what files a package contains Examples:

brew list                 # show all installed packages
brew list python          # show files installed by python

Configuration & Troubleshooting

brew config

Usage: Display Homebrew configuration and environment info When to use: Debugging installation issues or checking system setup Shows:

• Installation path
• Xcode location
• Git version
• CPU architecture Examples:

brew config

brew doctor

Usage: Check for potential problems with Homebrew installation When to use: When experiencing installation issues or errors Returns: Warnings and suggestions for fixing issues Examples:

brew doctor

brew install --verbose --debug FORMULA|CASK

Usage: Install with verbose output and debug information When to use: When standard install fails and you need detailed error messages Examples:

brew install --verbose --debug python

Advanced Usage

brew create URL [--no-fetch]

Usage: Create a new formula from source code When to use: Creating custom packages (advanced users) Options:

• --no-fetch

  = don't download source immediately Examples:

brew create https://example.com/package.tar.gz

brew edit [FORMULA|CASK...]

Usage: Edit formula or cask definition When to use: Customizing package installation (advanced users) Examples:

brew edit python

brew commands

Usage: Show all available brew commands When to use: Learning about additional brew features Examples:

brew commands

brew help [COMMAND]

Usage: Get help for specific command When to use: Need detailed help for a specific command Examples:

brew help install
brew help upgrade

Quick Reference

brew search TEXT

brew info FORMULA

brew install FORMULA

brew install CASK

brew update

brew upgrade

brew upgrade FORMULA

brew uninstall FORMULA

brew list

brew config

brew doctor

Common Workflows

Installing a New Package

1. Search:

   brew search python

2. Get info:

   brew info python@3.11

3. Install:

   brew install python@3.11

Troubleshooting Installation

1. Check config:

   brew config

2. Run doctor:

   brew doctor

3. Retry with debug:

   brew install --verbose --debug FORMULA

Maintaining Homebrew

1. Update:

   brew update

2. Check what's outdated:

   brew upgrade

   (shows what would upgrade)
3. Upgrade all:

   brew upgrade

Key Concepts

FORMULA: Command-line tools and libraries (e.g., python, git, node) CASK: GUI applications (e.g., google-chrome, vscode, slack) TAP: Third-party formula repositories (e.g.,

brew tap homebrew/cask-versions

Notes

• All brew commands require Homebrew to be installed
• Xcode Command Line Tools are required for building from source
• Some packages may prompt for sudo password
• Different packages have different installation times
• Package names are case-insensitive but shown lowercase by convention

Resources

• Official docs: https://docs.brew.sh
• Formula documentation: https://github.com/Homebrew/homebrew-core
• Cask documentation: https://github.com/Homebrew/homebrew-cask