Claude Code ships new versions almost every day. Updating gets you new features, support for new models and security fixes. How you update depends on how you installed it, and that is where most people get stuck.
This guide covers every way to update Claude Code:
- the native installer, which updates itself;
- npm, Homebrew and WinGet;
- apt, dnf and apk on Linux.
It also explains how to choose the stable or latest channel, pin or disable updates, and fix the common errors, such as “Auto-update failed”, an old version that will not go away, and npm permission problems.
All commands come from Anthropic’s official Claude Code setup and troubleshooting docs, checked on November 19, 2026. At that point the latest version on npm was 2.1.328 (released November 18) and the stable channel served 2.1.311.
- Quickest: run
claude updatein your terminal. It printsto version ...or “Claude Code is up to date”. - Check your version:
claude --version. For a health check:claude doctor. - Native install (the curl or PowerShell installer) updates itself in the background; the new version applies next time you start Claude Code.
- npm:
npm install -g @anthropic-ai/claude-code@latest(notnpm update -g). - Homebrew:
brew upgrade claude-code(orclaude-code@latest). WinGet:winget upgrade Anthropic.ClaudeCode. - Channels:
latest(default) orstable(about a week behind, skips bad releases). Set it in/config.
Step 1: Find Out How You Installed Claude Code
Run these in a terminal:
claude --version
claude doctor
claude doctor prints read-only diagnostics without starting a session: install health, the auto-update status, settings errors and suggested fixes. To see where the claude command lives:
# macOS / Linux / WSL
which -a claude
# Windows
where.exe claude
| Path you see | Install method |
|---|---|
~/.local/bin/claude or %USERPROFILE%\.local\bin\claude.exe |
Native installer (recommended) |
Inside an npm global folder (for example .../node_modules/.bin or AppData\Roaming\npm) |
npm |
/opt/homebrew/... or /usr/local/Caskroom/... |
Homebrew |
WinGet\Packages\Anthropic.ClaudeCode... |
WinGet |
/usr/bin/claude |
apt, dnf or apk package |
If you see more than one path, you have several installs fighting each other. Fix that first (see Troubleshooting).
Step 2: Update With claude update
- Close running Claude Code sessions (type
/exit). This matters most on Windows, where a running exe can be locked. - Run:
claude update - Read the result. A successful update prints a line ending with
to version <new version>. If you are current, you seeClaude Code is up to date (<version>). Homebrew, WinGet and apk installs reportClaude is up to date!. - Restart Claude Code and confirm with
claude --version.
For Homebrew and WinGet installs, claude update cannot replace the package itself. Use the package manager commands below.
Update Commands for Every Install Method
| Installed with | Auto-updates? | Update command |
|---|---|---|
| Native installer (curl / PowerShell / CMD) | Yes, in the background | claude update |
| npm | Yes, if the npm global folder is writable | npm install -g @anthropic-ai/claude-code@latest |
| Homebrew (stable cask) | No (opt-in available) | brew upgrade claude-code |
| Homebrew (latest cask) | No (opt-in available) | brew upgrade claude-code@latest |
| WinGet | No (opt-in available) | winget upgrade Anthropic.ClaudeCode |
| apt (Debian, Ubuntu) | No | sudo apt update && sudo apt upgrade claude-code |
| dnf (Fedora, RHEL) | No | sudo dnf upgrade claude-code |
| apk (Alpine) | No | apk update && apk upgrade claude-code |
npm: use install, not update
Anthropic’s docs warn against npm update -g, because it respects the version range from your original install and may not move you to the newest release. Always use:
npm install -g @anthropic-ai/claude-code@latest
The npm package needs Node.js 22 or later. Never use sudo npm install -g: an install that needs sudo cannot update itself later, and it causes permission problems.
Let Homebrew or WinGet update for you
Set the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. Claude Code then runs the upgrade command in the background when a new version is out and shows a restart prompt.
On WinGet the upgrade can fail while Claude Code is running because Windows locks the file; it then shows you the manual command. Homebrew keeps old versions, so run brew cleanup now and then.
How Auto-Updates Work
- Claude Code checks for updates when it starts and from time to time while running.
- Updates download and install in the background, then take effect the next time you start Claude Code.
- On macOS and Linux, the native installer keeps versions in
~/.local/share/claude/versions/and points the launcher~/.local/bin/claudeat the current one. It keeps the two newest versions and cleans up older ones. claude doctorshows the result of the last update attempt.
If you replaced ~/.local/bin/claude with your own script or symlink, updates still install, but your launcher decides which version runs. Remove your custom launcher and run claude update to hand control back.
Stable vs Latest Channel
| Channel | What you get | Best for |
|---|---|---|
latest (default) |
New versions as soon as they ship | Getting new features and new models on day one |
stable |
A version about one week old, skipping releases with major regressions | Work machines, teams, anyone who wants fewer surprises |
To switch, open Claude Code and run /config, then change Auto-update channel. Or add this to ~/.claude/settings.json:
{
"autoUpdatesChannel": "stable"
}
Two things to know. Switching a native install to stable can move you down to the older stable version. And a brand-new model can need a newer Claude Code than stable offers; switch to latest if you want to use it straight away.
Homebrew picks the channel by cask name (claude-code is stable, claude-code@latest is latest). The Linux apt, dnf and apk repositories pick it by repository URL. You can also install a channel directly:
# macOS / Linux / WSL: install the stable channel
curl -fsSL https://claude.ai/install.sh | bash -s stable
# Windows PowerShell
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable
Pin a Version or Turn Off Updates
Move to stable without downgrading
Set minimumVersion to the version you are on, together with the stable channel. Updates then refuse to install anything older:
{
"autoUpdatesChannel": "stable",
"minimumVersion": "2.1.328"
}
In /config, switching to stable offers the same “stay on your current version” option for you.
Turn off background updates
{
"env": {
"DISABLE_AUTOUPDATER": "1"
}
}
Confirm with claude doctor: the Auto-updates line should read disabled (set by env: DISABLE_AUTOUPDATER). This only stops the background check, so claude update still works. To block every update path (for example on managed machines), use DISABLE_UPDATES instead.
Want to know which settings file to edit and how settings layer? Our Claude Code commands cheat sheet lists the config commands, and the status line guide shows how to display your version at a glance.
Switch From npm to the Native Installer
The native installer is the recommended method because it updates itself reliably and does not depend on your Node.js setup. To switch:
- Remove the npm copy:
npm uninstall -g @anthropic-ai/claude-code - Install natively (your settings in
~/.claudeand your projectCLAUDE.mdfiles stay as they are):
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
- Open a new terminal and run
claude --versionandwhich -a claude(orwhere.exe claude) to confirm only the native copy remains.
Use the PowerShell line in PowerShell and the CMD line in Command Prompt. Mixing them up gives errors like 'irm' is not recognized or The token '&&' is not a valid statement separator.
VS Code, JetBrains and the Desktop App
- VS Code and forks: the Claude Code extension updates through the editor’s Extensions view like any other extension. Check for a pending update there and reload the window.
- JetBrains IDEs: update the plugin from Settings > Plugins. The plugin uses the
claudeCLI on your machine, so update that too. - Claude Desktop app: updates itself; restart the app when it asks.
- Claude Code on the web: nothing to update; Anthropic runs the latest version for you.
Troubleshooting Update Errors
| Problem | Cause | Fix |
|---|---|---|
Red Auto-update failed · Run claude doctor in the footer |
A background update did not install | Keep working; then run claude update in your shell to finish it or see the real error |
| Version does not change after updating | Two installs; an older one comes first on PATH | Run which -a claude / where.exe claude, keep the native one, uninstall the rest |
| npm permission error (EACCES) | npm global folder not writable, or installed with sudo | Switch to the native installer, or fix npm’s prefix; never use sudo |
Homebrew: No Cask with this name exists |
Old Homebrew data | Run brew update first, then upgrade |
Homebrew: Cask 'claude-code@latest' is not installed |
You installed the other cask | Upgrade the cask you have: brew upgrade claude-code |
| WinGet upgrade fails | Windows locks the running exe | Close all Claude Code windows, then rerun winget upgrade Anthropic.ClaudeCode |
| Update says new version but package manager has none | Known lag in package repositories | Wait a few hours and try again |
Release verification failed |
The release could not be verified, so nothing was installed | Run claude update again; your current version keeps working |
| Download drops behind a company proxy | Proxy or custom CA | Set NODE_EXTRA_CA_CERTS (and CURL_CA_BUNDLE for the installer) to your proxy’s CA file |
| Stuck on an old version on purpose? | DISABLE_UPDATES, minimumVersion or managed settings |
Check claude doctor and your settings files |
After an update, new features often appear as slash commands or settings. Our guides to Claude Code hooks and CLAUDE.md files cover the parts that change most often, and the Claude Code pricing guide explains plan limits.
FAQ
How do I update Claude Code?
Run claude update. For Homebrew use brew upgrade claude-code, for WinGet winget upgrade Anthropic.ClaudeCode, and for npm npm install -g @anthropic-ai/claude-code@latest.
Does Claude Code update automatically?
Yes for native and most npm installs. Homebrew, WinGet and Linux package installs do not, unless you opt in with CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 (Homebrew and WinGet only).
How do I check my Claude Code version?
Run claude --version in a terminal, or claude doctor for more detail.
What is the latest version of Claude Code?
On November 19, 2026 it was 2.1.328 on the latest channel and 2.1.311 on stable. New versions arrive very often, so claude update is the easiest way to get current.
Will updating delete my settings or chats?
No. Your settings in ~/.claude, project settings and CLAUDE.md files are kept across updates.
Can I go back to an older version?
Yes. The native installer accepts a version number, for example curl -fsSL https://claude.ai/install.sh | bash -s 2.1.311. Disable auto-updates afterwards or it will move forward again.
Should I use the stable or latest channel?
Latest if you want new features and models first. Stable if you prefer a version that has had about a week of real-world testing.



