Glonce

OpenAI's Python SDK migrates to HTTPX2, changing TLS trust store

toolsThe Glonce editorsHacker News🔥57Glonce rating57Impact48Novelty38Relevance63Surprise32Players75Credibility88
OpenAI's Python SDK migrates to HTTPX2, changing TLS trust store

OpenAI has published a migration guide describing a change to the HTTP layer of its openai Python SDK: the synchronous and asynchronous clients now use a library called HTTPX2 by default instead of HTTPX. HTTPX2 is installed automatically with the openai package, and the previous httpx package is no longer installed as a dependency; a plain pip install openai is enough, with no extra package required. Applications that build an OpenAI or AsyncOpenAI client without passing a custom http_client are unaffected in behavior: existing API calls, parsed response models, streaming, authentication, retries, and numeric timeouts keep working exactly as before. Anything that imported httpx only because it arrived transitively through the SDK now needs to add that dependency itself, or migrate those imports to httpx2.

The guide flags one default behavior change that affects even applications using the SDK's default client: certificate verification. HTTPX previously verified certificates against the CA bundle supplied by the certifi package. HTTPX2 instead verifies against the operating system's trust store, and the SDK no longer installs certifi. The guide states this can break certificate verification in minimal container images that lack system CA certificates, in environments that use corporate TLS-inspecting proxies, and in deployments that relied on a custom or modified certifi bundle. The fix is to install the needed CA certificates into the OS trust store, or to point the client at a certificate bundle explicitly through the SSL_CERT_FILE or SSL_CERT_DIR environment variables, or by passing an ssl.SSLContext through the verify argument on a custom DefaultHttpx2Client or DefaultAsyncHttpx2Client.

For code that configures a custom HTTP client directly, such as a proxy, a custom transport, or event hooks, the guide says to replace HTTPX-specific objects with their HTTPX2 equivalents (httpx2.HTTPTransport, httpx2.Timeout, and so on). The existing DefaultHttpxClient and DefaultAsyncHttpxClient names still work, but now construct HTTPX2 clients rather than HTTPX ones; the guide recommends using the DefaultHttpx2Client and DefaultAsyncHttpx2Client names going forward to make the HTTP client family explicit in code. Authentication handlers, hooks, and raw-response access now receive HTTPX2 request and response objects when a native HTTPX2 client is used; these type guarantees apply only to native HTTPX2 clients, and an injected legacy HTTPX client instead produces httpx.Request, httpx.Response, and HTTPX transport exceptions, even if the code requests cast_to=httpx2.Response. The supported aiohttp extra (pip install 'openai[aiohttp]') also uses an HTTPX2-native transport and does not install legacy HTTPX or the external httpx-aiohttp adapter.

Test suites are directly affected: mocks must now intercept HTTPX2 requests and return HTTPX2 responses, and a RESPX version that only patches legacy HTTPX cannot intercept the SDK's default HTTPX2 client. For teams that cannot migrate their HTTPX-only tooling immediately, the guide documents a temporary escape hatch: explicitly installing legacy httpx (or httpx-aiohttp) alongside openai and injecting a legacy client with cast(Any, httpx.Client()), since the SDK's public type annotations now expect HTTPX2 clients and passing a legacy client directly fails static type checking in mypy or Pyright. The guide is explicit that this legacy-client support is runtime-only, is meant as a migration aid, and may be discontinued.

Key facts

  • The openai Python SDK now installs HTTPX2 by default for its sync and async HTTP clients, and stops installing the previous httpx package as a dependency.
  • HTTPX2 verifies TLS certificates against the operating system trust store instead of the certifi bundle that HTTPX used, and the SDK no longer installs certifi.
  • The guide warns this can break certificate verification in minimal container images without system CA certificates, in corporate TLS-inspecting proxy setups, and in deployments relying on a custom certifi bundle.
  • Code that never passes a custom http_client keeps working unchanged; custom transports, proxies, auth hooks, and mocks need to be updated to HTTPX2 objects.
  • A temporary compatibility path lets applications inject a legacy HTTPX client via cast(Any, httpx.Client()), but the guide says this runtime-only support may be discontinued.

Why it matters

This is a default-dependency and default-behavior change in one of the most widely used AI SDKs. Swapping the underlying HTTP client library is normally invisible to callers, but here it changes what gets installed (httpx and certifi drop out, HTTPX2 comes in automatically) and quietly changes how TLS certificates are checked, from a bundled certifi list to whatever certificates the host operating system trusts.

Who it affects

Anyone using the openai Python package, most directly applications that construct a custom http_client, run in minimal or stripped-down container images without a populated OS certificate store, sit behind corporate proxies that intercept TLS, or previously depended on httpx being installed transitively through openai. Test suites that mock HTTP calls with RESPX or similar tools are also affected, since a RESPX setup built for legacy HTTPX cannot intercept the new default HTTPX2 client.

How to use it

Default usage needs no changes: pip install openai pulls in HTTPX2 automatically, and calls, streaming, auth, retries, and numeric timeouts behave the same. If certificate verification breaks, install the required CA certificates into the OS trust store, or set SSL_CERT_FILE or SSL_CERT_DIR, or pass an ssl.SSLContext through verify on DefaultHttpx2Client or DefaultAsyncHttpx2Client. Custom transports, proxies, and event hooks should use httpx2 objects (httpx2.HTTPTransport, httpx2.Timeout) instead of the old httpx ones; DefaultHttpxClient and DefaultAsyncHttpxClient still work but now build HTTPX2 clients. Teams not yet ready to migrate can install httpx explicitly and inject it with cast(Any, httpx.Client()), or install httpx-aiohttp the same way for the async aiohttp integration, as a documented but temporary escape hatch.

How solid is it

The source is OpenAI's own migration guide in the openai-python GitHub repository, discussed on Hacker News. It is a first-party, instructional document rather than a blog post or announcement: it carries no named author or company spokesperson, gives no version number for HTTPX2 itself, states no date for when the migration took effect, and offers no stated rationale for the switch beyond the described change in default TLS trust store, with no performance, security, or maintenance benefit claimed for HTTPX2 over HTTPX.

Risks and caveats

The trust-store change is the main operational risk: it can silently break TLS in minimal container images, corporate proxy environments, and setups that relied on a custom certifi bundle, since verification now depends on what the OS considers trusted rather than a bundled list. Type checkers such as mypy and Pyright will reject a legacy HTTPX client passed directly, forcing a cast(Any, ...) workaround, and a RESPX-based test suite built only for legacy HTTPX can fail to intercept requests under the new default without an update. The guide also states that legacy HTTPX support is runtime-only and may be discontinued, without giving a timeline.