brew update refreshes Homebrew itself and its package definitions. brew outdated lists installed packages that have newer versions. brew upgrade installs those newer versions. Run them in that order, reading the outdated list before you upgrade, so you know what is about to change on your machine.
The three commands in order
The Homebrew FAQ answers "How do I update my local packages?" in three steps.
- First update all package definitions (formulae) and Homebrew itself with brew update.
- List which installed packages are outdated with brew outdated.
- Upgrade everything with brew upgrade, or one package with brew upgrade followed by its name.
The common mistake is thinking brew update upgrades your tools. It does not. It only refreshes what Homebrew knows. Your installed software stays at the same versions until you upgrade.
Why the middle step matters
Running brew outdated gives you a review point. You can see which tools will move, notice a major version jump, and decide whether to wait. Skipping straight to upgrade everything means a new release of any tool lands on a laptop that holds your credentials, with no look at all.
That is not an argument against updating. Security fixes only help once installed. It is an argument for a short, deliberate step between knowing and doing. Our post on automatic updates on a developer Mac covers the wider picture.
Holding something back
The FAQ documents brew pin, which stops a formula or cask from being updated or upgraded, and brew unpin to allow it again. It adds a caveat: a pinned, outdated formula that another formula depends on must be upgraded when required, because Homebrew does not allow formulae to be built against outdated versions.
If you also do not want Homebrew to learn about newer versions until you choose, the FAQ gives an environment variable, HOMEBREW_NO_AUTO_UPDATE set to 1, which disables auto-updating entirely. Think about that trade: you gain predictability and lose automatic awareness of new versions and fixes. If you set it, put a calendar reminder next to it.
Cleanup behaviour worth knowing
The FAQ states Homebrew automatically uninstalls old versions of each upgraded formula and periodically performs additional cleanup every 30 days. Settings exist to disable that. Old versions that linger are old software still on disk, so leave cleanup on unless you have a reason.
A monthly routine
brew update
brew outdated
brew upgrade
brew cleanup
Between the second and third lines, read the list. If a tool you do not recognise appears, that is a prompt to remove it or find out why it is installed. The Brewfile post shows how to keep a record.
Try it yourself
Click through it at your own pace, or open it full screen.
Watch how knowing a fix exists and applying it are two separate steps, just like update and upgrade.
Quick check
Does brew update upgrade my installed tools?
No. It refreshes Homebrew and its definitions. Use brew upgrade to install newer versions.
How do I stop one package from upgrading?
Use brew pin on it, and brew unpin to allow updates again.
Sources
Last reviewed: 19 October 2026.
