Homebrew Package Manager

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

| 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 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