How to Update Claude Code When Homebrew Won't Cooperate

If you use Claude Code via Homebrew on macOS, you might eventually run into this confusing situation:

$ claude --update
Current version: 2.1.81
Update available: 2.1.81 → 2.1.91

To update, run:
  brew upgrade claude-code

So you do what it says:

$ brew upgrade claude-code
Warning: Not upgrading claude-code, the latest version is already installed

You try the usual Homebrew tricks — brew update, brew cleanup, brew reinstall — same thing. What’s going on?

The Root Cause: Two Release Channels

Running brew info claude-code reveals the answer:

==> claude-code ✔: 2.1.81
...
==> Caveats
This cask tracks the stable release channel. In-app update notifications
default to the latest channel regardless. To align notifications with this
cask, set the auto-update channel to "stable" via /config or in
~/.claude/settings.json

The Homebrew cask tracks the stable release channel. But claude --update checks the latest channel by default. These are two different release trains:

• Stable: what Homebrew ships — less frequent, more tested
• Latest: what Claude’s built-in updater sees — more frequent, bleeding edge

Homebrew is correct: you have the latest stable version. Claude is also correct: there’s a newer latest version. They’re just talking about different things.

Solution 1: Align the Release Channel

If you’re happy on stable, tell Claude to stop checking the latest channel. Run claude /config or edit ~/.claude/settings.json:

{
  "releaseChannel": "stable"
}

Now claude --update will only notify you about stable releases that match what Homebrew provides. No more false alarms.

Solution 2: Switch to npm

If you want the latest builds immediately, bypass Homebrew entirely:

brew uninstall claude-code
npm install -g @anthropic-ai/claude-code@latest

With npm you control the version directly — no cask lag, no channel mismatch. Updates are instant: npm update -g @anthropic-ai/claude-code.

Solution 3: Just Wait

The stable cask catches up eventually. If the version gap doesn’t bother you and you don’t need cutting-edge features, do nothing. The warning is cosmetic.

Which Should You Pick?

The underlying lesson: when a tool’s built-in updater disagrees with your package manager, check which release channel each one is tracking. They’re usually both right — just looking at different sources of truth.

Encountered on macOS with Claude Code 2.1.81 (Homebrew cask) vs 2.1.91 (latest channel), April 2026.