The OpenAI Python SDK has migrated from HTTPX to HTTPX2 for its synchronous and asynchronous HTTP clients, according to the migration guide. HTTPX2 is installed automatically with the SDK, and the previous httpx package is no longer required.
For most applications using the SDK without custom HTTP client configuration, the change is transparent. According to the guide, existing API calls, parsed response models, streaming APIs, authentication, retries, and numeric timeouts continue to work without modification. Applications that previously imported httpx only because the SDK installed it transitively will need to either add their own httpx dependency or migrate those imports to httpx2.
A significant change involves TLS certificate verification. HTTPX2 modifies the default trust store behavior. Previously, HTTPX verified certificates against the CA bundle provided by certifi. HTTPX2 instead uses the operating-system trust store, and the SDK no longer installs certifi. According to the guide, this change can break certificate verification in minimal container images without system CA certificates, environments using corporate TLS-inspecting proxies, and deployments that relied on a custom or modified certifi bundle.
The guide provides solutions for these cases. Applications can install required CA certificates in the operating-system trust store, or configure an explicit certificate bundle using environment variables like SSL_CERT_FILE or SSL_CERT_DIR when trust_env is True. Alternatively, developers can configure an ssl.SSLContext and pass it through the verify parameter when constructing a DefaultHttpx2Client.
For applications with custom HTTP client configurations, the migration requires updating HTTPX-specific objects to their HTTPX2 equivalents. These include httpx.Client becoming httpx2.Client, httpx.Timeout becoming httpx2.Timeout, and httpx.HTTPTransport becoming httpx2.HTTPTransport, among others.
Authentication handlers and hooks must be updated to receive HTTPX2 request and response objects. Custom auth classes and type annotations require corresponding updates. Third-party instrumentation, tracing middleware, and auth integrations must explicitly support HTTPX2.
For testing, mocks must intercept HTTPX2 requests and return HTTPX2 responses. The guide notes that test suites using RESPX must update to an HTTPX2-compatible version. An escape hatch exists for legacy HTTPX-only libraries: applications can explicitly install legacy HTTPX and inject a legacy client, though this requires type-checking workarounds.
Key facts
- OpenAI Python SDK now uses HTTPX2 for HTTP clients, replacing HTTPX
- HTTPX2 changes default TLS verification from certifi CA bundle to operating-system trust store
- Existing API calls and configurations work without changes if no custom HTTP client is provided
- Custom HTTP client code must update HTTPX objects to HTTPX2 equivalents
- Certificate verification may break in minimal container images without system CA certificates