OpenAI Python SDK Migrates to HTTPX2
Key changes and migration guide for the new HTTP client
1Significance of HTTPX2 Migration
The OpenAI Python SDK has adopted HTTPX2 as its HTTP client, bringing changes to TLS certificate verification and default connection settings. HTTPX2 now uses the operating system's trust store, eliminating the certifi dependency. This transition requires careful attention in container environments and corporate proxy scenarios, where custom certificate configurations might be necessary.
2Automatic Migration Scenarios
Existing OpenAI clients created without http_client parameters continue to work seamlessly with API calls, response models, and streaming APIs. HTTPX2 is automatically installed with the openai package, requiring no additional setup. However, applications directly using httpx need to explicitly add this dependency, as it's no longer transitively included by the SDK.
3TLS Verification Changes
The certificate verification mechanism has significantly changed in the new version. The operating system's trust store is now used by default, and the certifi package is no longer automatically installed. This may require setting SSL_CERT_FILE or SSL_CERT_DIR environment variables in environments using custom CAs. Alternatively, custom configurations can be made using SSLContext objects.
4Custom HTTP Client Configuration
Developers can customize proxy, timeout, and connection pool settings using DefaultHttpx2Client and DefaultAsyncHttpx2Client helpers. HTTPX2's Timeout and HTTPTransport objects can be used directly. While native httpx2.Client and httpx2.AsyncClient instances are supported, using the helper classes is recommended to maintain the SDK's default configurations.
5Backward Compatibility
The DefaultHttpxClient and DefaultAsyncHttpxClient names still work but now create HTTPX2 clients. New code should explicitly use the HTTPX2 versions. Timeout values and URL formats remain unchanged, but custom transport subclasses and auth handlers need updating to target HTTPX2 interfaces. Third-party instrumentation must explicitly support HTTPX2.
6Response and Error Handling
SDK response models remain unchanged, but when using native HTTPX2 clients, http_response and http_request objects will be of HTTPX2 type. The cast_to=httpx2.Response parameter can be used for raw HTTP responses. Streaming response wrappers also expose HTTPX2 response objects. Applications should catch SDK exceptions like openai.APITimeoutError rather than relying on transport-level exceptions.
7Migration Considerations
Container environments must ensure system CA certificates are present. Corporate TLS inspection proxies may require custom certificate configurations. Applications using custom certifi bundles should either update the OS trust store or set SSL_CERT_FILE. Interactions with other HTTPX-dependent libraries should be verified. Custom transport implementations need updating to HTTPX2 interfaces.
8Performance and Security Benefits
The HTTPX2 migration provides a more consistent security model through OS-level TLS integration. Connection pool and timeout management improvements enhance stability for long-lived connections. The update offers a more consistent interface for custom transport implementations while providing greater flexibility for proxy and custom network configurations.
Original article: Hacker News (news.ycombinator.com) — OpenAI Python SDK'da HTTPX2'ye Geçiş