Homebrew Guide

Every developer remembers the friction of setting up a new machine—tracking down installers, clicking through wizards, resolving PATH issues, and then repeating the process months later when it’s time to update. Homebrew solves this problem for macOS and Linux users by providing a unified, command‑line interface for installing, updating, and removing software. It has become the de facto package manager on macOS and a trusted companion on Linux, used daily by millions of developers to maintain their toolchains.

This guide covers everything from installation to advanced workflows. You’ll learn the concepts, essential commands, best practices, and how to integrate Homebrew into your professional development environment. Whether you’re setting up your first laptop or standardising tooling across an engineering team, Homebrew will save you time and reduce environment drift.

What Is Homebrew?

Homebrew is an open‑source package manager that simplifies software installation on macOS and Linux. It installs packages into a self‑contained directory (by default /opt/homebrew on Apple Silicon, /usr/local on Intel Macs, and /home/linuxbrew/.linuxbrew on Linux) and symlinks them into your PATH. This keeps the system’s own directories clean and avoids permission issues.

Homebrew manages two main types of software:

• Formulae: command‑line tools and libraries (e.g., Git, Python, Node.js). A formula is a Ruby script that tells Homebrew how to compile or install a package.
• Casks: macOS desktop applications, fonts, and plugins (e.g., Google Chrome, VS Code, Docker Desktop). Casks install GUI apps the way you’d drag them to the Applications folder.

Additionally, Taps are third‑party repositories of formulae and casks. They let the community extend Homebrew beyond its core offerings.

Homebrew’s philosophy is “don’t repeat yourself.” It automates dependency resolution, ensures consistent file placement, and provides simple commands to keep everything up to date. For developers juggling dozens of tools, that consistency is invaluable.

Installing Homebrew

Homebrew can be installed with a single command, though the exact steps vary by platform.

macOS (Apple Silicon and Intel)

Open Terminal and run:

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

The script explains what it will do and pauses for confirmation. After installation, you may need to add Homebrew to your PATH. Follow the on‑screen instructions, which typically involve running two eval commands or adding them to your shell profile (~/.zshrc).

Linux

The same install script works on Linux, but Homebrew installs into /home/linuxbrew/.linuxbrew by default. You’ll need to add the necessary environment variables, as prompted. Some Linux distributions also offer a native Homebrew package, but using the official installer gives you the latest version.

System Requirements

• macOS 12 (Monterey) or later for full support; older versions may work with limitations.
• Linux: glibc 2.13 or newer, a 64‑bit x86 or ARM CPU, and development tools (gcc, make) installed.
• Command Line Tools for Xcode (macOS) or build‑essential (Linux) are prerequisites. The installer will attempt to install them if missing.

Verifying Installation

brew --version

This prints the installed version. Then run:

brew doctor

This checks for configuration issues and suggests fixes. A clean brew doctor output means your setup is healthy.

Updating Homebrew

Homebrew updates itself automatically before most commands, but you can run brew update explicitly to fetch the latest formulae and versions.

Understanding Homebrew Concepts

A few terms appear frequently in Homebrew documentation. Understanding them helps you reason about your installation.

• Formula: a package definition (Ruby script) that tells Homebrew how to install a command‑line tool or library. For example, git is a formula.
• Cask: an extension of a formula that installs a macOS native application (.app bundles, fonts, plugins). E.g., google-chrome is a cask.
• Tap: a Git repository containing additional formulae and/or casks. The core repository (homebrew/core) is tapped by default. You can add community taps for niche tools.
• Cellar: the directory where Homebrew stores installed package versions. Each version of a formula lives in its own subdirectory, and the active version is symlinked.
• Keg‑only: a formula that is installed but not symlinked into the default PATH, often to avoid conflicts with the system’s own software. You can still use it by referencing its full path or by manually linking.

Homebrew organizes all this in a consistent directory structure, making manual inspection or backup straightforward.

Essential Homebrew Commands

These commands cover 90% of daily usage. Every developer should be comfortable with them.

• brew help – displays a list of commands and brief usage.
• brew search <text> – searches formulae and casks by name or description. Useful when you’re unsure of an exact package name.
• brew install <package> – installs the latest version of a formula or cask. For casks, use brew install --cask <name>.
• brew uninstall <package> – removes a package. Add --force to remove all versions.
• brew list – shows all installed formulae and casks.
• brew info <package> – displays version, dependencies, installation options, and any caveats.
• brew update – fetches the latest package definitions from all taps.
• brew upgrade – upgrades all installed packages to the latest versions. Use brew upgrade <package> to upgrade a single package.
• brew cleanup – removes old versions of packages and clears the download cache. Run periodically to reclaim disk space.
• brew doctor – diagnoses common configuration problems and suggests fixes.

Example workflow for a new developer:

brew update
brew install git
brew install --cask visual-studio-code
brew cleanup

Installing Development Tools

Homebrew excels at installing the command‑line tools that form the backbone of modern development. Rather than hunting down individual installers, you can bootstrap a full environment with a few brew commands.

Common tools installed via Homebrew include:

• Git: brew install git gives you the latest version, often newer than the system‑provided one.
• Docker CLI: brew install docker provides the client; the Docker Engine can run locally via Docker Desktop (cask) or Colima.
• Node.js: brew install node installs Node and npm. For version management, consider nvm or fnm.
• Python: brew install python installs Python 3.x alongside pip. It’s keg‑only on macOS to avoid overriding the system Python.
• Java: brew install openjdk provides OpenJDK. Use SDKMAN for fine‑grained version switching, as described in our SDKMAN guide .
• Terraform: brew install terraform gives you the latest infrastructure‑as‑code tool.
• kubectl: brew install kubectl ensures you always have the current Kubernetes CLI.
• jq: brew install jq for JSON processing in the terminal, a companion to our online JSON tools .
• wget and curl: often pre‑installed, but Homebrew provides updated versions.

The real power isn’t any single tool, but the reproducibility. You can store a list of installed packages (brew leaves for top‑level packages, or brew bundle for a declarative Brewfile) and recreate the same environment on another machine. This is gold for onboarding new team members or provisioning a work laptop.

Managing GUI Applications

With Homebrew Cask, you can manage graphical desktop apps just like command‑line tools. Installing a cask downloads the app, moves it to the Applications folder, and keeps it updated.

# Install a cask
brew install --cask google-chrome

# List installed casks
brew list --cask

# Upgrade all casks
brew upgrade --cask

# Remove a cask
brew uninstall --cask google-chrome

Apps installed via cask integrate naturally with macOS Launchpad and Spotlight. For developers, this means your entire toolchain—from terminal utilities to IDEs—can be scripted and updated with a single command. Common developer casks include Visual Studio Code, Docker Desktop, Postman, and iTerm2.

When should you use a cask versus downloading the app manually? Almost always prefer the cask for developer tools you want to keep updated. For specialised apps with their own update mechanisms (like some JetBrains IDEs), the manual approach may still be fine, but cask reduces management overhead.

Version Management

Homebrew installs the latest stable version by default, which is ideal for most tools. However, some projects require older versions or strict version pinning.

• Checking outdated packages: brew outdated lists all packages that have newer versions available. This helps you assess the impact of an upgrade.
• Upgrading selectively: brew upgrade <package> updates a specific tool without touching others.
• Pinning a version: brew pin <package> prevents a formula from being upgraded when you run brew upgrade. This is useful if a project relies on a specific version of Go, Python, or a database client. Unpin with brew unpin <package> when you’re ready to move forward.
• Installing an older version: Homebrew does not officially support installing arbitrary old versions, but you can sometimes find a formula’s commit history in the core tap and install from a specific commit. For SDKs, we recommend using [SDKMAN] or language‑specific version managers (nvm, pyenv) for more robust multi‑version support.

Best practice: keep your default toolchain current with regular brew upgrade, and use version managers for the languages and runtimes where you need multiple versions simultaneously.

Taps

Taps are additional repositories that extend Homebrew’s catalogue. The core tap (homebrew/core) includes thousands of popular packages, but many organisations and developers maintain their own taps for niche or proprietary software.

• Adding a tap: brew tap <user>/<repo> (e.g., brew tap hashicorp/tap). This makes the tap’s formulae and casks available for installation.
• Installing from a tap: once tapped, you install packages normally, e.g., brew install hashicorp/tap/terraform.
• Listing taps: brew tap without arguments shows all currently tapped repositories.
• Removing a tap: brew untap <user>/<repo>.

Security consideration: third‑party taps can execute arbitrary code during installation. Only add taps from sources you trust. Prefer official vendor taps (like HashiCorp’s) when available. Check the repository’s stars, recency, and community activity before adding a random tap from an unknown developer.

Homebrew Best Practices

Adopting these habits will keep your Homebrew environment healthy and your development machine reproducible.

• Update regularly. Run brew update && brew upgrade weekly. Timely updates reduce the risk of breaking changes piling up.
• Clean up after upgrades. Run brew cleanup to remove old versions and free disk space. You can automate this by setting HOMEBREW_NO_INSTALL_CLEANUP to 0.
• Review installed packages. Run brew list periodically and uninstall tools you no longer use. A lean system is faster and easier to troubleshoot.
• Trust but verify. Install only packages maintained by reputable developers. The core tap is well‑curated; exercise caution with obscure taps.
• Use a Brewfile for team environments. Run brew bundle dump to generate a Brewfile listing all your installed formulae, casks, and taps. Commit this file to your team’s repository so every developer can replicate the environment with brew bundle install. This is a simple but powerful way to standardise tooling across a team.
• Leverage brew info before installing. Check for caveats, dependencies, and post‑install instructions. It avoids surprises.
• Prefer Homebrew over manual installs. Even if a tool provides a direct installer, the Homebrew formula simplifies updates and uninstalls. The only exceptions are tools that require manual activation or extensive configuration.

Common Mistakes

Even experienced users can trip over these pitfalls.

• Mixing manual installations with Homebrew. Installing Git via Xcode Command Line Tools while also installing it via Homebrew can lead to PATH confusion. Stick with one method per tool.
• Running too many taps. Each tap slows down brew update and increases the surface area for conflicts. Keep your tap list minimal.
• Ignoring brew doctor warnings. The doctor often catches permissions issues, stray files, or broken symlinks that cause subtle failures. Address its recommendations early.
• Forgetting cleanup. Old package versions accumulate in the Cellar and can consume gigabytes over time. A monthly brew cleanup is a good habit.
• Blindly upgrading everything. In a production‑critical environment, test a major version upgrade in a staging context first, especially for databases, compilers, or infrastructure tools.

Homebrew in Modern Development

Homebrew fits into nearly every layer of modern software engineering.

• Local development: it provides the fastest way to install languages, databases, and supporting tools on a personal machine. The combination of brew bundle and a Dev Container setup is a powerful onboarding recipe.
• DevOps and CI/CD: many CI runners for macOS and Linux have Homebrew pre‑installed. You can use a Brewfile to provision build agents identically, reducing “works on my machine” issues. For example, a GitHub Actions macOS runner can run brew bundle install to set up the exact tool versions needed for a build.
• Infrastructure as Code: tools like Terraform, Packer, and Ansible are regularly installed via Homebrew, ensuring the provisioning workstation matches the scripts.
• Developer onboarding: a new team member can go from zero to a full development environment with a single bootstrap script that installs Homebrew and then runs brew bundle install. This drastically reduces the time to first commit.

By treating Homebrew as infrastructure, you turn your development environment into a managed, versioned asset.

Alternatives to Homebrew

Homebrew isn’t the only package manager, and it’s not always the right tool. Knowing the alternatives helps you choose wisely.

Tool	Platform	Strengths	When to use
SDKMAN	macOS / Linux / WSL	Manages parallel versions of Java, Kotlin, Scala SDKs	When you need to switch between JDK versions frequently.
apt	Debian/Ubuntu	Native, deeply integrated, handles system libraries	For Linux system‑level dependencies and core utilities.
yum / dnf	RHEL / Fedora	Native RPM‑based management	For Red Hat‑based systems and enterprise environments.
pacman	Arch Linux	Fast, simple, rolling‑release	On Arch or Manjaro; best when you want the latest.
Chocolatey	Windows	PowerShell‑based package management with community feeds	For Windows desktop development environments.
Winget	Windows	Official Microsoft package manager, integrated with Windows	For modern Windows 10/11 setups that need simplicity.
MacPorts	macOS	Compiles from source, installs into /opt/local	When you need fine‑grained compile options or legacy macOS support.

For developers on macOS, Homebrew and SDKMAN often coexist. Homebrew installs system tools and GUI apps; SDKMAN handles Java‑family SDKs. The [Homebrew vs SDKMAN] comparison explores this in detail.

On Linux, Homebrew is a supplement, not a replacement for the native package manager. Use apt or dnf for system libraries and kernel modules, and Homebrew for development tools that aren’t packaged in the distro’s repositories (or when you need a newer version).

Frequently Asked Questions

1. What is Homebrew used for?
   Homebrew installs command‑line tools, libraries, and macOS desktop applications from a central repository. It keeps them updated and manages dependencies automatically.

2. Is Homebrew only for macOS?
   No. Homebrew also runs on Linux and the Windows Subsystem for Linux (WSL). On macOS it is the dominant package manager; on Linux it’s often used alongside the native package manager.

3. What’s the difference between a Formula and a Cask?
   A formula installs command‑line software and libraries. A cask installs macOS GUI applications, fonts, and plugins. Use brew install for formulae and brew install --cask for casks.

4. Should I update Homebrew regularly?
   Yes. Regular updates (brew update && brew upgrade) keep your tools current, secure, and compatible. Weekly updates strike a good balance between freshness and stability.

5. Is Homebrew safe?
   The core repository is carefully curated and community‑reviewed. Third‑party taps carry the same risks as any community software—review the repository’s reputation before tapping. Homebrew itself runs without sudo, reducing system‑wide risk.

6. Can Homebrew install GUI applications?
   Yes, via casks. Most popular macOS apps are available, from browsers to code editors to database GUIs.

7. How do I remove unused packages?
   Run brew autoremove to uninstall packages that are only installed as dependencies and are no longer needed. Then brew cleanup to delete old versions.

8. Does Homebrew manage dependencies?
   Yes. When you install a formula, Homebrew automatically installs its required dependencies. When you uninstall something, brew autoremove can clean up orphaned dependencies.

9. Should teams standardise on Homebrew?
   If your team uses macOS or Linux, standardising on Homebrew with a shared Brewfile ensures everyone has identical tool versions, reducing environment‑related bugs. Pair it with Docker for even stronger reproducibility.

10. What’s the difference between Homebrew and SDKMAN?
    Homebrew is a general‑purpose package manager; SDKMAN specialises in parallel version management for Java‑family SDKs. Many developers use both: Homebrew for tools, SDKMAN for JDK versions. See our [comparison] for more.

Conclusion

Homebrew turns the chaotic task of managing development software into a few predictable commands. It doesn’t just save time—it eliminates entire categories of environment bugs, simplifies onboarding, and lets you treat your machine as a reproducible, versioned asset.

Start by installing your daily tools with brew, then explore Brewfiles for team‑wide consistency. If you work with Java or multiple SDK versions, complement Homebrew with [SDKMAN] . For containerised environments, our [Docker Desktop guide] shows how to layer Docker alongside your brew‑managed toolchain.

Remember: a well‑maintained Homebrew environment is a hallmark of a disciplined developer. Return to the Tool Guides hub for practical, deep‑dive instruction on every tool in your stack. Build better with better tools—starting with the package manager that keeps them all in check.