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
pip show anthropic | grep Version
npm list @anthropic-ai/sdk
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
pip install --upgrade anthropic
pip show anthropic | grep Version
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)
response = client.completions.create(
model="claude-2",
prompt="\n\nHuman: Hello\n\nAssistant:",
max_tokens_to_sample=256
)
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Hello"}]
)
Python SDK 0.30+ (streaming changes)
response = client.messages.create(..., stream=True)
for line in response.iter_lines():
...
with client.messages.stream(...) as stream:
for text in stream.text_stream:
print(text)
TypeScript SDK 0.20+ (import path change)
import Anthropic from 'anthropic';
import Anthropic from '@anthropic-ai/sdk';
Step 4: Update API Version Header
client = anthropic.Anthropic(
default_headers={"anthropic-version": "2023-06-01"}
)
client = anthropic.Anthropic(
default_headers={"anthropic-beta": "token-counting-2024-11-01"}
)
Step 5: Run Tests and Verify
python -m pytest tests/ -v
npm test
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
pip install anthropic==0.39.0
npm install @anthropic-ai/sdk@0.34.0
git checkout main -- package.json package-lock.json
npm install
Resources
Next Steps
For CI integration during upgrades, see anth-ci-integration.
