Homebrew Cheatsheet - macOS Package Manager Reference

A fresh Mac loses hours to $PATH and dependency mess unless you install through Homebrew. This reference covers installing/updating/removing formulas, Cask GUI apps, brew services for background daemons, mirror switches for mainland use and troubleshooting broken bottles. Unlike a package list, it tells you which flag installs from HEAD vs a bottle, and how to diagnose a brew doctor complaint. After reading you can bootstrap and repair a Mac toolchain mostly from the terminal.

Dev Tools·38 commands·Last updated 2026-07-21

Typical Use Case

For macOS and Linux engineers whose workstation toolchain is managed by Homebrew. The recurring questions are always the same: why is this not updating, why did update break something, why is my install twice the size it should be, and why is a bottle refusing to download. This sheet covers the formula/cask split, update versus upgrade, services, taps, mirror switches, Brewfile-based reproducibility, and brew doctor as the first stop when the environment misbehaves.

Basics 12

brew install wget

Install a CLI tool

brew uninstall wget

Uninstall

brew update

Update Homebrew itself

brew upgrade

Upgrade all installed packages

brew upgrade wget

Upgrade a specific package

brew list

List installed

brew info wget

View package info

brew search nginx

Search for a package

brew cleanup

Clean up old-version caches

brew outdated

See upgradable packages

brew reinstall wget

Reinstall (fix corruption)

brew autoremove

Auto-remove unneeded dependencies

Cask GUI Apps 5

brew install --cask visual-studio-code

Install a GUI app

brew uninstall --cask visual-studio-code

Uninstall a GUI app

brew list --cask

List installed GUI apps

brew search --cask chrome

Search for GUI apps

brew upgrade --cask

Upgrade all GUI apps

Services 5

brew services list

List all service statuses

brew services start mysql

Start and enable on boot

brew services stop mysql

Stop a service

brew services restart mysql

Restart a service

brew services run mysql

Run without enabling on boot

Taps & Mirrors 5

brew tap homebrew/cask-fonts

Add a third-party tap

brew untap homebrew/cask-fonts

Remove a third-party tap

brew tap

List added taps

export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"

Switch API mirror temporarily

export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

Switch Bottle mirror temporarily

Troubleshooting 7

brew doctor

Check environment issues

brew config

View Homebrew config

brew deps wget

View dependencies

brew pin wget

Pin a version (no upgrade)

brew unpin wget

Unpin a version

brew leaves

See top-level manually installed packages

brew uses --installed wget

See which installed packages depend on it

Bundle Management 4

brew bundle dump

Dump installed list to Brewfile

brew bundle install

Install from Brewfile in batch

brew bundle cleanup

Clean up packages not in Brewfile

brew bundle check

Check if Brewfile dependencies are met

Parameter matrix

Parameter	Effect	Example
`brew update`	Refresh Homebrew itself and the formula/cask index; no installed package is upgraded	`brew update`
`brew upgrade`	Upgrade installed formulae; GUI apps need the separate --cask path	`brew upgrade --cask`
`brew cleanup`	Drop old versions and download caches - the fastest way to reclaim disk	`brew cleanup`
`brew pin`	Freeze a formula against upgrades, useful when a newer version breaks	`brew pin wget`
`brew bundle`	Dump, install or verify the toolchain from a Brewfile for reproducible setups	`brew bundle dump`

Common pitfalls

Symptombrew update ran but git and node versions did not move at all.

Causeupdate only refreshes Homebrew and its index; upgrading happens in upgrade.

FixCheck with brew outdated, then run brew upgrade; for GUI apps use brew upgrade --cask.

Symptombrew install hits a dependency conflict and only succeeds with --force-overwrite.

CauseLeftover old versions contradict the new dependency requirement - the upgrade chain was never completed.

FixRun brew update && brew upgrade, then brew cleanup to drop stale versions; fall back to brew reinstall for that package.

SymptomBottle downloads crawl or fail repeatedly, while building from source fails on missing deps.

CauseThe default distribution host is often unreachable on some networks.

FixExport HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles" and retry.

SymptomThe disk is nearly full after months of installs, with several old versions stacked up.

CauseHomebrew keeps old versions and download caches around after every upgrade.

FixRun brew cleanup periodically, then brew autoremove to drop dependencies nothing needs.

SymptomTwo Homebrew installs coexist (arm64 and x86_64), commands shadow each other and brew doctor complains.

CauseBoth /usr/local and /opt/homebrew exist on an Apple Silicon machine, or an Intel migration left one behind.

FixCheck with brew config, keep one prefix, and put it first in PATH.

Troubleshooting

1Start with the built-in health check
brew doctor
It points at concrete issues: duplicate installs, PATH ordering, missing Command Line Tools.
2Assess the blast radius before upgrading
brew outdated && brew info wget
outdated lists what can move; info gives version, dependencies and caveats, where breaking changes are recorded.
3Confirm installation and reverse dependencies
brew list && brew deps wget && brew uses --installed wget
deps answers "what does it need"; uses --installed answers "who needs it" - opposite directions.
4Freeze the toolchain and reproduce it elsewhere
brew bundle dump && brew bundle install
dump writes a Brewfile, install rebuilds from it on a new machine; brew bundle check verifies completeness.

Command Examples

Check the name and dependencies before installing

brew search nginx
brew info wget
brew list

The caveats printed by brew info often spell out extra PATH or configuration steps, so read them before installing.

Update, assess, then upgrade

brew update
brew outdated
brew upgrade
brew upgrade wget

update refreshes Homebrew itself only; outdated lists what could move, and you upgrade after reviewing that list.

Formulae and casks are managed separately

brew install --cask visual-studio-code
brew list --cask
brew search --cask chrome
brew upgrade --cask
brew uninstall --cask visual-studio-code

GUI applications live in the cask system, so plain brew upgrade leaves them alone; the --cask flag is required.

Service control and dependency health checks

brew services list
brew services start mysql
brew services run mysql
brew services restart mysql
brew services stop mysql
brew doctor
brew config

start registers the service for boot, run only affects the current session; the plist files live in ~/Library/LaunchAgents/.

Common Pitfalls

brew update upgrades nothing; upgrading is brew upgrade and brew upgrade --cask, two separate paths.
Do not reach for --force-overwrite on a dependency conflict: read brew info first, because forcing installs leaves the environment unreproducible.
brew cleanup really deletes old versions and download caches, and the only way back is to reinstall; check brew leaves before running it.
Two Homebrew prefixes on one machine (arm64 and x86_64) shadow each other, so run brew doctor first whenever commands behave strangely.
When bottle downloads crawl or fail, switch the HOMEBREW_API_DOMAIN and HOMEBREW_BOTTLE_DOMAIN mirrors instead of falling back to building from source.

Tips

On slow networks, switch mirrors before install, or bottle downloads often time out.
Services managed by brew services live in ~/Library/LaunchAgents/; check there if something breaks.
brew cleanup deletes old versions and download caches; run it when disk is tight.

FAQ

brew update finished but git and node are still old. Why?

Because update only refreshes Homebrew itself and its package index; it never touches installed packages. To actually upgrade, run brew upgrade, or brew upgrade wget for a single one. Check brew outdated first to see the upgrade list and judge whether anything is breaking. Another common case is upgrading only formulae: GUI applications live in the cask system and only move under brew upgrade --cask, and brew list and brew list --cask report two separate inventories.

How do I stop guessing the exact package name at install time?

Three steps. Run brew search nginx to get the real name, then brew info wget to check version, dependencies and caveats before committing, and brew list to see whether it is already installed and at which version. The cask equivalents are brew search --cask chrome and brew list --cask. If an install fails, resist reaching for --force-overwrite: brew info shows why the dependency conflict actually exists.

The disk is full of old versions and caches. What do I run first?

Start with brew cleanup, which removes old versions and downloaded caches and frees space the fastest. Follow up with brew autoremove for dependencies nothing needs any more, and brew bundle cleanup for packages absent from your Brewfile. Before running anything, check brew leaves to confirm which packages were installed at top level and that you are not about to delete something you rely on. Stale cask versions in the Caskroom go away through the same cleanup.

A tool crashes as soon as it upgrades. How do I freeze the version?

Run brew pin wget: brew upgrade skips pinned packages. Release it later with brew unpin wget once upstream has fixed whatever broke. To find out which installed package depends on it, run brew uses --installed wget, and to inspect its own requirements use brew deps wget. For a general health check of the environment, rely on brew doctor and brew config.

How do I reproduce this toolchain on a fresh machine?

Four commands close the loop: brew bundle dump exports the current installation into a Brewfile, you commit that file, brew bundle install applies it on the new machine, and brew bundle check verifies the requirements are satisfied while brew bundle cleanup removes anything not listed. Casks are recorded in the same Brewfile, so bundle manages both halves.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

Homebrew Docs

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.