How to Update Claude Code (and Why It May Not)

If you installed Claude Code with the official install script, you don't need to do anything — it updates itself in the background. If you installed it any other way, it probably doesn't, and that's the single fact this page exists to convey.

To update immediately:

claude update

Whether that's necessary depends entirely on how you installed:

Per Anthropic's setup documentation, native installs "automatically update in the background," while Homebrew, WinGet, and Linux package manager installations "do not auto-update by default."

Check what you have first

claude --version

A working install prints something like 2.1.211 (Claude Code). For a fuller picture — install health, settings validation, and the result of the last update attempt — run:

claude doctor

claude doctor is read-only and doesn't start a session — it prints install health, settings-file validation errors, and the result of the most recent update attempt. It's the right first move whenever an update seems stuck, because it tells you why the last attempt failed rather than making you guess. If it reports something you can't place, the installation troubleshooting guide maps errors to fixes.

Updating each install method

Native. Updates download in the background and take effect next launch. claude update forces it now, reporting either Successfully updated from <old> to <new> or Claude Code is up to date (<version>).

Homebrew. Two casks exist and they track different channels — claude-code follows stable, claude-code@latest follows latest. Upgrade whichever you installed:

brew upgrade claude-code        # or: brew upgrade claude-code@latest

Homebrew keeps old versions on disk, so run brew cleanup occasionally.

WinGet. winget upgrade Anthropic.ClaudeCode. This can fail while Claude Code is running because Windows locks the executable — close it first.

npm. Use @latest explicitly. Avoid npm update -g, which respects the semver range from your original install and may not move you forward at all:

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

Homebrew and WinGet can update themselves if you opt in — set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 and Claude Code runs the upgrade in the background when a new version appears. apt, dnf, and apk still require manual upgrades because those commands need elevated privileges.

Choosing a release channel

Two channels, set with autoUpdatesChannel in your settings file:

• latest (default) — new features as soon as they ship
• stable — a version typically about a week old, skipping releases with major regressions

{
  "autoUpdatesChannel": "stable"
}

You can also set it through /config → Auto-update channel. For teams, this can be enforced organization-wide through managed settings, which user and project settings can't override.

stable is the right default for anyone who can't afford a bad morning. A week's lag costs you very little and skips the releases that get pulled.

Pinning a floor

minimumVersion stops updates going below a value — including the downgrade you'd otherwise get switching from latest to stable:

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

Switching channels via /config prompts you to stay put or allow the downgrade; staying sets minimumVersion for you.

Note the distinction: minimumVersion constrains updates. If you need Claude Code to refuse to start outside a range, that's requiredMinimumVersion and requiredMaximumVersion in managed settings.

Turning updates off

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

That stops the background check only — claude update and claude install still work. To block every update path including manual ones, use DISABLE_UPDATES instead. That's for organizations distributing Claude Code through their own channels.

When an update doesn't take

Three causes cover most of it:

You have two installations. An old npm global plus a native install, or a leftover shell alias. claude doctor reports this; the docs have a dedicated section on finding conflicting installations.

A custom launcher. On macOS and Linux the native installer manages ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. If you replaced that with your own script, updates still install new versions but your launcher decides which one runs. Remove ~/.local/bin/claude and run claude update to hand control back.

npm can't write to its global directory. Claude Code shows a one-time notice and claude doctor lists the fixes. Don't reach for sudo npm install -g — the docs warn against it explicitly, and it creates permission problems rather than solving them.

One more known wrinkle: Claude Code may notify you of an update before it's available in Homebrew or WinGet. If the upgrade fails, wait and retry rather than debugging it.

Verifying what you installed

If you care about supply chain integrity, every release publishes a manifest.json of SHA256 checksums, signed with an Anthropic GPG key whose fingerprint is 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE. Verifying the manifest signature transitively verifies every binary it lists. macOS binaries are additionally signed by "Anthropic PBC" and notarized; Linux binaries aren't individually signed, but the apt/dnf/apk repositories are.

For getting set up in the first place, how to install Claude Code covers the install paths. For extending it once it's running, Claude skills and MCP clients cover the two main extension points.

Worth naming the wider pattern. Keeping a CLI current is a maintenance tax on every tool you run locally, and it's a big part of why people who can see a useful AI setup never end up running it — the environment keeps drifting underneath them. Taku mirrors a working AI setup into a desktop workspace and runs it there instead of asking you to reproduce and maintain someone else's environment. The free app library shows what's available to mirror. Taku is in Beta, and the Mac app is available now.

FAQ

How do I update Claude Code?

Run claude update. Native installs also update themselves in the background; Homebrew, WinGet, and Linux package manager installs need their own upgrade command.

Why isn't Claude Code auto-updating?

Most likely you installed via Homebrew, WinGet, apt, dnf, or apk — none of which auto-update by default. Other causes are a second conflicting installation, a custom launcher at ~/.local/bin/claude, or an npm global directory you can't write to. Run claude doctor.

How do I check my Claude Code version?

claude --version prints it. claude doctor gives the fuller diagnostic, including why the last update attempt failed.

What's the difference between the latest and stable channels?

latest ships new features immediately. stable is roughly a week behind and skips releases with major regressions. Set it with autoUpdatesChannel.

Can I stop Claude Code from updating?

Yes. DISABLE_AUTOUPDATER stops background checks while leaving claude update working; DISABLE_UPDATES blocks every path.

Key points

• Native installs auto-update; Homebrew, WinGet, and Linux package managers do not.
• claude doctor tells you why an update failed instead of making you guess.
• stable lags about a week and skips bad releases — a good default.
• Two installations or a custom launcher are the usual reasons an update seems not to take.
• Never use sudo npm install -g; fix permissions instead.