← Claude Code Hub
May 17, 2026 · 7 min read ✦ Tip #073

How to update Claude Code: one command, unless Homebrew or npm has left you weeks behind

With the native installer it's claude update, and even that is optional: it updates itself. Homebrew, WinGet, apt, dnf and apk don't, and if you haven't seen a new feature in weeks, claude doctor tells you why.

Updating Claude Code: table by install method with auto-update and manual command

TL;DR Check your version with claude --version. If you installed via the native installer (curl … | bash), it updates itself in the background and the new version kicks in the next time you start Claude Code. Force an update now with claude update. For Homebrew, WinGet, apt, dnf or apk, use the package manager's own upgrade command, or set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 and let Claude run it for you on Homebrew and WinGet. If it still won't update, the Auto-updates line in claude doctor tells you why.

To update Claude Code installed with the native installer, run claude update, though you rarely need to: it updates itself in the background. Homebrew, WinGet, apt, dnf and apk installs don't, so you run your package manager's own command instead. An npm install updates itself as long as it can write to npm's global directory. Here they all are in one table.

If you haven't seen a new feature in months, you're probably in the second group: a package-manager install that doesn't update itself.

Do you have to update? Yes

New features ship every couple of weeks: skills, subagents, agent teams, /goal, GitHub Actions, the Agent SDK. The native binary stays compatible with your CLAUDE.md and your settings across versions, so the cost of updating is close to zero. The cost of not updating is missing features that probably already have their own tips on this site. And a newly launched model can require a newer version than the one you have.

Check your version

claude --version
# 2.1.293 (Claude Code)

Compare against the latest published version, or from inside Claude run /release-notes (interactive changelog picker).

Does Claude Code update automatically?

It depends on how you installed it. The native installer updates itself, and so does npm as long as it can write to its global directory: Claude Code checks for new versions on startup and periodically while it runs, downloads them in the background, and the new version takes effect the next time you start Claude Code. The session you have open stays on the old one.

How you installed Auto-update Manual update command
Native installer (curl … | bash) ✅ Background claude update
Homebrew (brew install --cask claude-code) ❌ brew upgrade claude-code (or brew upgrade claude-code@latest, depending on the cask you installed)
WinGet (Windows) ❌ winget upgrade Anthropic.ClaudeCode
apt (Debian, Ubuntu) ❌ sudo apt update && sudo apt upgrade claude-code
dnf (Fedora, RHEL) ❌ sudo dnf upgrade claude-code
apk (Alpine) ❌ apk update && apk upgrade claude-code
npm (global) ✅ If npm's global directory is writable npm install -g @anthropic-ai/claude-code@latest

Important for npm: do NOT use npm update -g. It respects the semver range from the original install and may not move you to the newest release. If npm's global directory isn't writable, Claude Code can't update itself and shows a one-time notice at startup.

How do I force Claude Code to update?

You don't have to wait for the next background check:

claude update

If there was a new version, it prints Successfully updated from <old version> to version <new version>. If you're already current, Claude Code is up to date (<version>). Homebrew, WinGet and apk installs print Claude is up to date! instead. Quit and reopen Claude Code to start using the new version.

Why isn't my Claude Code updating?

claude doctor has the answer. It prints a diagnosis without starting a session, and these are the lines that matter here (real output from my machine):

Running: native (2.1.293)
Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER)
Auto-update channel: latest
Last update attempt: success → 2.1.282 (2026-09-25)

Running names your install method. Auto-updates says whether the background check is off and what turned it off: in my case, the DISABLE_AUTOUPDATER variable. Last update attempt is the result of the most recent attempt.

The usual causes:

  • You installed with a package manager. Homebrew, WinGet, apt, dnf and apk don't update themselves. Use the command from the table.
  • DISABLE_AUTOUPDATER or DISABLE_UPDATES is set in the env block of your settings.json, or in your company's managed settings.
  • It did update, but you haven't restarted. The new version takes effect when you reopen Claude Code.
  • Your package manager doesn't have the version yet. Claude Code can tell you about a release before it reaches Homebrew or WinGet. Wait and run the upgrade again later.
  • WinGet fails while Claude Code is running, because Windows locks the executable. Quit it and run winget upgrade Anthropic.ClaudeCode.

If Last update attempt shows an error, the four causes of that failure and their fixes are in when the auto-update fails.

Install a specific version (or downgrade)

Sometimes you don't want the latest: you want a specific version, for CI or because a recent update broke something. The native installer accepts either an exact version or a channel name:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# Windows PowerShell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89

Whatever channel you pick at install time (latest, stable, or an exact number) becomes the default for future auto-updates.

The package-manager trick

If you installed via Homebrew or WinGet but want Claude Code to update itself anyway, drop this into your settings.json:

{
  "env": {
    "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
  }
}

From then on, when a new version is available Claude runs the upgrade in the background and shows a restart prompt on success. apt, dnf, and apk still require manual updates because their commands need elevated privileges.

Channel: latest vs stable

By default you're on "latest": new features as soon as they ship. If a recent regression bit you and you'd rather be conservative:

{
  "autoUpdatesChannel": "stable"
}

"stable" runs about a week behind and skips releases with major regressions. Switch the channel via /config → Auto-update channel, or by editing settings.json directly. For teams: managed settings enforce a channel and minimumVersion org-wide.

Homebrew ignores this setting, because the cask picks the channel (claude-code tracks stable and claude-code@latest tracks latest). So do apt, dnf and apk: there the repository you registered decides.

Pin a minimum version

To make sure you don't accidentally downgrade past a specific version (for example when switching from "latest" to "stable"):

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

Useful in CI or teams that want a common floor.

Disable auto-updates

If your network or internal policy doesn't allow Claude to update itself:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER only stops the background check: claude update still works. To block everything (including manual updates), use DISABLE_UPDATES.

Reference: env vars and settings

Variable / setting For
claude --version Show installed version
claude update Force update now
claude doctor See whether auto-update is on and how the last attempt went
autoUpdatesChannel "latest" or "stable"
minimumVersion Version floor (refuses downgrades)
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 Auto-update through Homebrew/WinGet
DISABLE_AUTOUPDATER=1 Turn off the background check
DISABLE_UPDATES=1 Block every update path

Pairs well with

One case where updating is the whole fix: "Request rejected as unprocessable by the model" in sessions with hundreds of screenshots, fixed in 2.1.290.

Official docs: Update Claude Code

Found this useful? See more of wmedia.es in your Google results.

Add wmedia.es as a preferred source on Google
FREE GUIDE

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

  • 1. Rules the first match wins
  • 2. Mode a dial, not a switch
  • 3. Auto mode a classifier approves for you
  • 4. Sandbox a fence the OS puts up
  • 5. Bypass only inside a container
Are you a professional Web developer?

You'll receive the guide by email · You join the Gravitas newsletter · Unsubscribe anytime

of 10
#

Wmedia · 10 pages
FREE GUIDE · 10 pages · 5 levers

Approve less, but better.

Ten minutes in, you're hitting yes without reading. That's not review, that's prayer. A 10-page guide with the five levers in order of risk.

Are you a professional Web developer? · Unsubscribe anytime
How I use AI

My Claude Code workflow.

The skills, agents and instructions I use as a professional Software Engineer. It's called Craft, and it's a plugin you can install.

See the skills

Tired of approving permissions without reading?