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 withclaude update. For Homebrew, WinGet, apt, dnf or apk, use the package manager's own upgrade command, or setCLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1and let Claude run it for you on Homebrew and WinGet. If it still won't update, theAuto-updatesline inclaude doctortells 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_AUTOUPDATERorDISABLE_UPDATESis set in theenvblock of yoursettings.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
/doctor: audits install, version, MCP, and skills when something feels off.- Slash commands cheat sheet: includes
/release-notesand/config. - When the auto-update fails: the line in
claude doctorthat names which of the four causes you hit. - "Premature close": the error that, up to 2.1.289, hid a git or gh that wasn't installed.
- "Unrecoverable interface error": ten causes of that exit, fixed between 2.1.275 and 2.1.289.
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