jeremylongshore Anthropic Upgrade & Migration
Overview
Guide for upgrading the Anthropic SDK and migrating between API versions. The SDK follows semver — major versions may have breaking changes.
Check Current Versions
# Python
pip show anthropic | grep Version
# Version: 0.40.0
# TypeScript
npm list @anthropic-ai/sdk
# @anthropic-ai/sdk@0.35.0
# Check latest available
pip index versions anthropic 2>/dev/null | head -1
npm view @anthropic-ai/sdk version
Upgrade Path
Step 1: Create Upgrade Branch
git checkout -b upgrade/anthropic-sdk
Step 2: Upgrade SDK
# Python
pip install --upgrade anthropic
pip show anthropic | grep Version
# TypeScript
npm install @anthropic-ai/sdk@latest
Step 3: Review Breaking Changes
Key breaking changes by version:
Python SDK 0.20+ (anthropic-version: 2023-06-01)
# OLD: Text Completions API (deprecated)
response = client.completions.create(
model="claude-2",
prompt="\n\nHuman: Hello\n\nAssistant:",
max_tokens_to_sample=256
)
# NEW: Messages API
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Hello"}]
)
Python SDK 0.30+ (streaming changes)
# OLD: Manual SSE parsing
response = client.messages.create(..., stream=True)
for line in response.iter_lines():
...
# NEW: High-level streaming
with client.messages.stream(...) as stream:
for text in stream.text_stream:
print(text)
TypeScript SDK 0.20+ (import path change)
// OLD
import Anthropic from 'anthropic';
// NEW
import Anthropic from '@anthropic-ai/sdk';
Step 4: Update API Version Header
# The SDK sends anthropic-version header automatically
# To pin a specific version:
client = anthropic.Anthropic(
default_headers={"anthropic-version": "2023-06-01"}
)
# For beta features:
client = anthropic.Anthropic(
default_headers={"anthropic-beta": "token-counting-2024-11-01"}
)
Step 5: Run Tests and Verify
# Run your test suite
python -m pytest tests/ -v
npm test
# Verify a live call
python3 -c "
import anthropic
c = anthropic.Anthropic()
m = c.messages.create(model='claude-haiku-4-20250514', max_tokens=8, messages=[{'role':'user','content':'hi'}])
print(f'OK: {m.model} {m.usage}')
"
Migration: Text Completions to Messages
| Text Completions | Messages API |
|---|---|
client.completions.create() |
client.messages.create() |
prompt (string) |
messages (array) |
max_tokens_to_sample |
max_tokens |
model: "claude-2" |
model: "claude-sonnet-4-20250514" |
\n\nHuman:...\n\nAssistant: |
[{role: "user"}, {role: "assistant"}] |
response.completion |
response.content[0].text |
Rollback
# Python — pin to previous version
pip install anthropic==0.39.0
# TypeScript — pin to previous version
npm install @anthropic-ai/sdk@0.34.0
# Git rollback
git checkout main -- package.json package-lock.json
npm install
Resources
Next Steps
For CI integration during upgrades, see anth-ci-integration.