How to update Claude Code: auto-updates, claude update, release channels and pinning

To update Claude Code, run claude update in your terminal. If you installed with the native installer, you usually don't need to: it checks for updates on startup and while running, installs them in the background, and the new version takes effect the next time you start claude. Homebrew, WinGet, npm and Linux package manager installs update through their own commands instead.

This guide covers each install method, release channels, pinning and disabling updates, fixing failed updates, and uninstalling. It is based on Anthropic's advanced setup page and settings reference, read on 26 October 2026.

How do you update Claude Code on each install method?

First, find out how you installed it. Run which -a claude on macOS or Linux, or where.exe claude on Windows. A native install lives at ~/.local/bin/claude, a symlink into ~/.local/share/claude/versions/.

A few notes from the docs:

• Homebrew and WinGet opt-in. Set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 and Claude Code runs the upgrade for you in the background, then shows a restart prompt. On WinGet the upgrade can fail while Claude Code is running because Windows locks the executable.
• Package manager lag. The docs list a known issue: Claude Code "may notify you of updates before the new version is available in these package managers." If an upgrade fails, wait and try again.
• Homebrew disk space. Homebrew keeps old versions after upgrades. Run brew cleanup now and then.
• npm. Avoid npm update -g, which "respects the semver range from the original install and may not move you to the newest release." Never use sudo npm install -g.

What does claude update do?

claude update applies an update immediately instead of waiting for the next background check. When it installs something, it prints Successfully updated from <old version> to version <new version>. If you're current, it prints Claude Code is up to date (<version>). Installs managed by Homebrew, WinGet or apk report Claude is up to date! instead.

To check your version afterwards:

claude --version     # prints something like 2.1.211 (Claude Code)
claude doctor        # install health, settings errors, last update attempt

Inside a session, /status shows the version and /release-notes opens the changelog in an interactive version picker. If you mistype the subcommand, Claude Code suggests the fix: claude udpate prints Did you mean claude update?.

Which release channel should you use?

The autoUpdatesChannel setting controls which channel auto-updates and claude update follow:

• "latest", the default: "receive new features as soon as they're released"
• "stable": "use a version that is typically about one week old, skipping releases with major regressions"

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

{
  "autoUpdatesChannel": "stable"
}

One trade-off to know: "A newly launched model can require a Claude Code version newer than the stable channel serves." If you want a new model on launch day, move to latest.

Homebrew ignores this setting and picks the channel by cask: claude-code tracks stable and claude-code@latest tracks latest. The apt, dnf and apk repositories pick it by repository URL, with stable and latest variants.

How do you pin or roll back a Claude Code version?

There are three tools, each for a different job.

Install a specific version. The native installer accepts a version number or channel:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# or, with Claude Code already installed
claude install 2.1.118
claude install stable

On Windows PowerShell, the docs use & ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.89. The channel you choose at install time becomes your default for auto-updates.

Anthropic's docs don't give a single "freeze on this version" recipe, so here is Kipt's suggested combination of the documented pieces: install the exact version as above, then set DISABLE_AUTOUPDATER as described below. Without it, the next background update moves you to the newest release on your channel.

Set a floor with minimumVersion. Updates refuse to install anything below this value, so switching from latest to stable doesn't downgrade you:

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

When you switch to stable in /config and choose to stay on your current version, Claude Code sets minimumVersion for you.

Enforce a range for an organization. minimumVersion only constrains updates. To make Claude Code refuse to start outside a version range, admins use requiredMinimumVersion and requiredMaximumVersion in managed settings. See the enterprise guide for how managed settings are delivered.

How do you turn off Claude Code auto-updates?

Set DISABLE_AUTOUPDATER in the env block of your settings file:

{
  "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 and claude install still work. To block every update path, set DISABLE_UPDATES=1. Anthropic recommends it "when you distribute Claude Code through your own channels and need users to stay on the version you provide." Also note that CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns off auto-updates along with telemetry and other nonessential traffic, according to the environment variables reference.

How do you move from npm to the native installer?

Anthropic recommends the native install, and it updates itself in the background. The docs don't publish a dedicated migration guide, so these are Kipt's suggested steps, built from the documented install command and the conflicting installations advice to keep only one install. Install the native version, then remove the npm package:

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

Open a new terminal and run which -a claude to confirm only ~/.local/bin/claude is listed. Older versions of Claude Code could also create a legacy local npm install in ~/.claude/local/; the same troubleshooting page says to remove it with rm -rf ~/.claude/local. Multiple installations "can cause version mismatches or unexpected behavior."

What if a Claude Code update fails?

If you replaced ~/.local/bin/claude with your own script or symlink, auto-update leaves it alone and keeps every version on disk. To hand control back, remove ~/.local/bin/claude and run claude update. Network problems during updates are covered in the proxy settings guide, and other errors in the troubleshooting guide.

How do you uninstall Claude Code?

Use the command for your install method:

# Native (macOS, Linux, WSL)
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Homebrew (use claude-code@latest if that's the cask you installed)
brew uninstall --cask claude-code

# npm
npm uninstall -g @anthropic-ai/claude-code

On Windows, remove a native install with Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force and Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force, or a WinGet install with winget uninstall Anthropic.ClaudeCode. The apt, dnf and apk instructions also remove the repository configuration they added.

To remove settings too, delete ~/.claude and ~/.claude.json, plus .claude and .mcp.json in each project. The docs warn this deletes "all your settings, allowed tools, MCP server configurations, and session history," and that the VS Code extension, JetBrains plugin and Desktop app recreate ~/.claude/ if they're still installed. Uninstall those first for a complete removal.

Keep your setup portable

Updating is easy; rebuilding your setup on a new machine takes longer. Your Agent Skills and prompts don't live inside the Claude Code binary, so keep them somewhere you control. Kipt stores them as Markdown in a private GitHub repo you own, and npx skills add https://github.com/<you>/<repo>.git --all -g installs every skill into Claude Code on a fresh install. For a first-time install walkthrough, see the Claude Code setup guide.