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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
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:
bash
brew edit python
brew commands
Usage: Show all available brew commands
When to use: Learning about additional brew features
Examples:
bash
brew commands
brew help [COMMAND]
Usage: Get help for specific command
When to use: Need detailed help for a specific command
Examples:
bash
brew help install
brew help upgrade
Quick Reference
| Task | Command |
|---|---|
| Search for package | brew search TEXT |
| Get package info | brew info FORMULA |
| Install package | brew install FORMULA |
| Install app | brew install CASK |
| Update package list | brew update |
| Upgrade all packages | brew upgrade |
| Upgrade specific package | brew upgrade FORMULA |
| Remove package | brew uninstall FORMULA |
| List installed | brew list |
| Check config | brew config |
| Troubleshoot | brew doctor |
Common Workflows
Installing a New Package
- Search:
brew search python - Get info:
brew info [email protected] - Install:
brew install [email protected]
Troubleshooting Installation
- Check config:
brew config - Run doctor:
brew doctor - Retry with debug:
brew install --verbose --debug FORMULA
Maintaining Homebrew
- Update:
brew update - Check what's outdated:
brew upgrade(shows what would upgrade) - 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