How to Use Homebrew on Mac (2026)

To use Homebrew, run brew <command> in Terminal: brew install to add software, brew upgrade to update everything, brew uninstall to remove it, and brew doctor to fix problems.

Before you run anything

Three assumptions this guide makes. If any of them is missing, fix that first; every failure below traces back to one of these:

Homebrew itself, installed once

If brew is not on your machine yet, install it first and confirm Terminal finds it with which brew. On Apple Silicon the path is /opt/homebrew/bin/brew; on Intel it is /usr/local/bin/brew. Our new-Mac setup guide walks through the installer and the PATH fix when the shell cannot find it.

The Xcode command line tools

Formulae that compile from source need a compiler. The Homebrew installer normally pulls these in; if builds fail with missing headers, run xcode-select --install and let it finish before retrying. Pure cask installs (GUI apps) rarely need this, but having it avoids a whole class of errors.

An admin account you control

Installing software writes outside your home folder, so the account needs admin rights. Never work around this with sudo: Homebrew refuses to run as root for good reason, and forcing it breaks file ownership across the install.

Install & remove

brew install <tool>

Install a command-line tool (formula), e.g. brew install git. Homebrew resolves dependencies automatically, so one command often pulls in the libraries the tool needs.

brew install --cask <app>

Install a graphical app (cask), e.g. brew install --cask arc. The app lands in /Applications exactly as if you had downloaded the disk image by hand, minus the dragging.

brew uninstall <name>

Remove a formula. Add --cask for an app. Config files in your home folder usually survive, so reinstalling later picks up where you left off.

brew list

List everything you have installed. Run this before upgrades so you know the blast radius, and after a Brewfile restore to confirm nothing was skipped.

Find software

brew search <term>

Search for formulae and casks by name. Use this whenever a bundle line fails: the token you guessed is often one hyphen off from the real one.

brew info <name>

Show version, dependencies, and the homepage for a package. Read this before installing anything that pulls in five dependencies you did not ask for.

Keep things current

brew update

Refresh the catalog of available packages. Always run this before installing or upgrading; a stale catalog is the top cause of version-not-found errors.

brew upgrade

Upgrade everything you have installed to the latest version. Run it when you have time to verify afterward, not ten minutes before a deadline.

brew outdated

See which installed packages have updates available. Useful when you want a selective upgrade instead of moving the whole machine at once.

Maintenance & repair

brew doctor

Diagnose common problems with your Homebrew setup. Read each warning literally and fix one item at a time; most are PATH conflicts or leftover files.

brew cleanup

Delete old versions and free up disk space. Old versions accumulate fast on machines that upgrade weekly, so this is the easiest gigabytes you will ever reclaim.

brew bundle dump

Write a Brewfile of your current setup so you can reproduce it. Commit the file to Git and your next Mac is one command away.

Your first Homebrew session, step by step

Run these six steps in order on a quiet afternoon. By the end you will have installed two real apps, updated everything, and saved a Brewfile, which covers nearly all daily Homebrew use:

1
Refresh the catalog
Start every session by syncing your local copy of available packages. Skipping this is the most common reason an install fails with a version error: your machine is asking for a build the catalog no longer lists. It takes seconds and never changes what is installed, so there is no reason to skip it.
```
brew update
```
2
Install one app to learn the shape
GUI apps are casks, command-line tools are formulae, and the flag matters. Install a launcher like Raycast as a cask and watch where it lands (your /Applications folder, like a manual download). Grant the Accessibility permission it requests on first launch; launchers cannot do their job without it. From here on, every install follows the same pattern.
```
brew install --cask raycast
```
3
Install a second app without re-reading docs
Same command, different token. A terminal such as Ghostty installs the same way, and Homebrew skips anything already present, so repeating commands is harmless. Open it after installing and confirm your shell profile loads; a terminal that cannot find your PATH is a configuration issue, not an install failure. Chain two or three installs in one line while you learn; the pattern holds for every cask in our catalog.
```
brew install --cask ghostty
```
4
Check what you have
List everything installed and inspect anything unfamiliar before you upgrade it. brew info shows the version, dependencies, and homepage, which is worth reading the first time a package pulls in five things you did not ask for. Dependencies install automatically and uninstalling the parent does not always remove them; brew leaves shows what you asked for directly versus what came along for the ride.
```
brew list
brew info ghostty
```
5
Upgrade everything, then clean up
One upgrade pass updates all formulae and casks at once. Old versions pile up fast, so finish with cleanup to reclaim disk space. Run this pair weekly and your machine stays current without thought. If one upgrade misbehaves, outdated tells you exactly which packages moved, which narrows the suspect list fast.
```
brew upgrade
brew cleanup
```
6
Save your setup so it survives
Dump your current install into a Brewfile and keep that file somewhere safe. Next Mac, next reinstall, you replay one command instead of remembering fifty app names. This is the habit that turns Homebrew from a downloader into a reproducible setup. Commit the file whenever you add something you would miss; a Brewfile you never update is just a souvenir.
```
brew bundle dump --file=~/Brewfile --force
```

When a command fails

Six failures every Homebrew user meets eventually, with the fix that actually works for each. Read the error message first; it usually names the cause:

"zsh: command not found: brew" in a fresh shell

Homebrew installed but your shell never learned where. On Apple Silicon the binary is /opt/homebrew/bin/brew; evaluate the shellenv line once and append it to ~/.zprofile so future shells inherit it. Then quit Terminal completely and reopen it. A new tab is not always enough.

eval "$(/opt/homebrew/bin/brew shellenv)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

Never run brew with sudo

If a tutorial tells you sudo brew install, close that tutorial. Homebrew manages its own prefix ownership and running as root corrupts it, producing permission errors that persist after you stop. The fix for a genuine permission problem is to repair ownership of the prefix, not to escalate. When in doubt, brew doctor names the exact directory to look at.

brew doctor

Install fails with "no available formula or cask"

Three usual causes, in order: you forgot brew update and the catalog is stale; you used the wrong kind (a GUI app needs --cask, a tool must not have it); or the token is misspelled. Update first, check the kind second, then search for the right name. Cask tokens use lowercase hyphens, exactly as shown in our app pages.

brew update
brew search <name>

An upgrade breaks a tool you depend on

Do not panic-upgrade everything the morning of a deadline. Upgrade when you have time to verify, keep the previous behavior in mind, and remember cleanup deletes old versions you might have wanted to roll back to. For critical tools, upgrade that one formula alone and test it before running a blanket upgrade.

brew upgrade <formula>

A cask app will not open after install

macOS Gatekeeper flags freshly installed apps, especially on first launch. Right-click the app in Finder, choose Open, and confirm. This is the operating system doing its job, not a failed install, and it only happens once per app.

"Your Xcode is outdated" or missing compiler errors

Source builds need current command line tools. Run the standalone installer, wait for it to complete, and retry the build. If the error persists after that, the formula itself may be broken upstream; check its homepage or our app page before assuming your machine is at fault.

xcode-select --install

An upgrade moved a tool you needed pinned

Some workflows depend on an exact tool version. Pinning a formula excludes it from blanket upgrades while everything else moves forward. Use this sparingly: pinned tools miss security fixes, so revisit pins monthly and unpin once the blocker clears.

brew pin <formula>
brew unpin <formula>

A cask you use daily never shows updates

Apps that update themselves (browsers, editors with built-in updaters) are skipped by default upgrades. The greedy flag includes those self-updating casks in the pass. Expect some double updates where both Homebrew and the app updater fire; that overlap is harmless.

brew upgrade --cask --greedy

Frequently Asked Questions

What is the basic Homebrew workflow?

Run brew update to refresh the catalog, brew install <name> (add --cask for apps) to add software, brew upgrade to keep everything current, and brew uninstall <name> to remove it. brew doctor and brew cleanup keep the install healthy. That five-command loop covers nearly everything; the rest of this guide is about doing it in the right order and recovering when a step complains.

How do I update all my Homebrew apps at once?

Run brew update && brew upgrade. The first command refreshes the package list and the second upgrades every installed formula and cask to its latest version. Add the --cask --greedy flags when self-updating apps seem stuck on old versions.

How do I free up space used by Homebrew?

Run brew cleanup to remove outdated versions and cached downloads. Add --prune=all to also clear the entire download cache. On machines that upgrade weekly this routinely frees gigabytes, and it never touches the currently installed versions.

How do I see everything I have installed?

Run brew list to print every installed formula and cask, or brew leaves to see only the top-level packages you installed directly (not dependencies). Pair it with brew info <name> when you want the version and homepage of one package.

What is the difference between a formula and a cask?

A formula is a command-line tool that lives in Homebrew’s prefix and runs in Terminal; a cask is a graphical Mac app that lands in /Applications like a manual download. Install tools with brew install <name> and apps with brew install --cask <name>. Mixing them up is the most common beginner error, and the fix is just adding or removing the flag. When unsure, brew info names the kind before you commit.

Should I ever use sudo with brew?

No, never run brew with sudo. Homebrew owns its install prefix as your user, and escalating to root breaks that ownership and causes permission errors that linger. If an install complains about permissions, run brew doctor and repair the directory it names instead of forcing the command through. Any guide that tells you otherwise is outdated or wrong.