How to Update Claude Code (and Fix Update Errors)

Update Claude Code with claude update if you used the native installer, which also updates itself in the background. If you installed with npm, run npm install -g @anthropic-ai/claude-code@latest, and never npm update -g. Homebrew, WinGet and Linux package installs don't auto-update, so upgrade them with their own package manager.

Update commands by install method

The native installer covers macOS, Linux, WSL and Windows. "Opt-in" means Claude Code can run the package manager's upgrade for you in the background, as covered in the auto-update section below.

Check your version and install type

claude --version
claude doctor

claude --version prints the installed version. claude doctor is a read-only health check that runs without starting a session. It reports:

• installation health;
• update status;
• settings-file validation;
• any warnings.

Inside a session, /doctor runs the same kind of setup diagnostics.

To see which binary you are actually running, list every claude on your PATH:

which -a claude

On Windows, use where.exe claude. The path tells you the install type:

More than one line of output means you have duplicate installs. The fixes are covered further down.

claude update vs npm install -g

Both commands exist, and the right one depends on your install:

• Native install: claude update downloads and applies the update immediately, instead of waiting for the background check.
• npm install: the documented update is npm install -g @anthropic-ai/claude-code@latest. claude update also works on an npm install.
• Never use npm update -g. It respects the semver range from your original install and can silently leave you on a stale version.

As of September 2026, the npm path needs Node.js 22 or later, and it is also the path that collects permission errors. Unless you need Claude Code pinned alongside other global npm tooling, move to the native installer. It has no dependencies and keeps itself current.

How auto-updates work

Native installs check for updates in the background, download them, and apply them the next time you start Claude Code. npm global installs update themselves the same way when npm's global directory is writable. Package-manager installs don't unless you opt in.

Release channels

Change the channel in /config under Auto-update channel, or in settings.json:

{ "autoUpdatesChannel": "stable" }

Homebrew picks the channel by cask instead of by setting. claude-code tracks stable and claude-code@latest tracks latest.

Version floors and admin limits

minimumVersion sets a floor. Auto-updates and claude update refuse any version below it. The docs pair it with the stable channel. The version number below is the docs' example value, not a recommendation:

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

When you switch from latest to stable in /config, Claude Code offers to keep you on your current version and sets minimumVersion for you. Organizations can enforce requiredMinimumVersion and requiredMaximumVersion through managed settings, and user or project settings can't override those.

Package-manager auto-updates

Homebrew and WinGet can update in the background too. Set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 in your environment, or in the env block of settings.json, and Claude Code runs the package manager's upgrade for you. apt, dnf and apk installs never auto-update. Updates arrive through your normal system upgrade and still need elevated privileges.

Turn auto-updates off

Add this to settings.json:

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

This stops only the background check; claude update and claude install still work when you run them. To block every update path, manual ones included, set DISABLE_UPDATES=1 instead. That suits locked-down machines where updates come from IT.

Update each install type

Native installer

claude update

The installer manages ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. claude update installs the new version there and applies it immediately.

npm

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

Don't prefix this with sudo. A root-owned global install leaves files in the npm prefix that break future installs. The fix for EACCES is in the errors section below.

Homebrew

brew upgrade claude-code
brew upgrade claude-code@latest

Run the line that matches the cask you installed: claude-code for stable, claude-code@latest for the latest channel.

WinGet

winget upgrade Anthropic.ClaudeCode

Close Claude Code first. Windows locks the running executable, so an upgrade can fail while a session is open.

apt, dnf and apk

sudo apt update && sudo apt upgrade claude-code
sudo dnf upgrade claude-code
apk update && apk upgrade claude-code

These go through your system's package manager, not through Claude Code.

Move from npm to the native installer

The setup docs don't provide a one-step migration command. The path is to uninstall the npm copy, install natively, and check that only one claude remains:

npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bash

On Windows, install with PowerShell instead:

irm https://claude.ai/install.ps1 | iex

Then run which -a claude again; it should list only ~/.local/bin/claude. If an older version left a ~/.claude/local/ directory, remove it:

rm -rf ~/.claude/local

If your shell now says claude isn't found, add ~/.local/bin to your PATH using the fix in the errors section. For a fresh machine, Installing Claude Code walks through the whole setup.

Pin a version or roll back

The native installer accepts a version or a channel. In this example, 2.1.89 is the docs' sample value; swap in the version you need:

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89
curl -fsSL https://claude.ai/install.sh | bash -s stable

On npm, add the version to the package name with standard npm syntax: npm install -g @anthropic-ai/claude-code@<version>.

As of September 2026, the docs don't describe a dedicated rollback command. To go back, reinstall the version you want with the installer's version argument. If you want to stay there, set DISABLE_AUTOUPDATER afterwards.

For finer control, replace ~/.local/bin/claude with your own launcher script or symlink. Updates still land under ~/.local/share/claude/versions/, but your launcher decides which version runs. Fleets should pin through requiredMinimumVersion and requiredMaximumVersion in managed settings instead.

Fix update errors

npm left you on an old version

You probably ran npm update -g. Rerun the update with the explicit tag:

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

EACCES or permission errors with npm

Don't reach for sudo npm install -g. You have three fixes:

• Point npm at a user-writable prefix with npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH.
• Install Node through nvm, which avoids the problem entirely.
• Switch to the native installer, the simplest fix of the three.

"command not found: claude" after switching installs

The native binary lives in ~/.local/bin, and that directory isn't on your PATH. For zsh, the macOS default:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

For bash on Linux:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

For Windows PowerShell, then restart the terminal:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

The wrong version runs after an update

There are three likely causes:

• Duplicate installs. which -a claude (or where.exe claude) lists every copy. Remove the ones you don't want.
• No restart. A background update applies on the next startup, so restart the session.
• A custom launcher. If you replaced ~/.local/bin/claude yourself, it may point at an old version. Remove it and let Claude Code manage the link again:

rm ~/.local/bin/claude
claude update

To remove duplicate installs, use the line for each copy you don't want:

rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude   # native (macOS/Linux)
npm uninstall -g @anthropic-ai/claude-code                  # npm global
rm -rf ~/.claude/local                                      # legacy local npm
brew uninstall --cask claude-code                           # Homebrew
winget uninstall Anthropic.ClaudeCode                       # WinGet

WinGet upgrade fails

Windows locks the executable while Claude Code runs. Exit every session, then rerun winget upgrade Anthropic.ClaudeCode.

Updates refuse to run

Check three settings:

• DISABLE_UPDATES blocks every update path, including claude update.
• minimumVersion makes the updater refuse anything below it.
• requiredMaximumVersion, on managed machines, caps the version and can't be overridden locally.

claude doctor validates your settings files and reports update status, so run it before editing anything.

Homebrew or Linux packages never update

This is expected. They don't auto-update by default. Run the package manager's upgrade from the table at the top, or, for Homebrew and WinGet, set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.

For problems beyond updating, such as auth, context limits or MCP servers, see Claude Code troubleshooting.

See what changed

Anthropic publishes release notes in the Claude Code changelog. Claude Code ships frequently, so compare the changelog against your claude --version rather than trusting a version number quoted in a blog post, including this one. If new releases keep disrupting your work, switch to the stable channel, which skips releases with major regressions.

Next steps

Once you're current:

• 25 Claude Code tips covers the shortcuts and power features worth learning next.
• Claude Code slash commands explains /config, /doctor and the rest of the built-ins.
• Adding MCP servers helps when /doctor flags your MCP servers.
• Running Claude Code in CI covers automation. There, pin the version with the installer's version argument so an update doesn't change behavior mid-pipeline.