OpenAI Python SDK Migration to HTTPX2
The OpenAI Python SDK now utilizes HTTPX2 for both synchronous and asynchronous HTTP clients. This change ensures that the SDK is built against a stable API, avoiding the breaking changes expected in the upcoming HTTPX 1.0 release. While HTTPX2 is installed automatically with the openai package, the legacy httpx package is no longer a transitive dependency.
TLS Certificate Verification and Trust Stores
The most critical change for most users is the shift in how TLS certificates are verified. HTTPX2 uses the operating system's trust store by default, whereas the previous HTTPX implementation relied on the certifi CA bundle.
This transition may cause certificate verification failures in the following environments:
- Minimal container images that lack system CA certificates.
- Environments utilizing corporate TLS-inspecting proxies.
- Deployments that previously relied on a modified or custom
certifibundle.
To resolve these issues, users should install the required CA certificates into the OS trust store or configure an explicit certificate bundle using environment variables:
SSL_CERT_FILE=/path/to/ca-bundle.pemSSL_CERT_DIR=/path/to/ca-directory
For granular control, an ssl.SSLContext can be passed through the verify parameter using DefaultHttpx2Client or DefaultAsyncHttpx2Client.
Impact on Default and Custom HTTP Clients
Default Client Usage
For users who construct OpenAI or AsyncOpenAI clients without providing a custom http_client, existing API calls, streaming, authentication, and timeouts remain functional without additional configuration.
Custom Client Configuration
Users providing a custom HTTP client must now use HTTPX2 clients and configuration objects. The SDK provides helper classes to maintain recommended defaults for connection pools and timeouts:
DefaultHttpx2Client: For synchronous clients.DefaultAsyncHttpx2Client: For asynchronous clients.
Directly constructed httpx2.Client and httpx2.AsyncClient instances are also supported. While the legacy names DefaultHttpxClient and DefaultAsyncHttpxClient still function, they now instantiate HTTPX2 clients under the hood.
API Mapping and Object Replacements
When migrating custom implementations, replace legacy httpx objects with their httpx2 equivalents:
| Previous Object | HTTPX2 Object |
|---|---|
httpx.Client |
httpx2.Client |
httpx.AsyncClient |
httpx2.AsyncClient |
httpx.Timeout |
httpx2.Timeout |
httpx.URL |
httpx2.URL |
httpx.Limits |
httpx2.Limits |
httpx.HTTPTransport |
httpx2.HTTPTransport |
httpx.AsyncHTTPTransport |
httpx2.AsyncHTTPTransport |
httpx.MockTransport |
httpx2.MockTransport |
Raw Responses and Exception Handling
When using a native HTTPX2 client, transport-facing objects—such as those returned by with_raw_response—are instances of httpx2.Response and httpx2.Request.
Application code should continue to catch SDK-level exceptions (e.g., openai.APITimeoutError and openai.APIConnectionError). However, the underlying transport cause for these exceptions will now be an HTTPX2 exception rather than an HTTPX one.
Testing and Request Mocking
Mocks must now intercept HTTPX2 requests and return HTTPX2 responses. If a test suite relies on RESPX, users must update to an HTTPX2-compatible version or fork the library, as versions patching only legacy HTTPX cannot intercept the SDK's default HTTPX2 client.
Compatibility and the Legacy Escape Hatch
For applications that cannot immediately migrate from an HTTPX-only transport or mocking library, the SDK provides a runtime-only escape hatch. By explicitly installing httpx and injecting a legacy client, users can maintain existing functionality:
from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
Note that this approach fails static type checking (mypy, Pyright) and requires cast(Any, ...) or type-ignores. This legacy support is a temporary migration aid and may be discontinued.
Community Insights
Industry peers have noted that this shift is not unique to OpenAI; Anthropic has implemented a similar change. The primary driver is the instability of the httpx dependency as it approaches a 1.0 release, which is expected to introduce significant breaking changes.
The httpx2 project is essentially a fork that promises not to break the existing API, which makes it a more stable dependency to build against.
Other developers have suggested alternatives for high-performance needs, such as Rust-based pyqwest, though the SDK's current implementation is standardized on HTTPX2.
Sources
Related
- Project
- Dispatch
- Dispatch
- Project