Brewfile cleanup compatibility across Homebrew formula rename transitions

Direct answer

Do not assume brew bundle cleanup treats a renamed formula as an alias of the new name. In practice, cleanup compares the installed formula names on disk against the entries in your Brewfile. If your Brewfile still lists the old identifier, cleanup can treat the currently installed, renamed formula as unlisted and remove it. Installation and cleanup are separate resolution paths.

What is confirmed vs. likely

Confirmed in model knowledge: Homebrew core commonly retains an alias for a renamed formula for a transition period, so brew install <oldname> still resolves to the new formula. Once that alias is removed, the old name becomes a hard error.

Likely explanation rather than confirmed fact: brew bundle cleanup is not guaranteed to be alias-aware. It appears to operate on exact installed-name matching, so an archived Brewfile can produce the opposite of the intended state: uninstall the current formula and then fail to reinstall the deprecated name.

Dependency resolution and compatibility window

If the old name is still an alias, brew bundle resolves dependencies through the new formula's dependency graph. If the alias is gone, brew bundle fails during resolution rather than silently substituting a different package.

There is no documented, guaranteed compatibility window for Brewfiles generated after upstream renames. Homebrew's alias policy is a tap-level transition mechanism, not a promise to brew bundle cleanup.

Steps for this case

1. Check whether the old name is still an alias:
   

   brew info <oldname>

   If it resolves to the new name, the alias is live; if it errors, the window has closed.
2. Run brew bundle check with the archived Brewfile and record whether the entry is reported as installed, missing, or mismatched.
3. Dump the current state to a temp file and diff:
   

   brew bundle dump --file=/tmp/current.Brewfile
   diff /tmp/current.Brewfile ./Brewfile

4. Replace old names with the canonical names shown by brew info, then run brew bundle install before any cleanup.
5. Test cleanup only in a disposable Homebrew prefix or after backing up the Brewfile; never run cleanup on an archived Brewfile as the first step in your only working environment.

Version assumptions and the one diagnostic that matters

These observations are version-sensitive. Alias retention and cleanup matching can differ across Homebrew and homebrew/bundle releases, so verify on the exact machine before relying on cleanup with an archived Brewfile.

One diagnostic detail changes the recommendation: does brew info <oldname> resolve to the new formula name, or does it return an error? If it resolves, migrate names and proceed with cleanup after install. If it errors, the Brewfile must be edited before any bundle command will succeed.