Anthropic Python SDK v1.0: httpx2 Migration and Breaking Changes

Anthropic Python SDK v1.0 is a meaningful migration, not a cosmetic version bump. Released on August 20, 2026, anthropic 1.0.0 raises the minimum Python version to 3.10, moves the SDK’s HTTP layer from httpx to the Pydantic-maintained httpx2 fork, removes several deprecated API surfaces, and changes raw-response handling.

The most important operational warning is easy to miss: applications that patch httpx for tracing, APM, recording, or tests can continue to run while no longer observing Claude SDK traffic. Teams should audit the HTTP boundary before upgrading production workloads.

What changed in Anthropic Python SDK v1.0?

The upgrade is generally low-friction for applications that only call client.messages.create() with ordinary values. It is more consequential for code that owns custom HTTP clients, transports, timeout objects, response inspection, Bedrock configuration, or HTTP mocking.

Anthropic’s official release notes say that v1.0 moves from httpx to httpx2, requires Python 3.10 or later, removes the legacy Text Completions API, removes temperature, top_p, and top_k from Messages methods, and changes the async raw-response flow. The v1 migration guide provides the before-and-after details.

The package is also independently visible on PyPI, where anthropic 1.0.0 is marked as released on August 20, 2026 and lists Python 3.10+ as a requirement. The GitHub v1.0.0 release records the httpx2 upgrade as a breaking change.

The migration map

The following flow separates the easy path from the risky path. It is an original decision diagram based on Anthropic’s migration documentation.

Visual credit: original diagram by Essam Mdani, based on the Anthropic v1 migration guide.

Compatibility at a glance

The table is a practical summary, not a substitute for the full migration reference.

The safe upgrade path for ordinary API calls

Start by pinning the major version deliberately:

1python -m pip install --upgrade 'anthropic>=1,<2'

A minimal Messages API call remains straightforward:

1import os
2from anthropic import Anthropic
3
4client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
5message = client.messages.create(
6    model="claude-opus-5",
7    max_tokens=1024,
8    messages=[{"role": "user", "content": "Summarize this deployment plan."}],
9)
10
11for block in message.content:
12    if block.type == "text":
13        print(block.text)

This shape follows the current Python SDK documentation. The SDK still supports synchronous and asynchronous clients, streaming, batches, file uploads, tool helpers, and hosted deployment integrations. Do not infer that every feature is unchanged merely because the basic call is unchanged: response wrappers and HTTP-layer types are where most v1 migration work lives.

What the httpx2 switch means

httpx2 is designed as an API-compatible continuation of httpx, but Python treats classes from the two packages as different types. A httpx.Client is not an httpx2.Client, even when their public APIs look alike. The Pydantic HTTPX2 migration guide explains that both packages can coexist, but objects and exception types do not safely cross the boundary.

If your application only passes a numeric timeout, the SDK can keep constructing its own client. If you pass a custom transport, proxy, timeout object, event hook, or client, create that object from httpx2 or use Anthropic’s SDK helpers:

1import httpx2
2from anthropic import Anthropic, DefaultHttpxClient
3
4client = Anthropic(
5    timeout=httpx2.Timeout(60.0, connect=5.0),
6    http_client=DefaultHttpxClient(
7        proxy="http://proxy.internal:8080",
8        transport=httpx2.HTTPTransport(),
9    ),
10)

The migration guide also documents httpx2.alias_httpx(). This can help an application whose tracing or mocking stack still imports httpx, but it must run before anything imports httpx or httpcore. It should be an application decision, not something imposed by a reusable library.

1First lines of the application entry point:
2
3```python
4import httpx2
5httpx2.alias_httpx()
6
7from anthropic import Anthropic

Treat aliasing as a compatibility bridge. Add a test that proves the tracer or mock actually intercepted a request; a green test suite alone does not prove that an old patch still sees the SDK.

The observability and testing trap

The official migration guide specifically calls out tools that patch httpx, including OpenTelemetry’s HTTPX instrumentor, Sentry’s HTTPX integration, respx, pytest-httpx, and vcrpy. After the SDK moves to httpx2, those tools may continue importing and running while observing nothing.

That creates a dangerous failure mode:

1. The application starts successfully.
2. The test mock remains active.
3. The SDK sends requests through httpx2.
4. The old mock sees no request.
5. A test that never asserts interception can still pass.

Add explicit assertions around request capture, spans, and recorded traffic. If the tool has an httpx2-compatible release, prefer that. Otherwise, use an httpx2.MockTransport or call alias_httpx() at process startup after evaluating the process-wide import effect.

A useful smoke-test checklist is:

• Assert that one mocked SDK request was intercepted.
• Assert that one real staging request produces a trace span.
• Check isinstance checks and type annotations for response objects.
• Exercise retries, timeouts, proxies, and custom transports if you own them.
• Run the test suite in the same Python version used by production.

Removed API surfaces and replacements

Legacy Text Completions

client.completions.create() and its legacy completion types are removed. Current Claude integrations should use the Messages API. This is not a mechanical rename: prompt formatting, response parsing, and stop behavior should be reviewed against the model and endpoint you actually use.

Deprecated sampling parameters

The v1 migration guide removes temperature, top_p, and top_k from the relevant generated method signatures. Do not blindly move them into a request just to silence a type checker. Confirm whether the target model and endpoint support the behavior you need. If a legacy model requires an extra body field, use the documented escape hatch carefully and test the resulting request.

Raw response methods

On async raw responses, parsing is now awaited:

1response = await async_client.messages.with_raw_response.create(
2    model="claude-opus-5",
3    max_tokens=128,
4    messages=[{"role": "user", "content": "Return OK."}],
5)
6message = await response.parse()

The sync response API also changes some properties into methods: use response.text() and response.read() where the new response class requires calls. Update type annotations from httpx response classes to httpx2 equivalents when inspecting SDK errors or raw responses.

A production migration sequence

1. Inventory before installing

Search for import anthropic, import httpx, custom transports, http_client=, with_raw_response, client.completions, and sampling parameters. Include test utilities, shared observability modules, and dependency-injection factories.

2. Make the runtime decision

If the service cannot move to Python 3.10 yet, pin the last compatible 0.x line and schedule the runtime upgrade. Do not let a resolver choose a major-version jump accidentally during an unrelated deployment.

3. Upgrade in a branch

Install v1 in a clean environment, run static checks, and inspect the lockfile. Keep the version range explicit so a future major release cannot enter unnoticed.

4. Repair HTTP boundaries

Replace custom httpx objects passed into Anthropic with httpx2 objects or SDK-provided helpers. Audit isinstance checks, exception handlers, event hooks, and transport-specific code.

5. Prove telemetry and mocks

Require positive assertions. Verify a span exists, a mock recorded a request, and a replay fixture was actually consumed. This is the step most likely to catch a silent regression.

6. Exercise integrations

Run Bedrock tests with an explicit AWS region, async raw-response tests with awaits, streaming tests, tool tests, and any batch or file workflows used by the application.

7. Deploy progressively

Ship to a staging or canary environment with request IDs, error rates, latency, and trace-volume dashboards. A sudden drop in spans without a corresponding drop in API calls is a strong signal that instrumentation is still attached to httpx rather than httpx2.

Common errors and debugging

TypeError while constructing Anthropic: an old httpx.Client, Timeout, or transport is crossing into the v1 client. Rebuild it using httpx2 or DefaultHttpxClient.

Mocks match zero requests: confirm whether the mock library patches httpx. Upgrade the integration, use an httpx2 transport, or apply alias_httpx() before imports.

ModuleNotFoundError during installation: check the Python interpreter first. v1 requires Python 3.10 or newer.

AttributeError around raw responses: inspect whether .text or .content became a method, and whether async .parse(), .read(), .text(), or .json() is awaited.

Bedrock client fails before a request: configure the AWS region explicitly rather than relying on the old defaulting behavior.

Tracing volume falls after upgrade: compare API request counts with HTTP span counts and inspect import order. The process may be using httpx2 while the instrumentor is still attached to httpx.

Should you upgrade now?

For a small service that calls the Messages API with default networking, yes: the upgrade is mostly a runtime and dependency pin change. For a platform with custom transports, enterprise proxies, deep tracing, recorded HTTP tests, or old Python images, schedule a deliberate migration rather than merging a one-line dependency change.

The best decision rule is simple: upgrade when you can prove the HTTP boundary, not when the application merely starts. Anthropic’s v1 release stabilizes the package surface, but the httpx to httpx2 transition makes invisible integration failures more important than visible import errors.

FAQ

Does Anthropic Python SDK v1.0 exist?

Yes. anthropic 1.0.0 was uploaded to PyPI and the v1.0.0 tag was published on August 20, 2026. Verify the installed version in your lockfile and environment rather than relying on a global interpreter.

Do basic messages.create() calls need rewriting?

Usually not, if they use supported parameters, ordinary values, and the SDK’s default HTTP client. Still run the current test suite and confirm Python 3.10+.

Is httpx2 a totally different API?

It is intended to be API-compatible with httpx, but its classes, exceptions, module names, and package identity are distinct. Code that passes or inspects HTTP objects must use the matching package.

Is alias_httpx() safe in a library?

Anthropic and Pydantic document it as an application-level compatibility mechanism. A library should not change the meaning of import httpx process-wide for its users.

What is the first test to add?

Add one positive interception test and one positive tracing test. Assert that the request was captured and that the span was emitted; do not assert only that the test process exited successfully.

Conclusion

Anthropic Python SDK v1.0 is easy for the default path and consequential for the infrastructure path. Upgrade the runtime, pin the major version, replace custom HTTP objects with httpx2 equivalents, remove retired API calls, update async raw-response code, and prove that mocks and telemetry still observe the SDK.

The migration is manageable because the official documentation is unusually explicit. Use the Python SDK guide, the v1 migration file, and the Pydantic HTTPX2 guide as the implementation references—not an inferred compatibility story from a successful import.

Related reading

If you are building a broader agent stack, see the site’s guide to Anthropic computer use and browser use. For protocol-level integrations, compare the MCP C# SDK stateless HTTP migration. Teams maintaining agent infrastructure may also benefit from the OpenAI Agents SDK sandbox and harness guide.

Sources and visual credits

• Anthropic Claude Platform release notes
• Anthropic Python SDK v1 migration guide
• Anthropic Python SDK v1.0.0 release
• Anthropic Python SDK documentation
• PyPI package record
• Pydantic HTTPX2 migration guide
• Visual 1: original Mermaid migration map, informed by Anthropic’s migration guide.
• Visual 2: comparison table summarizing documented v0.x/v1.0 compatibility changes.
• Visual 3: code/request-flow examples adapted from the official SDK and migration documentation; links above provide source and credit.