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 Opus 4.8 (May 2026)

Opus 4.8 is the current default

Claude Opus 4.8 (claude-opus-4-8, released 2026-05-28) is now the Claude Code default. It defaults to high effort, with xhigh (“extra”) and max available for difficult or long-running tasks. Dynamic workflows ship as a research preview on a recent v2.1.x build. Opus 4.8 shares Opus 4.7’s Messages-API request shapes, so no code changes are needed when moving from 4.7 — the migration notes below still apply when upgrading from Opus 4.6 or earlier. Run claude update to get the current release before pinning Opus 4.8.

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) models retire 2026-06-15. Migrate to claude-sonnet-4-6 and claude-opus-4-7 respectively before that date. 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 install is the recommended, current method (covered below). The NPM global install path is deprecated but still works — keep these commands for machines you haven’t migrated yet.

NPM Global Installation (Deprecated)

Note

NPM installation is deprecated. Use the native installation method when possible — see Native Binary Installation below. Migrate an existing npm install with claude install.

Standard Upgrade

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

# Perform upgrade
npm update -g @anthropic-ai/claude-code

# 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@1.0.54

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

Tip

Permission Issues? If npm upgrade fails with permission errors, consider migrating to local installation:

claude install

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: Use WSL for binary installation

Handling Breaking Changes

Example: Bedrock model identifiers

When you run Claude Code against Amazon Bedrock, the model is set via the ANTHROPIC_MODEL environment variable. A common upgrade-time mistake is using a bare, version-less model string — Bedrock rejects it. Use a region-prefixed inference-profile ID with a version suffix, or a full application-inference-profile ARN. Apply this pattern whenever an upgrade changes your default model:

1. Use a valid Bedrock model string

   # Inference-profile ID form (region prefix + dated version + -v1:0)
   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'

   A bare foundation-model/anthropic.claude-... (no region prefix, no -vN:0) is not a usable Bedrock ID. Look up the current inference-profile ID for your chosen model in the Bedrock console before pinning.

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

# Reset to defaults if needed
mv ~/.claude/config.json ~/.claude/config.json.backup
claude # Will recreate with defaults

Permission Errors

# NPM permission issues
sudo npm install -g @anthropic-ai/claude-code  # Not recommended

# Better solution: migrate to local
claude install

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.