Safe Upgrade Procedures

Upgrading Claude Code requires careful planning and execution, especially in team or enterprise environments. This guide provides comprehensive procedures for safe, reliable upgrades with minimal disruption to your workflow.

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

   # Within Claude Code
   /release-notes
   
   # Or check GitHub
   # github.com/anthropics/claude-code/releases

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

NPM Global Installation

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 migrate-installer

Local Installation (Recommended)

The local installation method avoids permission issues and provides smoother updates:

# If you haven't migrated yet
claude migrate-installer

# Updates happen automatically or manually
claude update

# Check installation location
which claude  # Should show ~/.claude/local/claude

Native Binary Installation (Alpha)

Update Binary

# From existing installation
claude install

# Or fresh install
curl -fsSL claude.ai/install.sh | bash

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 ARN Format Change (v0.2.125)

When upgrading across breaking changes, follow this pattern:

1. Identify the Change

   • Old format: arn:aws:bedrock:region::foundation-model/model%2Fversion
   • New format: arn:aws:bedrock:region::foundation-model/model/version

2. Update Configuration

   # Before upgrade, update environment variables
   export ANTHROPIC_MODEL="arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-opus-20240229-v1:0"
   # Note: No %2F, use literal /

3. Test Configuration

   # Verify configuration works
   claude doctor

4. 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
   claude config get autoUpdates --global
   claude config get model --global
   
   # Check custom commands
   ls .claude/commands/

3. Tool Functionality

   # Test file operations
   claude "List files in current directory"
   
   # Test MCP servers
   /mcp list

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 migrate-installer

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
/mcp list

# Update MCP configurations if needed
claude mcp update <server-name>

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
2. Community Forums: Check if others experiencing same issue
3. Rollback First: Don’t try to fix forward in production
4. Document Thoroughly: Help others avoid same problem

Tip

Remember: The rapid development of Claude Code means frequent updates with valuable improvements. A well-planned upgrade process lets you benefit from new features while maintaining stability.