Introduction
# 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 1. Search: `brew search python` 2. Get info: `brew info [email protected]` 3. Install: `brew install [email protected]`
### 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