OpenAI Python SDK migrates to HTTPX2, altering TLS trust and custom client setups

What changed

The OpenAI Python SDK has moved its synchronous and asynchronous HTTP clients from HTTPX to HTTPX2, according to a migration guide published in the openai-python repository and surfaced on the Hacker News front page. The httpx2 package installs automatically with openai; the previous httpx package no longer does.

The guide splits the fallout into two camps: applications that use the SDK's default client, and those that pass a custom HTTP client. Default-client users are largely unaffected — API calls, parsed response models, streaming APIs, authentication, retries, and numeric timeouts keep working with no extra installation.

The dependency you may not have known you had

One immediate break affects code that imported httpx only because an earlier version of the SDK pulled it in transitively. The guide tells those applications to declare httpx as a direct dependency or migrate the imports to httpx2, since installing the SDK no longer provides httpx for them.

TLS trust now comes from the operating system

The change with the widest blast radius has nothing to do with custom clients. HTTPX previously verified certificates against the CA bundle from certifi; HTTPX2 instead uses the operating system's trust store, and the SDK no longer installs certifi at all. This applies even to applications using the default client.

The guide calls out three scenarios where verification can fail: minimal container images without system CA certificates, environments behind corporate TLS-inspecting proxies, and deployments that relied on a custom or modified certifi bundle. Remedies include installing the needed CA certificates into the operating-system trust store, or pointing the SSL_CERT_FILE and SSL_CERT_DIR environment variables at an explicit bundle or directory. Both variables are honored when trust_env is enabled, which is the default. For explicit control, applications can pass an ssl.SSLContext through the verify argument of DefaultHttpx2Client or DefaultAsyncHttpx2Client, and the SDK's aiohttp transport shares the same TLS settings.

Custom clients, hooks, and raw responses

Applications that inject their own HTTP client must switch to HTTPX2 clients and configuration objects: httpx2.Client, httpx2.AsyncClient, httpx2.Timeout, httpx2.URL, httpx2.Limits, and the transport classes replace their httpx counterparts. The SDK provides DefaultHttpx2Client and DefaultAsyncHttpx2Client helpers that preserve its recommended timeout, connection-pool, and redirect defaults, while the older DefaultHttpxClient names still work but now construct HTTPX2 clients. Numeric timeout values and string URLs are unchanged.

Authentication handlers and event hooks now receive HTTPX2 request and response objects, so custom auth subclasses and type annotations need updating, and third-party instrumentation or tracing middleware must add explicit HTTPX2 support. Parsed response models are untouched, but raw-response code sees httpx2.Response and httpx2.Request objects on a native client, with HTTPX2 exceptions sitting underneath SDK errors such as openai.APIConnectionError and openai.APITimeoutError. The aiohttp extra now uses an HTTPX2-native transport without installing legacy HTTPX or the external httpx-aiohttp adapter, and its DefaultAioHttpClient helper is an httpx2.AsyncClient.

Tests, mocking, and the escape hatch

Test suites get particular attention. Mocks must intercept HTTPX2 requests and return HTTPX2 responses, and RESPX users must upgrade to an HTTPX2-compatible version, because a RESPX release that patches only legacy HTTPX cannot intercept the SDK's default client.

For teams that cannot migrate right away, the guide documents a runtime-only escape hatch: install legacy httpx explicitly and inject a legacy httpx.Client or httpx.AsyncClient. Because the SDK's public type annotations accept only HTTPX2 clients, this path fails static checks in mypy and Pyright and requires a cast to Any or a targeted type-ignore. Legacy clients keep the old request, response, and exception families while migration is in progress.

Why it matters

This is a breaking change delivered through the transport layer of one of the most widely installed Python packages, and the TLS shift means even untouched code can fail in production — particularly in slim container images that never shipped system CA certificates. It also previews ecosystem-wide friction: mocking, tracing, and authentication tooling built on HTTPX will need HTTPX2 support as more libraries follow suit. Teams should audit for transitive httpx imports, verify certificate handling in their deployment images, and decide soon whether to migrate fully or lean on the temporary legacy path.