Claude Code upgrade procedures

Reference Updated 2026-10-12

A safe Claude Code upgrade follows one sequence: choose a release channel (latest or stable), record the current version, read the changelog for everything in between, back up ~/.claude, ~/.claude.json and the project’s .claude/ and .mcp.json, update with the command for your install type, then verify with a scripted smoke test and keep a rollback command ready.

This page is for developers who own their own install and for tech leads who keep a team on one version. The problem it solves looks like this: you open a terminal on Monday, the background updater installed a new build over the weekend, and your session now starts in a different permission mode, runs a different default model, and one MCP server no longer connects. Nothing announced it. Your teammate, on Homebrew, is still a week behind you.

What a controlled Claude Code upgrade gives you

A release-channel decision (latest or stable) and the settings that enforce it for one person or a whole team.
The exact update and rollback command for each install type: native, Homebrew, WinGet, apt/dnf/apk, and npm.
A list of what recent versions changed without asking, so you know what to check.
A smoke-test script and two copy-paste prompts that prove the upgrade worked without you reading the changelog line by line.
Recovery steps for the failures that actually happen: the updater undoing your rollback, two installs on PATH, and MCP servers that stop connecting.

Which Claude Code install do you have, and how does it update?

Run claude doctor first. It prints read-only installation and settings diagnostics without starting a session, including the install type, the result of the last update attempt, and settings-file validation errors. The install type decides everything that follows.

Install type	Updates itself?	Update command	Install or roll back to a version
Native installer (recommended)	Yes, in the background; the new version takes effect on the next start	`claude update`	`claude install 2.1.274`, or `claude install stable`
Homebrew	No (opt in with `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1`)	`brew upgrade claude-code` (stable cask) or `brew upgrade claude-code@latest`	Switch between the `claude-code` (stable) and `claude-code@latest` casks
WinGet	No (same opt-in)	`winget upgrade Anthropic.ClaudeCode`	For an exact version, move to the native installer
apt / dnf / apk	No; upgrades need elevated privileges	`sudo apt update && sudo apt upgrade claude-code`, `sudo dnf upgrade claude-code`, `apk update && apk upgrade claude-code` (Alpine, as root)	Point the repository at the `stable` or `latest` channel
npm (`@anthropic-ai/claude-code`, Node.js 22+)	Yes, if the npm global directory is writable	`npm install -g @anthropic-ai/claude-code@latest`	`npm install -g @anthropic-ai/claude-code@2.1.274`, or `@stable`

Two details from the official setup guide catch people out. Avoid npm update -g: it respects the semver range of the original install and may not reach the newest release. And never use sudo npm install -g; fix the npm prefix or switch to the native installer instead.

Should you follow the latest or the stable release channel?

Claude Code ships roughly one release a day on the latest channel. The stable channel runs about a week behind latest and skips releases with major regressions, according to the setup guide. On 2026-10-12 latest is v2.1.296 and stable is v2.1.287 (npm dist-tags; the native installer’s channel pointers and the Homebrew casks agree, checked that day). On 2026-09-26 they were v2.1.283 and v2.1.274.

You are…	Channel	Why
A developer who wants new features as they ship	`latest` (the default for native and npm installs)	You get fixes first and can report regressions early
A team of five or more that needs everyone on the same behaviour	`stable` for the team, `latest` for one or two volunteers	The volunteers act as the canary for the rest of the team
A regulated team that approves each version	`stable` plus a version ceiling in managed settings	Nothing runs outside the approved range

Set the channel in /config → Auto-update channel, or in settings.json. Homebrew picks the channel by cask name instead: claude-code tracks stable, and claude-code@latest tracks latest.

A newly launched model can need a Claude Code version newer than stable serves, and Anthropic’s setup guide says to move to the latest channel to run it now. On 2026-10-12 that applies to Claude Haiku 5.5, which needs v2.1.293.

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

minimumVersion is a floor for updates, so moving from latest to stable does not downgrade you. Four more controls exist, and they do different things:

Control	Where	Effect
`DISABLE_AUTOUPDATER=1`	`env` block of `settings.json`	Stops the background check only; `claude update` and `claude install` still work
`DISABLE_UPDATES=1`	environment	Blocks every update path, including manual ones; for teams that distribute Claude Code themselves
`requiredMinimumVersion`	managed settings	Claude Code refuses to start below this version
`requiredMaximumVersion`	managed settings	Claude Code refuses to start above it, and updates respect it as a ceiling

For how managed settings reach every machine, see managed policy for coding agents.

What can a Claude Code upgrade change without asking?

Most releases are bug fixes. Some change behaviour that your hooks, scripts and habits depend on. These are the recent ones from the Claude Code changelog; the version history has the full list. On 2026-10-12 stable is v2.1.287, so the rows up to v2.1.287 are on both channels and the rows from v2.1.288 are on latest only. On 2026-09-26 every row from v2.1.277 up was on latest only.

Version	What changed	What to check afterwards
v2.1.222	`/ultraplan` removed from the command reference	Use plan mode (`/plan`) in scripts and docs
v2.1.274	MCP 2026-07-28 protocol negotiation with direct HTTP servers reached every install, including Bedrock, Google Cloud, Foundry and telemetry-off installs	Run `claude mcp list`; an older HTTP server may need `MCP_PROTOCOL_NEGOTIATION=legacy`
v2.1.277	Claude Code reads `AGENTS.md` when a project has no `CLAUDE.md` (v2.1.281 extended it to Bedrock, Google Cloud, Foundry and gateways)	Repositories with only `AGENTS.md` now load those instructions; toggle under “Project instructions” in `/config`
v2.1.280	Claude Opus 5.5 became the default model on every paid plan and the Anthropic API (on both channels since `stable` reached v2.1.287)	Your cost and latency profile moves; see the models hub
v2.1.283	Auto mode became the starting permission mode for interactive terminal and VS Code sessions on every plan and provider	Sessions that used to stop and ask now let a classifier approve actions; `claude -p`, the Agent SDK and sessions on a model auto mode does not support (for example Haiku) still start in Manual, as do sessions where a settings file sets `permissions.disableAutoMode`. Since v2.1.285 the `-p` exception does not apply on third-party providers or with telemetry off, and Haiku 5.5 supports auto mode (Haiku 4.5 does not)
v2.1.284	The `sonnet` alias on the Anthropic API became Claude Sonnet 5.5; ultracode became its own toggle that no longer forces `xhigh`	Pin `--model` where a job relied on the earlier Sonnet; set the effort level separately from ultracode
v2.1.285	`claude -p` and Python Agent SDK sessions on third-party providers or with telemetry off start in auto mode; background Bash and PowerShell commands stop when their `timeout` runs out (default 30 minutes)	Pass `--permission-mode` in unattended jobs; raise the `timeout` of long-running background commands
v2.1.286	`--bare` connects only the MCP servers named on the command line	Name each MCP server a scripted call needs
v2.1.287	Opus 4.7 and later and Fable default to a 1M window on Bedrock, Google Cloud, Foundry and the Claude apps gateway; Claude Code handles URL prompts from servers on the 2025-11-25 MCP protocol	Set `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` to keep 200K; run `claude mcp list`, and if a server stopped connecting, read the changelog entry about `bareElicitationCapability`
v2.1.288 (`latest` only)	`claude project purge` became `claude purge`; the old name still works and prints a notice	Update scripts to `claude purge`
v2.1.292 (`latest` only)	Local (stdio) MCP servers negotiate protocol 2026-07-28 by default on every install	Run `claude mcp list`; `MCP_PROTOCOL_NEGOTIATION=legacy` opts out
v2.1.293 (`latest` only)	The `haiku` alias on the Anthropic API became Claude Haiku 5.5	Jobs that call the `haiku` alias now run a different model; re-run their evals
v2.1.296 (`latest` only)	Cost figures price Sonnet 5.5 cache reads at the lower rate	Recalibrate `--max-budget-usd` caps and cost alerts

A model change is its own migration with its own evals. Follow the new-model playbook for that part; this page covers the tool.

Upgrade Claude Code in five steps

Record where you are. Save the version and the diagnostics so you have something to compare against and a version to roll back to.
Terminal window
```
claude --version | tee ~/claude-upgrade-before.txt
claude doctor >> ~/claude-upgrade-before.txt
```

Read the changelog for every version in between. The Claude Code changelog lists each release. Let the agent read it for you and extract only what touches your setup.

I'm upgrading Claude Code from the version in ~/claude-upgrade-before.txt to the
current latest release. Fetch https://code.claude.com/docs/en/changelog and read
every entry between those two versions. Then read my ~/.claude/settings.json,
.claude/settings.json, .mcp.json and the hooks and skills under .claude/.
Produce a table with one row per change that affects THIS setup: version,
what changed, which of my files or habits it touches, and the exact action I
need to take (or "none"). Flag separately: default model changes, permission-mode
changes, removed or renamed commands and flags, hook event or field changes, and
MCP transport or protocol changes. Do not edit any file.

Back up the files an upgrade or a rollback can touch. User settings live in ~/.claude/, user-scoped MCP servers and state in ~/.claude.json, and project settings in .claude/ and .mcp.json.
Terminal window
```
STAMP=$(date +%Y%m%d)
tar -czf ~/claude-config-$STAMP.tgz -C ~ .claude .claude.json
tar -czf ./claude-project-$STAMP.tgz .claude .mcp.json 2>/dev/null || true
```
The project archive is a local safety net; .claude/ and .mcp.json should also be committed to Git.
Update with the command for your install type.
Terminal window
claude update # newest version on your channel claude install stable # or move to the stable channel's version claude install 2.1.296 # or an exact version
Terminal window
brew upgrade claude-code # stable cask brew upgrade claude-code@latest # latest cask brew cleanup # Homebrew keeps old versions on disk
Terminal window
npm install -g @anthropic-ai/claude-code@latest # or @stable, or @2.1.296
Terminal window
sudo apt update && sudo apt upgrade claude-code # Debian, Ubuntu sudo dnf upgrade claude-code # Fedora, RHEL apk update && apk upgrade claude-code # Alpine (as root)
Restart everything that runs the old binary, then verify. claude update reports Successfully updated from <old version> to version <new version>, or Claude Code is up to date (<version>) when there was nothing to install. A new version takes effect the next time Claude Code starts. Background sessions keep the old binary until you restart them with claude respawn --all. Then run the smoke test in the next section.

How do you verify a Claude Code upgrade without reading every change?

You prove the upgrade with checks that run the same way on every machine, not by re-reading the changelog. The script exits non-zero when an MCP server fails to connect or needs authentication, or when the model call breaks. Save this script as scripts/claude-smoke.sh in the repository so every developer and every canary machine runs the same checks. The script needs jq on PATH.

#!/usr/bin/env bash
# Post-upgrade smoke test for Claude Code. Run from the project root.
set -euo pipefail

echo "== version";  claude --version
echo "== doctor";   claude doctor
echo "== plugins";  claude plugin list

echo "== mcp"
mcp_out=$(claude mcp list)
echo "$mcp_out"
if grep -qE '✗|Failed to connect|Needs authentication' <<<"$mcp_out"; then
  echo "MCP check failed"; exit 1
fi
if grep -qi 'pending approval' <<<"$mcp_out"; then
  echo "WARNING: an MCP server is waiting for approval"
fi

echo "== headless round trip"
answer=$(claude -p "Reply with exactly the word READY and nothing else." \
  --output-format json | jq -r '.result')
[ "$answer" = "READY" ] || { echo "Headless check failed: $answer"; exit 1; }
echo "OK"

One section still needs a human glance: claude doctor must show no settings-file validation errors, and the script prints that section without judging it. The MCP check stops the script on a server that failed to connect or needs authentication, for example after an OAuth token expired. A server marked ⏸ Pending approval only raises a warning: it is a project .mcp.json entry that nobody has approved yet on this machine, and Claude Code does not connect to it until someone does. The headless round trip proves authentication and the model call work. It starts in Manual mode, except on third-party providers or with telemetry off, where claude -p starts in auto mode from v2.1.285.

Behaviour that a script cannot see, such as hooks firing and skills resolving, needs a real session. Run the prompt below in your main project right after upgrading.

I just upgraded Claude Code. Without changing any tracked file, check that my setup
still behaves as before:
1. Tell me which model and permission mode this session started in.
2. List the hooks configured in ~/.claude/settings.json and .claude/settings.json.
   For each PreToolUse or PostToolUse hook, trigger it once with a harmless action
   (for example, read README.md or create and delete a file under /tmp) and tell me
   whether it fired, with its output.
3. List the skills and subagents under .claude/ and confirm each one loads.
4. Report every difference from a normal session as a table: symptom, likely cause,
   smallest fix. If a fix needs a settings change, show the JSON but do not apply it.

For a team, the sign-off is explicit. The canary developers on latest run the script and the prompt on the day a release lands. The tech lead raises requiredMinimumVersion (and, for regulated teams, requiredMaximumVersion) in managed settings only after the canaries report a clean run on a version that has also reached stable. The per-user minimumVersion from the channel switch above does not do this: it only stops one machine from downgrading. Record each decision in the team’s upgrade log: version, date, who ran the checks, and what failed.

How do you roll back a Claude Code upgrade?

Roll back first and diagnose afterwards when an upgrade blocks work. Stop all running Claude Code sessions (claude agents opens agent view, a research preview, where background sessions are listed). If a minimumVersion above your target is set, lower it first: it is a floor that exists to stop downgrades. Then use the command for your install type:

claude install 2.1.274

Then stop the background updater from reinstalling the broken version: add "DISABLE_AUTOUPDATER": "1" to the env block of ~/.claude/settings.json. claude doctor confirms it with Auto-updates: disabled (set by env: DISABLE_AUTOUPDATER). Remove the setting once a fixed release ships.

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

Set DISABLE_AUTOUPDATER as for native installs, because an npm install with a writable global directory also updates itself.

brew uninstall --cask claude-code@latest
brew install --cask claude-code

Moving from the latest cask to the stable cask is the practical rollback on Homebrew.

If configuration broke too, restore it from the step 3 archive:

tar -xzf ~/claude-config-YYYYMMDD.tgz -C ~

Replace YYYYMMDD with the date of the archive. Then run scripts/claude-smoke.sh again, and file a GitHub issue on anthropics/claude-code with the claude doctor output from before and after.

When a Claude Code upgrade breaks

Your rollback keeps undoing itself. The background updater reinstalls the newest version on the next start. Set DISABLE_AUTOUPDATER (one machine) or requiredMaximumVersion in managed settings (a team) until the fix ships.

claude --version shows the old version after an update. Two installs are on your PATH, often an old npm install shadowing the native one. Run which -a claude and claude doctor, remove the one you do not use (npm uninstall -g @anthropic-ai/claude-code), and open a new shell.

Updates stop arriving on a native install. A custom script or symlink at ~/.local/bin/claude decides which version runs, and claude update leaves it alone. claude doctor reports a launcher the installer did not create. Remove ~/.local/bin/claude and run claude update to hand control back.

An npm install cannot update. The npm global directory is not writable. Claude Code shows a one-time notice and claude doctor lists the fixes. Change the npm prefix or move to the native installer; do not reach for sudo.

An MCP server stopped connecting. Check claude mcp list first; ⏸ Pending approval means the server needs approval through /mcp, not a fix. If the server is a direct HTTP server that predates the 2026-07-28 protocol, set MCP_PROTOCOL_NEGOTIATION=legacy for that machine and ask the server’s maintainer for an update. From v2.1.292 (latest only on 2026-10-12) local (stdio) servers negotiate the same protocol, and a server on the 2025-11-25 protocol that stopped connecting after v2.1.287 may need "bareElicitationCapability": true, as the changelog’s 2.1.287 entry says. Setup details are in MCP setup for Claude Code.

Sessions now run without asking. From v2.1.283 (on both channels since stable reached v2.1.287), auto mode is the starting permission mode, and since v2.1.285 claude -p starts in auto mode on third-party providers or with telemetry off. If your team needs Manual approval, set permissions.disableAutoMode to "disable" in managed settings; auto mode set in project settings is ignored by design.

Costs or latency moved after the upgrade. The default model changed in v2.1.280 (on both channels since stable reached v2.1.287; stable v2.1.274 still had the older default on 2026-09-26), the sonnet alias moved to Sonnet 5.5 in v2.1.284, and the haiku alias moved to Haiku 5.5 in v2.1.293 (latest only). Check the session model with /model, pin the model your evals approved with the model setting, and run the comparison in the new-model playbook.

Homebrew or WinGet says an update exists but cannot install it. Claude Code can announce a version before the package manager has it. Wait and retry. On WinGet, the upgrade can also fail while Claude Code is running because Windows locks the executable.

For errors not tied to an upgrade, see Claude Code troubleshooting.

Where to go next after upgrading Claude Code

Claude Code changelog: what shipped in each version, with our notes.
Beta features and early access: research-preview features a new version may unlock.
Keeping a team current with agent tools: the team habit around releases, not only the commands.
Enterprise integration for Claude Code: distributing managed settings and approved versions across an organization.
Installing Claude Code: the prerequisite, if you are choosing an install type for the first time.