Claude 4 Migration Guide: Step-by-Step Before June 15

Claude 4 Opus and Sonnet 4 retire in 13 days. Here's exactly how to migrate — with code examples for Python, Node.js, and REST API, plus a testing checklist and rollback plan.

What's Retiring and What Replaces It

Step 1: Find All Deprecated Model References

Search your entire codebase for the old model IDs. Check source code, config files, environment variables, and documentation.

Python / Node.js projects

# Search for both deprecated models
grep -rn "claude-4-opus\|claude-sonnet-4" src/ config/ .env*

# Also check for the long-form names
grep -rn "Claude 4 Opus\|Claude Sonnet 4" docs/ README.md

Common locations to check

• Source code files (model parameter in API calls)
• .env or .env.production files (MODEL_NAME variable)
• Config files (JSON, YAML, TOML)
• Docker compose files or deployment configs
• CI/CD pipeline definitions
• Documentation and README files

Step 2: Update the Model Name

Python (Anthropic SDK)

# Before (deprecated)
response = client.messages.create(
    model="claude-4-opus",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

# After (replacement)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

Node.js (Anthropic SDK)

// Before (deprecated)
const message = await anthropic.messages.create({
  model: "claude-4-opus",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }]
});

// After (replacement)
const message = await anthropic.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }]
});

REST API (curl)

# Before (deprecated)
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"model": "claude-4-opus", "max_tokens": 1024, ...}'

# After (replacement)
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"model": "claude-opus-4-8", "max_tokens": 1024, ...}'

Sonnet migration

# Before
model: "claude-sonnet-4"

# After
model: "claude-sonnet-4-6"

Step 3: Update SDK Version

Make sure you're on the latest Anthropic SDK version. Older versions may not recognize the new model IDs.

# Python
pip install --upgrade anthropic

# Node.js
npm update @anthropic-ai/sdk

The new model IDs work with SDK version 0.39+ (Python) and 0.39+ (Node.js). If you're on an older version, upgrade first.

Step 4: Test in Parallel

Don't switch cold turkey. Run both models side-by-side for 1-2 weeks to validate output quality.

Parallel testing pattern

import os

OLD_MODEL = "claude-4-opus"
NEW_MODEL = "claude-opus-4-8"

def test_migration(prompt):
    # Run both models
    old_response = client.messages.create(model=OLD_MODEL, ...)
    new_response = client.messages.create(model=NEW_MODEL, ...)

    # Compare outputs
    print(f"Old: {old_response.content[0].text[:100]}")
    print(f"New: {new_response.content[0].text[:100]}")
    print(f"Old cost: ${calculate_cost(old_response)}")
    print(f"New cost: ${calculate_cost(new_response)}")

What to test

• Run your top 20 most common prompts through both models
• Compare output quality (accuracy, tone, formatting)
• Measure latency differences
• Verify structured output (JSON mode, function calling)
• Test edge cases (long inputs, system prompts, multi-turn)
• Check token usage (new model may use different token counts)
• Validate that your parsing/post-processing still works

Step 5: Deploy and Monitor

Once validated, update production. Keep the old model ID in a comment for reference.

Deployment checklist

• Update model name in all environments (dev, staging, prod)
• Update environment variables
• Deploy to staging first, run smoke tests
• Deploy to production during low-traffic window
• Monitor error rates for 24 hours
• Monitor cost dashboard — confirm savings appear
• Update documentation and README files

Rollback plan

If something goes wrong, you can switch back instantly — just change the model name back. But note: after June 15, the old model IDs will stop working entirely. Keep your rollback window within the next 13 days.

Cross-Provider Migration (Advanced)

If you want to switch from Anthropic entirely (to save 85-99%), the migration is more involved:

DeepSeek migration example (OpenAI-compatible)

# DeepSeek uses OpenAI-compatible API
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello"}]
)

Cost Impact: Real Workload Example

For a typical workload of 10M input + 2M output tokens/month:

Calculate your exact savings with the Claude Deprecation Calculator — input your real token usage and see costs across all 34 models.

Timeline: What to Do and When