Set Up a Productive Dev Environment with Homebrew

What you'll build / learn

By the end of this tutorial you'll have Homebrew installed, you'll know how to install command-line tools and GUI apps, and you'll have a single Brewfile that can rebuild your entire developer setup on a new machine with one command.

Prerequisites

• macOS (Homebrew also runs on Linux, but this tutorial focuses on macOS). macOS 13 (Ventura) or newer is recommended.
• Administrator access to your Mac (you'll be asked for your password during install).
• Command Line Tools for Xcode — the Homebrew installer will offer to install these automatically, so you don't need to do it ahead of time.
• A Terminal. Use the built-in Terminal.app (in /Applications/Utilities) or iTerm2.

Apple Silicon vs Intel note: On Apple Silicon Macs (M1/M2/M3/M4), Homebrew installs to /opt/homebrew. On older Intel Macs it installs to /usr/local. This affects one step below where you add Homebrew to your shell — pay attention to which one applies to you.

Step 1: Install Homebrew

Open Terminal and run the official install command from brew.sh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script explains exactly what it will do and pauses for you to confirm with Return. It may prompt for your macOS password (typing shows nothing — that's normal) and offer to install the Xcode Command Line Tools. Let it.

Step 2: Add Homebrew to your PATH

On Apple Silicon, the installer does not automatically add brew to your shell. The end of the install output tells you the exact commands. For the default zsh shell on a modern Mac, run:

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

On an Intel Mac, brew lives in /usr/local/bin, which is already on your PATH, so you can usually skip this. If brew isn't found, use the same commands but replace /opt/homebrew with /usr/local.

Close and reopen Terminal so changes take effect.

Step 3: Verify and run a checkup

brew --version
brew doctor

brew doctor checks your setup and prints Your system is ready to brew. when everything is healthy. Warnings are common and usually safe to ignore.

Step 4: Install formulae (command-line tools)

A formula is a package for a CLI tool or library. Install a few essentials:

brew install git wget jq

Useful day-to-day commands:

brew search node      # find packages matching "node"
brew info git         # show version, dependencies, caveats
brew list             # list everything you've installed
brew uninstall wget   # remove a package

Step 5: Install casks (GUI apps)

A cask installs a full macOS application. The syntax is brew install --cask:

brew install --cask visual-studio-code
brew install --cask google-chrome

Homebrew downloads the app and places it in /Applications, just like dragging it from a .dmg — but now it's tracked and updatable from the command line.

Step 6: Make it reproducible with a Brewfile

This is the payoff. A Brewfile is a plain-text list of everything you want installed. Generate one from your current setup:

brew bundle dump --describe --file="$HOME/Brewfile"

We use "$HOME/Brewfile" instead of ~/Brewfile here on purpose: in zsh and bash, a ~ that appears after the = in a word like --file=~/Brewfile is not tilde-expanded by the shell, so quoting $HOME guarantees the file lands in your home directory. (If you prefer the tilde, write it as its own word with a space — --file ~/Brewfile — so the shell expands it.)

--describe adds helpful comments. Open ~/Brewfile and you'll see something like:

brew "git"
brew "jq"
brew "wget"
cask "google-chrome"
cask "visual-studio-code"

brew bundle is built into Homebrew, so a fresh dump won't include a tap "homebrew/bundle" line. You'll only see tap lines for taps you actually added yourself (for example tap "hashicorp/tap").

Commit this file to a dotfiles Git repo. On a brand-new Mac, after installing Homebrew, you rebuild everything with:

brew bundle install --file="$HOME/Brewfile"

To check whether your machine matches the Brewfile:

brew bundle check --file="$HOME/Brewfile"

Tip: brew bundle dump refuses to overwrite an existing Brewfile. Add --force to regenerate it after you've installed new things.

Step 7: Keep everything updated

Run these regularly:

brew update     # refresh Homebrew's package catalog
brew outdated   # show which installed packages have newer versions
brew upgrade    # upgrade everything that's outdated

Over time, old downloads and previous versions accumulate. Clean them up:

brew cleanup

Verify it works

Run a quick end-to-end check:

git --version
jq --version
brew list --cask

You should see version numbers for git and jq, and visual-studio-code and google-chrome listed among your casks. If you open Finder → Applications, the GUI apps you installed will be there. Your ~/Brewfile should exist and list everything you installed.

Troubleshooting

brew: command not found after install You skipped or mis-ran Step 2. Re-run the eval "$(/opt/homebrew/bin/brew shellenv)" line (use /usr/local on Intel), then restart Terminal.

Error: Cannot install ... because conflicting formulae are installed An older or conflicting package is blocking the install. Read the message — it names the conflict. Usually brew uninstall <conflicting-package> followed by retrying resolves it.

Cask install fails with a permissions or quarantine error Make sure no copy of the app is already open or already in /Applications. Remove the old copy, then re-run brew install --cask <app>. If macOS Gatekeeper blocks the app on first launch, open System Settings → Privacy & Security and click Open Anyway.

brew doctor warns about an unbrewed file in /usr/local These warnings are informational. If you're not having an actual installation problem, you can safely ignore them.

Next steps

• Build a dotfiles repo on GitHub that includes your Brewfile plus shell config, so a new machine is one brew bundle install away from ready.
• Install developer fonts straight from the default cask repository — no special tap needed anymore. The old homebrew/cask-fonts tap was archived in 2024 and its font casks were merged into homebrew/cask, so just run brew install --cask font-fira-code (or any other font-* cask) directly.
• Explore vendor taps such as hashicorp/tap when you need packages that live outside the core repositories.
• Read the official docs at docs.brew.sh and run brew help to discover more commands.
• Automate upgrades: schedule brew update && brew upgrade && brew cleanup as part of your weekly routine.