Installing Homebrew from scratch, then using it to install, update, and remove tools and apps. Everything here is typed in Terminal on your Mac.
READ-ONLY only looks; safeCHANGES THINGS installs, updates, or removes something$ = you type this
Getting started
#1What Homebrew is
Homebrew is an app store for your Mac that you use from Terminal. One command finds, downloads, installs, and later updates a program, along with anything it needs to run.
Two kinds of things it installs
Formulas (formulae)
Command-line tools you use in Terminal, like wget, tree, or mysql-client.
Casks
Regular Mac apps that show up in your Applications folder, like Firefox or Multipass. Installed the same way.
Why use it instead of downloading from websites
One command to update everything, instead of visiting each website.
A list of what you've installed, so you can set up a new Mac the same way (section 6).
Clean removal: uninstalling takes the program's files with it.
Where it keeps things
Everything Homebrew installs lives in one folder, /opt/homebrew, separate from macOS's own files. That's why it can't damage the system itself.
You only do this once per Mac. Takes about 5 to 10 minutes. You'll need your Mac login password, and your account must be an administrator (System Settings › Users & Groups).
This downloads Homebrew's official install script and runs it. Always copy it from here or from brew.sh, never from a random website.
What it asks, in order
Password:
Your Mac login password. Nothing shows as you type; that's normal. Press Return.
Press RETURN/ENTER to continue
It lists what it's about to do. Press Return.
The Xcode Command Line Tools will be installed
Apple's developer basics, which Homebrew needs. May take several minutes. If a separate window pops up asking to install them, click Install.
Installation successful!
Done, but don't close Terminal yet. Read the Next steps below it.
Step 3: run the "Next steps" lines the installer prints
At the end, under ==> Next steps:, the installer prints two or three commands. They tell Terminal where to find brew. Use those exact lines, copied from your own Terminal window, not from this page. Their wording changes between Homebrew versions, and the installer prints the right ones for your Mac.
Select the first line under Next steps in Terminal and copy it (Cmd+C).
Paste it (Cmd+V) and press Return.
Repeat for each remaining line. No output after each = done.
⚠ Example only: so you recognize them. Don't copy these; use what your installer printed.
What they do: the first lines add a setting to ~/.zprofile, a file Terminal reads every time it opens; the last one applies it to the window you have open now.
⚠ CAREFULThose lines use >>, which adds to the file. A single > would wipe~/.zprofile and replace it. That's why you copy and paste the installer's lines rather than retyping them.
Closed Terminal before running them? (read-only check)
grep shellenv ~/.zprofile
A line containing brew shellenv = already set up. Open a new Terminal window and go to step 4.
No output = not set up yet. Run the installer command from step 2 again; it notices Homebrew is already installed, finishes quickly, and prints the Next steps lines again.
Step 4: check it worked (read-only)
brew doctorYour system is ready to brew.
If it lists warnings instead, see Troubleshooting. Most are harmless.
INTEL MACSHomebrew is built for Apple Silicon Macs (M1 and newer), where it lives in /opt/homebrew. Support for older Intel Macs (which used /usr/local) is being phased out; check brew.sh before installing on one.
Each line: name, the version you have, then the newer one. No output = everything is current.
3. Upgrade
brew upgrade
Upgrades everything on that list. To upgrade just one: brew upgrade tree.
4. Clean up old versions
brew cleanup
Deletes old versions and downloads Homebrew kept after upgrading. Ends with how much space it freed. Homebrew also does this on its own now and then.
GOOD TO KNOWHomebrew refreshes its catalog by itself before most installs, which is why brew install sometimes pauses at Auto-updating Homebrew first. That's normal.
⚠ BEFORE A BIG UPGRADEIf you rely on a tool for work (for example a database client that has to match your server's version), check what's changing with brew outdated first, and upgrade that one separately when you have time to test it. To keep one from upgrading: brew pin NAME; brew unpin NAME releases it.
Casks are ordinary Mac apps (they land in your Applications folder), installed and updated with the same brew commands. Add --cask to make clear you mean the app.
Task
Command
Safe?
Search for an app
brew search --cask firefox
READ-ONLY
Install an app
brew install --cask firefox
CHANGES THINGS
List apps installed this way
brew list --cask
READ-ONLY
Uninstall an app
brew uninstall --cask firefox
CHANGES THINGS
What you might see
Password:
Some apps need your Mac password to install. Nothing shows as you type.
It seems there is already an App at '/Applications/Firefox.app'
You installed it yourself before. Either leave it alone, or let Homebrew take it over: brew install --cask--adopt firefox.
Firefox.app was successfully installed!
Done. Open it from Applications or Spotlight as usual.
Updating apps
Plain brew upgrade updates apps too, except apps that update themselves (like browsers). Homebrew leaves those to their own updater. To include them anyway:
brew upgrade --cask--greedy
⚠ CAREFULbrew uninstall --cask--zap APP removes the app and its settings and saved data (preferences, caches, sometimes more). Plain uninstall leaves those in place. Only use --zap when you really want every trace gone.
GOOD TO KNOWMultipass (the Ubuntu virtual machine tool) is available as a cask too. Its install and update steps are on the Multipass sheet.
An extra catalog Homebrew uses, if you added any. Leave these lines in.
It's plain text: you can delete lines for things you don't want on the next Mac, or add a # note above a line.
Step 3: keep a copy somewhere safe
Copy ~/Brewfile to cloud storage or a password manager note, so it survives if this Mac doesn't. Run step 1 again (with --force) whenever you've added or removed something.
On a new Mac: install everything on the list
Install Homebrew first (section 2), put the Brewfile in your home folder, then:
brew bundle --file=~/Brewfile
Goes down the list installing each item; anything already there is skipped. Ends with Homebrew Bundle complete! Can take a while for a long list.
Is everything on the list installed? (read-only)
brew bundle check --file=~/Brewfile
The Brewfile's dependencies are satisfied. = yes. Otherwise it says something is missing.
⚠ CAREFULbrew bundle cleanup --forceuninstalls everything that isn't in your Brewfile. Without --force it only lists them, which is safe. Never add --force until you've read that list.
Start with brew doctor. It checks your setup and explains anything odd it finds.
brew doctor
Your system is ready to brew. = all good.
Lines starting Warning: come with an explanation and often a suggested command. Many warnings are harmless if things work; the text itself says so for most. Fix them only if you're having a problem.
Common messages
zsh: command not found: brew
Terminal doesn't know where Homebrew is. Open a new Terminal window first. If it still fails, the "Next steps" lines were never run; see the check in section 2.
Running Homebrew as root is extremely dangerous
You typed sudo brew …. Never use sudo with brew. Run it without; Homebrew asks for your password itself when it needs it.
xcrun: error: invalid active developer path
Usually right after a macOS upgrade, which removes Apple's command line tools. Reinstall them with xcode-select--install and click Install.
Another active Homebrew update process is already in progress
Another brew is running, maybe in a different Terminal window. Wait for it to finish, then try again.
No available formula with the name "…"
Typo, or it's an app: try brew search NAME, then brew install --cask NAME.
It seems there is already an App at …
The app was installed outside Homebrew. See section 5.
Download fails or times out
Run brew update, then try the install again. Sometimes the download site is just busy.
Asking for help: show your setup (read-only)
brew config
Prints your Homebrew version, macOS version, and Mac type. Paste it when asking someone for help; it answers their first questions.
Removing Homebrew completely (rarely needed)
Homebrew provides an official uninstall script; find it on brew.sh under its documentation. It removes Homebrew and everything installed with it. Save your Brewfile first (section 6) so you can put it all back.