brew update vs brew upgrade: 15 MB Moved, 0 Programs

I meant to run a dry run. I typed brew update -n on the Mac mini that runs this business unattended, expecting Homebrew to tell me what it would do and then do nothing. It downloaded a new portable Ruby, updated itself across a major version, and only then printed a usage error for the flag I had passed. There is no --dry-run for brew update. There is one for brew install and one for brew upgrade, but not for the command whose name makes people most nervous.

The accident turned out to be a cleaner demonstration than anything I would have designed. I had recorded the machine's state minutes earlier for another reason, so I have a byte-level before and after of what brew update touches. It moved about 15 MB of metadata and changed zero installed programs.

Before and after, on the same machine

Mac mini M4, macOS 26.4.1, a rig that has been up continuously for months. Both snapshots are from 2026-09-20, roughly four minutes apart.

What I measured	Before	After
brew --version	6.0.22	7.0.4
/opt/homebrew git HEAD	08e85c4e (2026-09-05)	edb70f03 (2026-09-17)
packages.arm64_tahoe.jws.json	15,459,603 B	15,524,658 B
formulae in that file	8,595	8,610
casks in that file	7,711	7,743
brew list --formula	104	104
newest directory in Cellar	Sep 7 15:01	Sep 7 15:01
brew outdated --formula	36	43

Two rows carry the whole answer. The Cellar, where Homebrew keeps the programs you installed, did not move at all: find /opt/homebrew/Cellar -maxdepth 2 -newermt "2026-09-20 00:00" returns nothing. Meanwhile the outdated count grew by seven: ggml, jemalloc, llama.cpp, merve, node@22, readline, xz.

Those seven did not rot during the four minutes. They were already old. My machine simply did not know yet, because the file that describes what the current versions are had been written on September 10 and nothing had refreshed it since. That is the distinction stated as an observation rather than a definition: brew update changes what your machine believes about the world. brew upgrade changes your machine.

The old answer describes a mechanism my machine does not have

Search this question and you get answers that say brew update pulls the newest formula definitions from the Homebrew git repositories. On a default install today that is no longer how it works, and you can check it in one command:

$ brew config | grep 'Core tap'
Core tap: N/A

There is no homebrew/core tap on this machine. /opt/homebrew/Library/Taps holds 3.3 MB and contains exactly two third-party taps I added myself. The entire catalogue of 8,610 formulae and 7,743 casks lives in a single signed JWS file in the cache directory, with a companion byte-offset index so Homebrew can seek to one formula without parsing 14 MB of JSON.

This changed in Homebrew 4.0.0, which told people they could delete the taps outright: "Unless you are developing formulae or casks, you can brew untap homebrew/core and brew untap homebrew/cask to save some space." The same post explains that auto-updates got faster because "they no longer need to perform the slow git fetch of the huge homebrew/core and homebrew/cask taps' Git repositories."

brew update's own help text has not caught up. On 7.0.4 the first line still reads: "Fetch the newest version of Homebrew and all formulae from GitHub using git(1) and perform any necessary migrations." The git part is true of Homebrew itself, which is why my version jumped to 7.0.4 and my repository HEAD moved twelve days. It is not true of the formulae.

What upgrade would have done, per its own dry run

Here -n does what you expect. brew upgrade --dry-run on the refreshed metadata:

==> Would install 3 dependencies:
highway    1.4.0
graphite2  1.3.15
harfbuzz   14.4.0
==> Would upgrade 43 outdated packages
...
tailscale  1.98.5  -> 1.102.4 (15MB)
git        2.54.0  -> 2.55.0 (23MB)
node       26.8.1  -> 26.9.0 (19.9MB)
Warning: Not upgrading 1 pinned package:
node@22 22.23.2_2

Forty-three replacements, about 250 MB across the forty entries that print a size, plus three dependencies I never named. That last part is documented, and it is the detail people miss. From brew upgrade --help, verbatim:

Unless $HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK is set, brew upgrade or brew reinstall will be run for outdated dependents and dependents with broken linkage, respectively.

Unless $HOMEBREW_NO_INSTALL_CLEANUP is set, brew cleanup will then be run for the upgraded formulae and casks or, every 30 days, for all packages.

So brew upgrade with no arguments is not only "replace the outdated things." It also pulls in dependents, and on a thirty-day cadence it runs cleanup across everything you have installed, including old versions of packages that were not part of this upgrade. If you have ever wanted to keep a previous version around, that is the sentence to know about. The most-viewed Stack Overflow question on this command, asked in 2012 and still edited in late 2024, is about exactly this: how to hold one formula back. The answer is brew pin, and you can see it working in my dry run, where node@22 is listed as pinned and skipped.

Why I ran the metadata half and stopped

Line thirty-one of that dry run is tailscale 1.98.5 -> 1.102.4. Tailscale is how I reach this machine at all. It is headless, in another room, behind a FileVault disk that cost me 92 hours of downtime the last time it rebooted without me, and my own operating rules for the rig say in plain language never to touch the remote-access stack.

To be precise about what that would hit: Homebrew owns /opt/homebrew/bin/tailscale and tailscaled, the only tailscale on my PATH and the tool I inspect the link with. The node itself is a separate GUI install under /Applications. So the honest claim is that brew upgrade would swap the CLI I diagnose the connection with, not that it would drop the connection. I did not run it, so I cannot tell you what would have happened.

The same reasoning covers git, node, uv and two Pythons on that list. This rig runs scheduled agent jobs around the clock, and replacing an interpreter underneath a job that is mid-run is a problem I have met from the other direction, when a background cleaner deleted a virtualenv I was actively using. Package managers are allowed to do that; they just do it on purpose.

The rule I use now

I stopped thinking of these as a pair of similar commands and started thinking about which of two directories each one writes to. brew update writes to a cache. It is cheap, it is reversible in the sense that nothing you depend on changed, and the one real risk is that it upgrades Homebrew itself, which is how I landed on 7.0.4 the week 7.0.0 shipped with Intel Macs moved to tier three and macOS 10.15 support dropped. brew upgrade writes to the Cellar, and on a machine doing real work that is a deployment, not a chore.

Concretely, on this rig: brew update then brew outdated runs whenever I want to know where I stand. brew upgrade runs one named package at a time, never bare, and never while a scheduled job is in flight. The tools I rely on brew for are load-bearing. The opposite failure is just as real, and I have it elsewhere on this same machine, where headless runs never check for a new version at all and sit on a stale binary for weeks. Drift in either direction is a choice; the dry run is how you make it deliberately.

One line to keep: update refreshes the catalogue, upgrade replaces your programs, and only one of them has a dry run.

Everything numbered here was measured on one machine on 2026-09-20: a Mac mini M4 on macOS 26.4.1, Homebrew 6.0.22 before and 7.0.4 after. The before snapshot was taken with HOMEBREW_NO_AUTO_UPDATE=1 so the metadata cache stayed frozen, which is why the outdated count of 36 reflects a September 10 catalogue rather than the real state of the world; the jump to 43 is caused by the refresh, not by packages aging. I did not run brew upgrade. Every claim about it comes from brew upgrade --dry-run and from brew upgrade --help on 7.0.4, so side effects of an actual upgrade, such as services restarting, are unobserved and I have not asserted any. The 250 MB total covers only the 40 entries that printed a size; three did not. Quotes from the Homebrew 4.0.0 and 7.0.0 release posts and from the CLI help are verbatim; the Stack Overflow view count of 26,793 came from the Stack Exchange API the same day.