HTTPX2 becomes the default in OpenAI's Python SDK

The OpenAI Python SDK has switched its synchronous and asynchronous HTTP clients to HTTPX2, which now installs automatically with the package while the previous httpx dependency does not. The migration guide in the SDK repository on Github states that applications using the default client keep their existing behaviour, while the change to TLS trust can break certificate verification.

At a glance

• HTTPX2 verifies certificates against the operating-system trust store rather than the certifi bundle, and the SDK no longer installs certifi, so minimal container images and TLS-inspecting corporate proxies can fail.
• Applications that construct OpenAI or AsyncOpenAI without passing http_client keep their existing calls, parsed response models, streaming APIs, authentication, retries and numeric timeouts, with no extra installation beyond pip install openai.
• Custom transports, auth classes, event hooks and mocking setups must move to httpx2 equivalents; test suites built on RESPX need an HTTPX2-compatible version or fork to intercept the default client.

The dependency change is small on paper and large in production. Certificate verification is the one behaviour that changes for applications that never touched the HTTP layer, and it fails at runtime, inside containers and behind inspecting proxies, rather than at install time. The rest of the migration is mechanical, but it likely lands hardest on test suites and observability stacks, where third-party libraries have to add HTTPX2 support before anything can be intercepted.

The SDK no longer installs httpx or certifi, and TLS trust moves to the operating-system store

Installing the SDK no longer brings httpx or certifi along. Applications that imported httpx only because an earlier release installed it transitively need an explicit httpx dependency of their own, or those imports moved to httpx2. No HTTPX2 extra or separate installation is required.

HTTPX previously verified certificates against the CA bundle shipped by certifi; HTTPX2 uses the operating-system trust store instead. The guide names three failure modes: minimal container images without system CA certificates, environments with TLS-inspecting corporate proxies, and deployments that relied on a custom or modified certifi bundle.

The fix is to install the required CA certificates into the system trust store, or to point the runtime at an explicit bundle through SSL_CERT_FILE or at a directory through SSL_CERT_DIR. Both variables are honoured while trust_env is True, the default. A custom client can take an ssl.SSLContext through the verify argument of DefaultHttpx2Client or DefaultAsyncHttpx2Client, and the SDK's aiohttp transport uses the same HTTPX2 TLS settings.

Existing DefaultHttpxClient names now construct HTTPX2 clients

Applications that inject their own client must use HTTPX2 objects. DefaultHttpx2Client and DefaultAsyncHttpx2Client preserve the SDK's recommended timeout, connection-pool and redirect defaults; directly constructed httpx2.Client and httpx2.AsyncClient instances also work, with HTTPX2's own defaults. Module-level configuration follows the same rule through openai.http_client.

The object rename is one-to-one: httpx.Client, httpx.AsyncClient, httpx.Timeout, httpx.URL, httpx.Limits, httpx.HTTPTransport, httpx.AsyncHTTPTransport and httpx.MockTransport map to their httpx2 counterparts. Numeric timeout values and string URLs are untouched. Authentication handlers and event hooks now receive httpx2.Request and httpx2.Response objects, so custom auth classes, transport subclasses and connection-pool instrumentation have to target HTTPX2 interfaces.

Parsed SDK response models are unchanged. With a native HTTPX2 client, with_raw_response returns httpx2.Response and httpx2.Request objects, cast_to=httpx2.Response requests an unparsed response, and the transport cause behind openai.APITimeoutError or openai.APIConnectionError is an HTTPX2 exception. Mocks must intercept HTTPX2 requests and return HTTPX2 responses through httpx2.MockTransport, and RESPX suites need an HTTPX2-compatible version or fork, since a release patching only legacy HTTPX cannot intercept the default client.

Legacy HTTPX runs at runtime but fails mypy and Pyright

Applications tied to an HTTPX-only transport, integration or mocking library can install httpx themselves and inject a legacy client. Support is runtime-only: the SDK's public type annotations accept HTTPX2 clients, so passing httpx.Client or httpx.AsyncClient fails static checking in mypy and Pyright unless wrapped in cast(Any, ...) or a targeted type-ignore.

A legacy client keeps the HTTPX request, response and exception families, and raw responses must be requested as httpx.Response; passing cast_to=httpx2.Response does not convert them. The same path covers existing httpx-aiohttp setups through HttpxAiohttpClient, which OpenAI covers with dedicated compatibility tests, including a real request through the aiohttp transport.

The supported aiohttp path is HTTPX2-native. Installing the openai[aiohttp] extra brings in neither legacy HTTPX nor the external httpx-aiohttp adapter, and DefaultAioHttpClient is itself an httpx2.AsyncClient, so applications that use that helper do not construct or import the aiohttp transport directly.

Whether the legacy path survives The guide states that legacy HTTPX support is provided as a migration aid and may be discontinued, and that applications choosing it install and maintain the httpx dependency themselves. No removal date or SDK version is named for that deprecation. For new code, OpenAI points at openai[aiohttp] and DefaultAioHttpClient rather than the httpx-aiohttp escape hatch.