Anthropic Python SDK v1 Migration Guide: Python 3.10, HTTPX 2 and Breaking API Changes

Anthropic Python SDK v1 is a runtime and integration-contract upgrade, not a routine package bump.

Version 1 raises the minimum supported Python version from 3.9 to 3.10, moves the SDK’s HTTP layer from httpx to httpx2, changes raw-response handling, removes deprecated SDK surfaces and requires an AWS region to resolve for AnthropicBedrock. Applications with custom HTTP clients, tracing, mocks, legacy Completions calls, async raw responses or Bedrock integrations need deliberate migration work. Anthropic’s official v1 migration guide

As of August 27, 2026, the current release reviewed for this guide is anthropic==1.2.0, matched to official tag v1.2.0. The PyPI wheel is anthropic-1.2.0-py3-none-any.whl, SHA-256 b60642b3e3cd6b8e3e328a2d3f2863ad2b6e743f1037e42cc0143f7df99f63c6. Recheck the official releases and PyPI package before using those values later.

Kingy tracks this change in the Anthropic Python SDK v1 Radar record. Browse related provider changes in the Model Economics and Migrations hub.

What changed

These changes are documented in Anthropic’s release notes and v1 migration guide.

Who needs to act

Review the migration carefully if your application:

• Still runs Python 3.9 in development, CI, workers, serverless runtimes or deployment images.
• Passes custom httpx clients, transports, timeouts, limits or proxies into the SDK.
• Uses SDK-returned httpx.Request, Response or Headers types.
• Instruments or mocks the old httpx package.
• Calls client.completions.create() or uses HUMAN_PROMPT, AI_PROMPT or /v1/complete.
• Passes temperature, top_p or top_k to Messages methods.
• Reads asynchronous raw responses without awaiting their parsing or body methods.
• Sends raw bytes through low-level body= or passes bytes-valued headers.
• Relied on the former implicit Bedrock us-east-1 fallback.
• Consumes unknown Bedrock streaming events such as amazon-bedrock-invocationMetrics.

Safe migration sequence

1. Inventory before upgrading

Record the Python runtime, deployed Anthropic version, lockfiles, build manifests, custom HTTP integrations, tracing and mock libraries, Bedrock region sources and exact rollback package. Establish a baseline with the existing type checker and tests.

Use only synthetic data and non-production credentials for migration exercises. Disable external tool side effects, set request and spend ceilings, and reject fixtures or logs containing secrets, customer data, production prompts or personal information.

2. Upgrade the runtime first

Every environment that will run SDK v1 must use Python 3.10 or later. Do not infer deployment support from a developer workstation. Anthropic v1 environment requirements

import sys

assert sys.version_info >= (3, 10), (
    "Anthropic Python SDK v1 requires Python 3.10 or later"
)

3. Pin and verify the package

Anthropic documents the generic range:

pip install --upgrade "anthropic>=1,<2"

Treat that as vendor reference syntax, not an immutable deployment command. Resolve a reviewed exact release, obtain it from an approved package source, verify the expected artifact digest, commit the application’s lockfile and inspect the direct and transitive dependency diff. Install first in an isolated non-production build. Official upgrade guidance

For the release reviewed on August 27, 2026, the exact pin is:

anthropic==1.2.0

4. Replace SDK-bound httpx objects

Objects that cross the SDK boundary must come from httpx2:

import httpx2
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    http_client=DefaultHttpxClient(
        transport=httpx2.HTTPTransport(retries=1)
    )
)

Update request and response annotations, exception handling, transports, proxies, fixtures and isinstance checks. Passing an old httpx.Client or httpx.AsyncClient through http_client= raises TypeError during construction. Custom HTTP migration

5. Use alias_httpx() only as a last-resort application bridge

Anthropic documents httpx2.alias_httpx() for applications that cannot immediately replace old imports. It makes both httpx and httpcore resolve to their v2 replacements for the entire process and must run before either old package is imported. A reusable library must never enable it for its users. Alias behavior

import httpx2

httpx2.alias_httpx()

import httpx

Prefer direct imports. If the bridge is unavoidable, inventory every in-process HTTP consumer, test unrelated clients and instrumentation in isolation, put the call under application entry-point control and define its removal and rollback conditions. Stop if import order or compatibility cannot be proven.

6. Repair tracing and mocks without logging sensitive content

Instrumentation and mocking tools that patch httpx can silently stop seeing SDK traffic after the migration. Verify controlled success and failure paths, trace creation, mock interception, proxy behavior and timeout behavior. Also verify that prompts, bodies, tool arguments, API keys, authorization headers and customer identifiers are absent or irreversibly redacted. Anthropic’s tracing and mocking guidance

7. Remove legacy Completions usage

Search for client.completions.create, HUMAN_PROMPT, AI_PROMPT, /v1/complete and the old completion types. Move each flow deliberately to Messages, reviewing roles, system instructions, stop behavior and output parsing rather than mechanically converting an alternating prompt string. Messages migration requirement

8. Remove deprecated Messages arguments

Remove temperature, top_p and top_k from generated Messages method calls. Anthropic’s guide shows claude-sonnet-4-6 only as an older-model example for passing temperature through extra_body; do not copy that exception unless the application is intentionally pinned to a model that requires it. Removed request parameters

9. Update raw-response handling

Async response parsing and body access must be awaited:

response = await client.messages.with_raw_response.create(...)
message = await response.parse()
body = await response.text()

For the synchronous client, parse() remains synchronous, while body access uses methods such as text() and read(). Raw-response changes

10. Update low-level bytes, headers and Bedrock regions

Send raw payload bytes through content=, not body=. Convert bytes-valued header values to strings. Remember that differently cased forms of the same header name are now merged case-insensitively. Low-level request and header changes

Configure the actual authorized Bedrock region explicitly or through AWS_REGION, AWS_DEFAULT_REGION or the selected boto3 profile:

import os
from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region=os.environ["AWS_REGION"])

Do not hard-code us-east-1 merely to recreate the old fallback. Bedrock region resolution

Validation and rollout

Before rollout, verify runtime compatibility, locked artifact identity, type checking, basic and streaming Messages behavior, sync and async raw responses, error handling, custom transports, traces, mocks, removed surfaces and Bedrock region failure. Use synthetic fixtures, mocked tools and non-production credentials only.

Roll out by service. Retain the previous lockfile, package artifact, instrumentation and request-construction path until the rollback window closes. If rollback is required, restore those items together. If alias_httpx() was enabled, disable it at the application entry point and restart the process; do not try to reverse imported module identity in place.

Testing limitation

Kingy source-reviewed these instructions against Anthropic’s official documentation but did not independently execute the examples or reproduce the errors. Treat the code as illustrative and verify it against your pinned SDK and application in a safe non-production environment.

Official sources

• Anthropic Python SDK v1 migration guide
• Claude Python SDK documentation
• Claude Platform release notes
• Anthropic Python SDK releases
• Anthropic on PyPI

Migrating Gemini instead? Use the Gemini 3.7 Flash guide.