HTTPX2 becomes the default in OpenAI’s Python SDK

OpenAI’s Python SDK now builds its synchronous and asynchronous HTTP clients on HTTPX2. Since August 28, installing openai pulls in httpx2 and no longer installs httpx or certifi. For most applications, the risk sits in the second of those two packages.
OpenAI’s migration guide on GitHub splits users into two groups. If you construct OpenAI or AsyncOpenAI without passing http_client, API calls, parsed response models, streaming, authentication, retries and numeric timeouts keep working after a plain pip install openai, and there’s no extra to install. If you supply your own client, hooks, transports or mocks, they have to move to HTTPX2 objects. Code that imported httpx only because an earlier SDK installed it transitively now needs its own httpx dependency, or its imports moved to httpx2.
- Default TLS trust store: the CA bundle from certifi → the operating-system trust store
- HTTP library installed with
openai: httpx → httpx2 DefaultHttpxClientandDefaultAsyncHttpxClient: built HTTPX clients → still accepted, but now build HTTPX2 clients
Where certificates come from
The trust-store change also reaches applications that never touch the HTTP layer. HTTPX verified certificates against certifi’s bundle. HTTPX2 verifies them against the operating system’s trust store, and the SDK no longer installs certifi. The guide names three setups where verification can fail: minimal container images without system CA certificates, networks behind corporate proxies that inspect TLS traffic, and deployments that relied on a custom or modified certifi bundle.
There are three fixes. You can install the CA certificates into the OS trust store, or point SSL_CERT_FILE at a bundle or SSL_CERT_DIR at a directory of certificates. Both variables are honored when trust_env=True, which is the default. For explicit control, build an ssl.SSLContext and pass it through verify on DefaultHttpx2Client, or on DefaultAsyncHttpx2Client for async code. The SDK’s aiohttp transport uses the same HTTPX2 TLS settings, so switching transports won’t get you around the change.
A fork with a new name
HTTPX2 is Pydantic’s continuation of HTTPX. The project’s GitHub page says that because HTTPX itself has seen limited activity recently, Pydantic is taking over stewardship under the new name so users have a maintained path forward, including timely security updates. A generation of API SDKs, OpenAI’s among them, standardized on httpx, and the project slowed to the point where issues and pull requests were piling up without review.
Pydantic’s migration docs describe httpx2 as a fork of httpx 0.28.1 with the same public API, where the main change is the name. The two packages install side by side without conflict. Their objects can’t be swapped, though: httpx2.Client and httpx.Client are distinct classes, an isinstance check against one rejects the other, and except httpx2.HTTPError won’t catch an httpx.HTTPError. That is why every integration point in the SDK guide needs attention, even though the method names stay the same.
Custom clients, hooks and tests
For custom clients, the guide recommends DefaultHttpx2Client and DefaultAsyncHttpx2Client, which keep the SDK’s recommended timeout, connection-pool and redirect defaults. You can also construct httpx2.Client or httpx2.AsyncClient directly, but then HTTPX2’s own defaults apply unless you set them yourself. The same applies to module-level configuration through openai.http_client.
The object swap is mostly mechanical: Client, AsyncClient, Timeout, URL, Limits, HTTPTransport, AsyncHTTPTransport and MockTransport each move from the httpx namespace to httpx2. String URLs and numeric timeouts don’t change. Some code needs more than a new import. Custom transport subclasses, mounted transports, proxy integrations and connection-pool instrumentation must target HTTPX2’s transport interfaces. Auth handlers and event hooks now receive HTTPX2 request and response objects, and third-party tracing middleware and auth integrations work only if they explicitly support HTTPX2.
Parsed SDK models don’t change. With a native client, with_raw_response returns an httpx2.Response and httpx2.Request, streaming wrappers expose HTTPX2 responses, and you request an unparsed response with cast_to=httpx2.Response. You should still catch SDK exceptions such as openai.APITimeoutError and openai.APIConnectionError, but their underlying transport cause is now an HTTPX2 exception.
The openai[aiohttp] extra now ships an HTTPX2-native transport and no longer installs legacy httpx or the external httpx-aiohttp adapter. DefaultAioHttpClient() is itself an httpx2.AsyncClient.
Test suites are where the change is easiest to miss. Mocks must intercept HTTPX2 requests and return HTTPX2 responses. A RESPX version that patches only legacy HTTPX can’t intercept the SDK’s default client, so you need an HTTPX2-compatible RESPX release or a fork.
The escape hatch
If a transport, integration or mocking library can’t move yet, you can install legacy httpx yourself with pip install openai httpx and inject httpx.Client() or httpx.AsyncClient(). That support works at runtime only. The SDK’s public type annotations accept HTTPX2 clients, so mypy, Pyright and similar checkers reject a legacy client unless you wrap it in cast(Any, ...) or add a targeted type-ignore. A legacy client keeps returning httpx requests, responses and exceptions, even if you pass cast_to=httpx2.Response.
Existing httpx-aiohttp setups follow the same route: install the adapter explicitly and inject HttpxAiohttpClient() through the same cast. OpenAI says dedicated compatibility tests cover that path, including a real request through the aiohttp transport. Pydantic’s docs offer a different workaround for apps already on httpx2 whose dependencies still import httpx: httpx2.alias_httpx(), which makes both names share the same classes.
The guide says you install and maintain the legacy dependency yourself, and that “legacy HTTPX support is provided as a migration aid and may be discontinued.”
Up next
Hub testing in Claude adds a switch-back feedback prompt
Per TestingCatalog, Claude’s internal Hub build asks for feedback the moment a user switches back to a normal chat. Anthropic hasn’t announced the mode, which the site reads as presumably a task orchestrator.
Related stories
- OpenAI ships an official CLI for its REST API
- OpenAI sends GPT-4o users to Luna ahead of 2027 retirement
- OpenAI’s Decisions API beats its own engine by up to 10x
- OpenAI’s Decisions API picks an answer in 150 milliseconds
- ChatGPT’s new Mac memory watches what you do, without screenshots
- Claude Code on desktop folds an iPhone Duo to test layouts
Comments
No comments yet. Be the first.
Join the conversation
Sign in to leave a comment. It appears after moderation.

