Claude Code Upgrade Procedures

You start the morning, run claude to pick up yesterday’s branch, and a background auto-update has just landed a new minor version. Your pre-commit hook errors out, an MCP server won’t connect, and your team is hitting three different builds. Upgrades are routine until one breaks mid-sprint — this guide makes them boring again, across npm, native, and enterprise-pinned installs.

What You’ll Walk Away With

• A pre-upgrade checklist that backs up the configs an upgrade can actually clobber.
• The correct upgrade and rollback commands for each install type (native, npm, enterprise-pinned).
• A reusable prompt that turns the changelog into a personalized migration plan.
• A verification routine that catches a broken hook or MCP server before your team does.

Claude Sonnet 5 (June 2026)

Sonnet 5 is the default on Pro and standard seats

Claude Sonnet 5 (claude-sonnet-5, released 2026-06-30) became the account default for Pro, Team Standard, and Enterprise subscription seats in v2.1.197. Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API sessions default to Opus 5, and an organization default can override either mapping. As of v2.1.219, Amazon Bedrock, Google Cloud’s Agent Platform, and Claude Platform on AWS also default to Opus 5; Microsoft Foundry remains on Sonnet 4.5 and still resolves the opus alias to Opus 4.6 unless you override it. Sonnet 5 has native 1M context and introductory API pricing of $2/$10 per MTok through August 31, then $3/$15.

Claude Opus 5 Migration (July 2026)

Claude Opus 5 (claude-opus-5, released 2026-07-24) is the current Opus and the account default on Max, Team Premium, Enterprise pay-as-you-go, Anthropic API, and the managed clouds. It requires Claude Code v2.1.219 or later, and it is priced identically to Opus 4.8 at $5 / $25 per MTok — so for Claude Code users the upgrade is a version bump, not a cost decision.

Two breaking changes if you call the API directly

Neither affects Claude Code sessions, but both will break a pinned API integration moving from Opus 4.8:

1. Thinking is on by default. Omitting the thinking parameter meant no thinking on Opus 4.8; on Opus 5 it runs adaptive thinking. Because max_tokens caps thinking plus response text, a request sized tightly around its answer can now truncate mid-response. Raise max_tokens, or opt out explicitly.
2. Disabling thinking is capped at high effort. thinking: {"type": "disabled"} combined with xhigh or max returns a 400, validated per request — so a later call that raises effort while thinking is still disabled fails even though earlier calls succeeded. Prefer leaving thinking on and lowering effort instead.

Everything else carries over from Opus 4.7/4.8 unchanged: temperature/top_p/top_k are still rejected, budget_tokens still returns a 400, last-assistant-turn prefills still fail, and thinking.display still defaults to "omitted".

Three other differences worth knowing. Opus 5 draws on a separate rate-limit pool from the combined Opus 4.x models, so shifting traffic neither frees nor inherits headroom. It does not support Priority Tier, which Opus 4.8 does. And the minimum cacheable prompt drops to 512 tokens from 1024, so prompts you had written off as uncacheable may now cache with no code change.

Prompting changes to make. Opus 5 verifies its own work without being asked, so delete verification instructions and harness verification steps rather than rewriting them — keeping them causes over-verification. It writes longer responses and longer files by default, and effort is not the lever that shortens them; ask for concision explicitly. It can also widen a task’s scope, so state the boundary when you want exactly what you asked for.

Claude Opus 4.8 (May 2026)

Opus 4.8 is superseded by Opus 5 at the same price, but it is not deprecated and remains worth knowing about: it still serves pinned production traffic, it still supports Priority Tier, and it is the model that cybersecurity-flagged requests on both Opus 5 and Fable 5 automatically re-run on. The migration notes below remain relevant to pinned Opus deployments.

Claude Opus 4.7 Migration (April 2026)

Breaking changes in Claude Opus 4.7

Opus 4.7 (claude-opus-4-7, released 2026-04-16) introduces four Messages-API-level breaking changes. Claude Code hides most of this from you, but if you use Opus 4.7 via the SDK or your own API clients — or via LLM gateways like LiteLLM — you must update your request shapes. Claude Managed Agents users are unaffected.

1. Extended thinking budgets removed

thinking: {"type": "enabled", "budget_tokens": N} now returns 400. Adaptive thinking is the only thinking-on mode, and it’s off by default on Opus 4.7.

# Before (Opus 4.6)
thinking = {"type": "enabled", "budget_tokens": 32000}

# After (Opus 4.7)
thinking = {"type": "adaptive"}
output_config = {"effort": "high"}  # or "xhigh" for deepest reasoning

2. Sampling parameters removed

Setting temperature, top_p, or top_k to a non-default value returns 400. Just omit them — prompt for determinism instead (note: temperature=0 never guaranteed identical output).

# Before
response = client.messages.create(model="claude-opus-4-6", temperature=0, ...)

# After — omit sampling params
response = client.messages.create(model="claude-opus-4-7", ...)

3. Thinking content omitted by default

Thinking blocks are still emitted but their thinking field is empty unless you opt in. This is a silent change — set display to restore visible reasoning output.

thinking = {
    "type": "adaptive",
    "display": "summarized",  # or "omitted" (default)
}

UX impact: if your product streams reasoning to users, the new default looks like a long pause before output begins. Use "summarized" to restore visible progress during thinking.

4. New tokenizer (~1.0–1.35x token usage)

Opus 4.7 uses a new tokenizer. Expect anywhere from same to ~35% more tokens compared to Opus 4.6 depending on workload shape. /v1/messages/count_tokens will return different numbers for the same input. Bump max_tokens for headroom — including compaction triggers in Claude Code.

Opus 4.7 ships with the full 1M context at standard API pricing (no long-context premium). In Claude Code, versions before v2.1.117 computed context against a 200K window even when running Opus 4.7, causing inflated /context percentages and early autocompact. Update Claude Code to 2.1.117+ before pinning Opus 4.7 to get the fix.

Task budgets (beta)

Opus 4.7 adds an optional task_budget as a soft cap on total tokens across a full agentic loop (including thinking, tool calls, tool results, final output). Unlike max_tokens, the model sees the running countdown and self-moderates.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[{"role": "user", "content": "Refactor the auth module."}],
    betas=["task-budgets-2026-03-13"],
)

Minimum value is 20k tokens. Skip it for open-ended work where quality matters more than token spend.

Behavior changes (not API-breaking, but worth knowing)

• More literal instruction following — remove “double-check the X before returning” style scaffolding; Opus 4.7 no longer generalizes across items you didn’t ask about.
• Response length calibrates to task complexity — expect leaner output on simple asks.
• Fewer tool calls by default, uses reasoning more — raise effort to increase tool usage.
• More direct, opinionated tone — less validation-forward, fewer emoji.
• Fewer subagents spawned by default — steerable through prompting.

Claude Sonnet 4 / Opus 4 deprecation

The legacy Claude Sonnet 4 (claude-sonnet-4-20250514) and Claude Opus 4 (claude-opus-4-20250514) retired on 2026-06-15. Current targets are claude-sonnet-5 and claude-opus-5. Claude Opus 4.1 (claude-opus-4-1-20250805) is deprecated and retires on 2026-08-05 — migrate pinned deployments to claude-opus-5 before then. See Anthropic’s model deprecations page for details.

Understanding Upgrade Paths

Auto-Updates (Default)

Seamless background updates with zero downtime - recommended for most users

Manual Updates

Full control over timing and testing - ideal for teams and enterprises

Version Pinning

Lock to specific versions for stability - required in regulated environments

Rollback Ready

Always maintain ability to revert - critical for production environments

Pre-Upgrade Checklist

Before any upgrade, ensure you’re prepared:

1. Check Current Version

   claude --version
   claude doctor  # More detailed diagnostics

2. Review Release Notes

   github.com/anthropics/claude-code/releases

   # Check the GitHub releases page (or the in-product changelog)

   Tip

   Copy-paste prompt to turn the changelog into a migration plan. Run it after step 1 shows your current version:

   I'm about to upgrade Claude Code from <CURRENT_VERSION> to <TARGET_VERSION>.
   Read the release notes at github.com/anthropics/claude-code/releases for every
   version between those two. List, in a table: (1) anything that changes the
   settings.json schema or default permissions, (2) any hook event renames or
   removed hook fields, (3) any .mcp.json / `claude mcp` changes, (4) any renamed
   or removed slash commands or CLI flags. For each, give the exact migration step.
   Then tell me which of my files to back up first.

3. Backup Critical Configurations

   # Backup your configurations
   cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)
   cp -r .claude .claude.backup.$(date +%Y%m%d)

4. Test in Non-Critical Environment

   • Use a sandbox project first
   • Verify core workflows still function
   • Check custom commands and hooks

5. Notify Team Members

   • Communicate upgrade schedule
   • Share any breaking changes
   • Coordinate timing for minimal disruption

Upgrade Procedures by Installation Type

The native binary is the recommended install. The supported npm path installs the same native binary and is useful when your fleet already manages software through an npm registry.

NPM Global Installation (Supported Advanced Option)

Note

As of v2.1.198, npm installation requires Node.js 22+ and a package manager that preserves optional dependencies. The installed claude executable is still native and does not invoke Node at runtime.

Standard Upgrade

# Check for updates
npm outdated -g @anthropic-ai/claude-code

# Install the newest release explicitly
npm install -g @anthropic-ai/claude-code@latest

# Verify upgrade
claude --version

Clean Install

# Sometimes needed for major version jumps
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

Specific Version

# Pin to specific version
npm install -g @anthropic-ai/claude-code@2.1.207

# Verify exact version
npm list -g @anthropic-ai/claude-code

Tip

Permission issues? Never use sudo npm install -g. Fix the npm global prefix or switch to the recommended native installer. Avoid npm update -g, which can remain inside the original semver range and miss the newest release.

Native Binary Installation (Recommended)

The native installer is the current default and avoids the permission issues of global npm installs. Native installs auto-update in the background.

Update Binary

# Update an existing installation
claude update

# Or (re)install the latest native build
curl -fsSL https://claude.ai/install.sh | bash

# Confirm install type and version
claude doctor

Platform Notes

• macOS: Universal binary, works on Intel and Apple Silicon
• Linux: Automatic architecture detection
• Windows: Native installers support PowerShell and CMD; WinGet is also available. WSL is optional for Linux toolchains and required only for features such as sandboxed command execution

Homebrew, WinGet, and the signed apt / dnf / apk repositories update through their package managers rather than the native background updater. Homebrew and WinGet can opt into Claude-triggered upgrades with CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1; Linux package managers remain manual because upgrades require elevated privileges. Verify the exact repository and signing-key commands in the official installation guide.

Handling Breaking Changes

Example: Bedrock model identifiers

When you run Claude Code against Amazon Bedrock, the model is set via ANTHROPIC_MODEL, but the valid ID format depends on the Bedrock surface. The current Claude-in-Bedrock Messages endpoint uses dateless IDs such as anthropic.claude-sonnet-5; the legacy InvokeModel surface uses versioned global or cross-region inference-profile IDs and does not expose Sonnet 5. Do not copy an ID between these surfaces.

1. Use a valid Bedrock model string

   # Current Claude-in-Bedrock Messages endpoint
   export CLAUDE_CODE_USE_MANTLE=1
   export ANTHROPIC_MODEL='anthropic.claude-sonnet-5'
   
   # Legacy InvokeModel inference-profile example (older model)
   export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'
   
   # Or an application-inference-profile ARN
   export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-profile-id'

   Look up the model in the current Bedrock documentation or the legacy catalog that matches your endpoint before pinning it.

2. Test Configuration

   # Verify the binding resolves
   claude doctor

3. Proceed with Upgrade

   claude update

Common Breaking Change Categories

Configuration Format

JSON structure changes, new required fields, deprecated options

API Changes

SDK field renames (e.g., total_cost → total_cost_usd)

Tool Renames

Built-in tools get clearer names (e.g., LSTool → LS)

Command Changes

Slash commands or flags modified or deprecated

Enterprise Upgrade Strategy

Version Control and Testing

• Directoryinfrastructure/

  • Directoryclaude-code/

    • versions.json (approved versions)
    • Directorytest-suite/ (upgrade validation)

      • …
    • Directoryrollback-scripts/

      • …
• Directorydocumentation/

  • upgrade-log.md
  • known-issues.md

Staged Rollout Process

1. Development Environment

   • Test with volunteer developers
   • Run for 1-2 days
   • Collect feedback

2. Staging Environment

   • Broader testing group
   • Full workflow validation
   • Performance benchmarking

3. Production Rollout

   • Communicate via team channels
   • Staggered by team/region
   • Monitor for issues

4. Post-Upgrade Review

   • Gather team feedback
   • Document any issues
   • Update procedures

Enterprise Configuration Management

# Disable auto-updates company-wide
export DISABLE_AUTOUPDATER=1

# Version pinning in package.json
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "1.0.54"
  }
}

# Automated deployment script
#!/bin/bash
APPROVED_VERSION="1.0.54"
CURRENT_VERSION=$(claude --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

if [ "$CURRENT_VERSION" != "$APPROVED_VERSION" ]; then
  npm install -g @anthropic-ai/claude-code@$APPROVED_VERSION
fi

Rollback Procedures

When an upgrade causes issues, quick rollback is essential:

Immediate Rollback

NPM Method

# Rollback to previous version
npm install -g @anthropic-ai/claude-code@1.0.53

# Restore configuration backup
rm -rf ~/.claude
mv ~/.claude.backup.20250716 ~/.claude

Local Install

# Local installations maintain version history
cd ~/.claude/versions

# List available versions
ls -la

# Switch to previous version
ln -sf 1.0.53 current

Rollback Checklist

• ☐ Stop all running Claude Code instances
• ☐ Restore previous version
• ☐ Restore configuration backups
• ☐ Clear any corrupted cache/state
• ☐ Verify functionality
• ☐ Document issues for bug report

Post-Upgrade Verification

After any upgrade, verify critical functionality:

1. Basic Functionality

   # Check version and diagnostics
   claude --version
   claude doctor
   
   # Test basic interaction
   claude "Hello, are you working correctly?"

2. Configuration Integrity

   # Verify settings preserved
   cat ~/.claude/settings.json
   
   # Check custom commands
   ls .claude/commands/

3. Tool Functionality

   # Test file operations
   claude "List files in current directory"
   
   # Check MCP servers (terminal CLI)
   claude mcp list

   Inside an interactive session, run /mcp instead — it opens the server-status and OAuth management UI.

4. Performance Check

   • Response time
   • Memory usage
   • Context handling

Troubleshooting Common Upgrade Issues

Configuration Corruption

Caution

If Claude Code fails to start after upgrade, configuration corruption is often the cause.

# Diagnose configuration issues
claude doctor

# Back up the current settings if you need to isolate a malformed file
mv ~/.claude/settings.json ~/.claude/settings.json.backup
claude # Will recreate with defaults

Permission Errors

# Do not use sudo with npm; fix the user-owned global prefix
npm config set prefix ~/.npm-global

# Or install the recommended native build
curl -fsSL https://claude.ai/install.sh | bash

Version Conflicts

# Check for multiple installations
which -a claude
type -a claude

# Remove duplicates
npm uninstall -g @anthropic-ai/claude-code
# Then reinstall

MCP Server Compatibility

After major upgrades, MCP servers may need updates:

# Check MCP server status (terminal CLI)
claude mcp list

# To update an MCP server, remove and re-add it.
# The -- separator is required for stdio servers so Claude's flags
# don't collide with the server's own command and args.
claude mcp remove <server-name>
claude mcp add <server-name> -- <command> [args...]

Best Practices Summary

Always Backup

Configuration and custom commands before any upgrade

Test First

In isolated environment before team-wide rollout

Read Release Notes

Understand changes and potential impacts

Coordinate Teams

Synchronize upgrades to avoid version mismatches

Monitor Post-Upgrade

Watch for performance changes or new issues

Document Everything

Keep upgrade logs for future reference

Emergency Contacts

If critical issues arise during upgrade:

1. GitHub Issues: Report bugs with version details (claude doctor output)
2. Discord: Check the Claude Developers Discord for others hitting the same issue
3. Rollback First: Don’t try to fix forward in production
4. Document Thoroughly: Help others avoid same problem

Tip

Copy-paste prompt for a post-upgrade smoke test. Run it in your real project right after upgrading:

I just upgraded Claude Code. Verify my setup is intact: read my settings.json and
.mcp.json, then check that (1) every configured MCP server connects, (2) my hooks
still fire on their events, and (3) my custom slash commands in .claude/commands/
still resolve. Report anything that broke and the smallest fix for each. Don't
change any files — just diagnose.

What’s Next

• Claude Code Version History — track what shipped between your versions.
• Beta Features and Early Access — opt into research-preview features like dynamic workflows.
• Staying Current with Claude Code — the full version-management workflow.