How to Update Homebrew on macOS: Step-by-Step Guide 2026

Introduction / Why It's Needed

Homebrew is a package manager for macOS that allows you to easily install and update thousands of utilities and applications from the command line. Regularly updating Homebrew is critically important for two reasons:

1. Security: Updates often contain patches for vulnerabilities in both Homebrew itself and the programs installed through it.
2. Stability and New Features: New package versions fix bugs and add functionality. Outdated formulas may stop working with new versions of macOS or other dependencies.

This guide will show you how to safely and correctly update Homebrew and all your installed packages.

Requirements / Preparation

Before you begin, ensure that:

• You have a compatible version of macOS (10.14 Mojave or newer).
• You have internet access.
• You have administrator privileges (may be required for installing some packages, but not for updating Homebrew itself).
• Homebrew is already installed on your system. If not, perform the standard installation first.

Step-by-Step Instructions

Step 1: Check Your Current Homebrew Version

Open Terminal and run the command:

brew --version

You will see something like:

Homebrew 4.2.0
Homebrew/homebrew-core (git revision 123456; last commit 2026-02-15)

This confirms that Homebrew is working and shows its version. If the command is not found, Homebrew is not installed or not added to your PATH.

Step 2: Update Homebrew Itself

This is the most important first step. It updates the package manager itself and its "recipes" (formulas) for all packages.

brew update

What this command does:

• Performs a git pull in the Homebrew directory (/usr/local/Homebrew or /opt/homebrew).
• Updates the "core" — the main homebrew-core formula repository.
• Updates the homebrew-cask repository for GUI applications (if you have it enabled).

Expected output: Updated 1 tap (homebrew/core). If the output shows Already up-to-date., you are already using the latest version.

Step 3: Upgrade All Installed Packages (Formulas)

After updating the recipes, Homebrew learns that newer versions of your installed packages are available. Upgrade them all with one command:

brew upgrade

What this command does:

• For each installed formula, it checks if a newer version exists in the updated recipe.
• If one exists, it downloads and installs the new version.
• Important: Homebrew does not remove old package versions after an upgrade by default. That is done by the brew cleanup command.

You will see a list of packages that will be upgraded and their old/new versions. Confirm the action if prompted (usually not for upgrade).

Step 4: Clean Up Old Package Versions (Mandatory!)

After brew upgrade, files from old package versions remain on your disk. They take up space and can cause conflicts. Remove them:

brew cleanup

What this command does:

• Deletes old versions of all packages installed via Homebrew.
• Removes old download files (downloads) from Homebrew's cache.
• You can clean up a specific package: brew cleanup <package_name>.

Output: A list of removed files and the amount of space freed (e.g., Removed: 1.2G of cached downloads).

Step 5: Check System Integrity (Final Diagnostics)

Complete the process by running the built-in diagnostics:

brew doctor

Ideal result: Your system is ready to brew.

If there are issues, Homebrew will describe them in detail and often suggest a solution. For example:

• Warning: You have Xcode... — just informational.
• Error: /usr/local is not writable. — a critical error requiring permission fixes.

Verifying the Result

You can confirm everything is up-to-date in two ways:

1. Run brew upgrade again: If after completing all steps you run brew upgrade and get Already up-to-date. or empty output, everything is updated to the latest versions.
2. View the list of outdated packages: The brew outdated command will show only packages for which a new version exists. After a successful upgrade, this list should be empty.

Potential Issues

Issue: Permission Errors During brew update or brew upgrade

Symptom: Error: /usr/local/... is not writable.Cause: Incorrect permissions on the Homebrew directory (often after manual changes or installation via sudo). Solution: Do not use sudo with Homebrew! Instead, fix the permissions:

sudo chown -R $(whoami) /usr/local/*
# Or for Apple Silicon:
sudo chown -R $(whoami) /opt/homebrew/*

Then retry brew update.

Issue: brew update Hangs or Gives Network Errors

Symptom: The command hangs for a long time or fails with fatal: unable to access 'https://github.com/Homebrew/...': Could not resolve host: github.com. Cause: Network connectivity issues, GitHub blocking, or a non-working DNS. Solution:

• Check your internet (ping 8.8.8.8).
• Try brew update --force to force an update.
• Temporarily disable your VPN or antivirus.
• If the problem is on GitHub's side, you will have to wait.

Issue: Formula Conflicts or brew doctor Shows Many Warnings

Symptom: After upgrade, some package commands stop working, or brew doctor shows dozens of warnings. Cause: This is most often a result of manual intervention in Homebrew files (/usr/local/bin, /usr/local/lib) or conflicting packages. Solution: Read the brew doctor output carefully. Often these steps help:

1. brew cleanup (removes conflicting old versions).
2. Reinstall the problematic package: brew reinstall <package_name>.
3. If the issue is serious, search for the specific error text in the Homebrew Issues tracker.