Skip to content
,

How to Update Claude Code (2026): claude update, npm, Homebrew, WinGet and Fixes

8–11 minutes
Laughing woman in a white coat and orange top holding a card with the Claude logo at a tech conference, with the text Update Claude Code in 10 Seconds

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.

TL;DR

  • Quickest: run claude update in your terminal. It prints to 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 (not npm update -g).
  • Homebrew: brew upgrade claude-code (or claude-code@latest). WinGet: winget upgrade Anthropic.ClaudeCode.
  • Channels: latest (default) or stable (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

  1. Close running Claude Code sessions (type /exit). This matters most on Windows, where a running exe can be locked.
  2. Run: claude update
  3. Read the result. A successful update prints a line ending with to version <new version>. If you are current, you see Claude Code is up to date (<version>). Homebrew, WinGet and apk installs report Claude is up to date!.
  4. 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/claude at the current one. It keeps the two newest versions and cleans up older ones.
  • claude doctor shows 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:

  1. Remove the npm copy: npm uninstall -g @anthropic-ai/claude-code
  2. Install natively (your settings in ~/.claude and your project CLAUDE.md files 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
  1. Open a new terminal and run claude --version and which -a claude (or where.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 claude CLI 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.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Laughing woman in a white coat and orange top holding a card with the Claude logo at a tech conference, with the text Update Claude Code in 10 Seconds