How you update Claude Code depends on how you installed it. A native install updates itself in the background, and claude update applies the newest version straight away. Homebrew, WinGet, apt, dnf and apk installs need their own upgrade command, and npm needs npm install -g @anthropic-ai/claude-code@latest. Not sure which you have? Run claude doctor.
An out-of-date copy of Claude Code is one of the most common reasons a tutorial, a new setting or a newly launched model doesn't behave the way you expect. The fix is usually one command. The catch is that the right command depends entirely on the route your copy came in by, and running the wrong one does nothing useful at all.
Everything on this page follows Anthropic's setup docs for Claude Code, so the commands and settings are the official ones rather than something pieced together from forum threads. If you haven't installed it yet, start with my guide to installing Claude Code and come back here.
Which update route matches your install
Find your row first. Everything else on the page hangs off this.
| How you installed it | Does it update itself? | What updates it |
|---|---|---|
| Native installer | Yes, in the background | Nothing, or claude update to apply it now |
| Homebrew | No, not by default | brew upgrade claude-code or brew upgrade claude-code@latest |
| WinGet | No, not by default | winget upgrade Anthropic.ClaudeCode |
| apt, dnf or apk | No, not by default | Your Linux package manager's upgrade command |
| npm (global package) | Yes, as long as the npm global folder is writable | npm install -g @anthropic-ai/claude-code@latest |
Can't remember how you installed it? Run claude doctor in your shell. It prints read-only installation and settings diagnostics without starting a session, including install health and any warnings with suggested fixes. On macOS and Linux, the native installer manages a launcher at ~/.local/bin/claude that points into ~/.local/share/claude/versions/, so if that's where your copy lives, you're on the native route.
The exact commands for each method
Native install
You mostly don't need to do anything. Claude Code checks for updates when it starts and periodically while it's running. Updates download and install in the background, then take effect the next time you start Claude Code. So if you've been told a new version is out and you're not seeing it, close your session and open a fresh one before you assume something's broken.
To apply an update immediately without waiting for the next background check, run claude update. It tells you either that it's updated you from your old version to the new one, or that Claude Code is up to date.
Homebrew
Homebrew offers two casks, and you upgrade the one you installed. claude-code tracks the stable release channel, and claude-code@latest tracks the latest channel. So it's either brew upgrade claude-code or brew upgrade claude-code@latest.
WinGet
Run winget upgrade Anthropic.ClaudeCode. One thing that trips people up: the upgrade may fail while Claude Code is running, because Windows locks the executable. Close every Claude Code window first, then run it.
On both Homebrew and WinGet you can hand the job back to Claude Code. Set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 and it runs the upgrade in the background when a new version is available, then shows a restart prompt when it succeeds. The upgrade targets only the Claude Code package, so it won't touch anything else you've installed. If you forget to update by hand, I'd switch this on.
apt, dnf and apk
- apt:
sudo apt update && sudo apt upgrade claude-code - dnf:
sudo dnf upgrade claude-code - apk:
apk update && apk upgrade claude-code
npm
Run npm install -g @anthropic-ai/claude-code@latest. Avoid npm update -g, which respects the version range from your original install and may not move you to the newest release. And don't use sudo. Claude Code runs npm without sudo when it updates itself, so an install that needs sudo can't update automatically, and you'll end up stuck on an old version without realising.
When an update fails or seems stuck
Start with claude doctor. It shows the result of the last update attempt Claude Code recorded, which tells you straight away whether the update failed or simply hasn't happened yet. Then work through the usual suspects:
- You haven't restarted. Background updates only take effect on the next start. Close and reopen before anything else.
- You replaced the launcher. If you swapped
~/.local/bin/claudefor your own script or symlink, auto-update andclaude updateleave it in place. New versions still install, but your launcher decides which one runs, and Claude Code keeps every installed version on disk because it can't tell which one your launcher needs. To hand control back, remove~/.local/bin/claudeand runclaude update. - Your npm global folder isn't writable. Claude Code shows a one-time notice at startup, and
claude doctorlists the available fixes. - Windows is holding the file. On WinGet, close Claude Code and run the upgrade again.
Once you think it's worked, run claude --version. A working installation prints a version number, and that's the only proof I'd trust.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Choosing between latest and stable releases
The autoUpdatesChannel setting controls which channel auto-updates and claude update follow. "latest" is the default and gives you new features as soon as they're released. "stable" uses a version that's typically about one week old and skips releases with major regressions.
You can change it in /config under Auto-update channel, or add "autoUpdatesChannel": "stable" to your settings.json file. Homebrew picks its channel by cask name instead, and apt, dnf and apk pick it by repository.
Here's how I'd choose. If you're one person using Claude Code to build things and you like the new features, stay on latest. If Claude Code is part of a team's daily routine and a bad release would cost you a morning, stable is the calmer option. Just know the trade-off: a newly launched model can need a newer version than the stable channel serves, so if you want to try a new model on day one, you'll need to move to latest. Organisations can also enforce one channel for everyone through managed settings.
Setting a version floor
The minimumVersion setting sets a floor. Background updates and claude update refuse to install anything below it, which means moving to stable won't quietly downgrade you if you're already on a newer latest build.
If you switch from latest to stable in /config, it asks whether to stay on your current version or allow the downgrade. Choosing to stay sets minimumVersion for you, and switching back to latest clears it. To set it by hand, add both lines to settings.json, for example "autoUpdatesChannel": "stable", "minimumVersion": "2.1.100".
Switching automatic updates off
Set DISABLE_AUTOUPDATER to "1" inside the env key of your settings.json file. On a native or npm install, run claude doctor afterwards and check the Auto-updates line now says disabled rather than enabled.
That only stops the background check. claude update and claude install still work, so you can update by hand whenever you choose. If you need to block every update path, including manual ones, use DISABLE_UPDATES instead. That's meant for people who distribute Claude Code through their own channels and need everyone on the version they provide.
My honest view: most people shouldn't switch updates off. You'll fall behind on fixes without noticing, and half the odd behaviour people blame on Claude Code turns out to be an old version. If you do switch them off, put a regular reminder in your calendar to run the update yourself. Once you're current, my Claude Code best practices are the next thing worth reading.
Quick answers
How do I check which version of Claude Code I'm running?
Run claude --version in your terminal. A working installation prints its version number. If your shell says it can't find claude, the install folder isn't on your path.
Why didn't my Claude Code update show up?
Background updates on a native install take effect the next time you start Claude Code. Close your session, open a new one, then run claude doctor if it still looks old.
Should I use sudo to update Claude Code through npm?
No. Claude Code runs npm without sudo when it updates itself, so an install that needs sudo can't update automatically. Fix the folder permissions instead; claude doctor lists the options.
