OpenAI: Migrating to HTTPX2

OpenAI's Python SDK now uses HTTPX2 for its synchronous and asynchronous HTTP clients, replacing the previous httpx package, which is no longer installed automatically. The migration changes the default TLS trust store to the operating-system trust store instead of certifi, which can break certificate verification in minimal container images or corporate proxy environments unless CA certificates are installed or SSL_CERT_FILE/SSL_CERT_DIR are set. Developers should use HTTPX2 objects like httpx2.Client and DefaultHttpx2Client, while legacy DefaultHttpxClient names still work but now construct HTTPX2 clients.

The OpenAI Python SDK now uses HTTPX2 https://httpx2.pydantic.dev/ for its synchronous and asynchronous HTTP clients. HTTPX2 is installed automatically with openai ; the previous httpx package is not. This guide explains what changes for applications that interact with the SDK's HTTP layer. If you construct an OpenAI or AsyncOpenAI client without providing http client , your existing API calls, parsed response models, streaming APIs, authentication, retries, and numeric timeouts continue to work: python from openai import OpenAI client = OpenAI timeout=30.0 response = client.responses.create model="gpt-5.5", input="Hello" No HTTPX2 extra or separate installation is required: pip install openai If your application imported httpx only because an earlier SDK installed it transitively, add your own httpx dependency or migrate those imports to httpx2 . Installing the SDK no longer installs httpx for you. HTTPX2 changes the default TLS trust store, including for applications that use the SDK's default HTTP client. HTTPX previously verified certificates against the CA bundle provided by certifi . HTTPX2 instead uses the operating-system trust store, and the SDK no longer installs certifi . This 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. Install the required CA certificates in the operating-system trust store, or configure an explicit certificate bundle: export SSL CERT FILE=/path/to/ca-bundle.pem Alternatively, configure a directory of trusted CA certificates: export SSL CERT DIR=/path/to/ca-directory These environment variables are honored when trust env=True , which is the default. To control trust explicitly on a custom client, pass an ssl.SSLContext through verify : python import ssl from openai import OpenAI, DefaultHttpx2Client ssl context = ssl.create default context cafile="/path/to/ca-bundle.pem" client = OpenAI http client=DefaultHttpx2Client verify=ssl context Use DefaultAsyncHttpx2Client verify=ssl context for the equivalent async configuration. The SDK's aiohttp transport uses the same HTTPX2 TLS settings. Use HTTPX2 clients and HTTPX2 configuration objects. The SDK provides helpers that preserve its recommended timeout, connection-pool, and redirect defaults: python import httpx2 from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client proxy client = OpenAI http client=DefaultHttpx2Client proxy="http://proxy.example.com:8080" transport client = OpenAI http client=DefaultHttpx2Client transport=httpx2.HTTPTransport local address="0.0.0.0" , timeout=httpx2.Timeout 30.0, connect=5.0 , async client = AsyncOpenAI http client=DefaultAsyncHttpx2Client timeout=httpx2.Timeout 30.0 Directly constructed httpx2.Client and httpx2.AsyncClient instances are also supported. When you construct a client directly, its own HTTPX2 defaults apply unless you configure them yourself. The existing DefaultHttpxClient and DefaultAsyncHttpxClient names continue to work, but now construct HTTPX2 clients. Prefer DefaultHttpx2Client and DefaultAsyncHttpx2Client when making the HTTP client family explicit. Module-level configuration follows the same rule: python import openai openai.http client = openai.DefaultHttpx2Client Replace HTTPX-specific objects with the corresponding HTTPX2 objects: | Previous object | HTTPX2 object | |---|---| httpx.Client | httpx2.Client | httpx.AsyncClient | httpx2.AsyncClient | httpx.Timeout | httpx2.Timeout | httpx.URL | httpx2.URL | httpx.Limits | httpx2.Limits | httpx.HTTPTransport | httpx2.HTTPTransport | httpx.AsyncHTTPTransport | httpx2.AsyncHTTPTransport | httpx.MockTransport | httpx2.MockTransport | For example, a granular SDK timeout becomes: python import httpx2 from openai import OpenAI client = OpenAI timeout=httpx2.Timeout 60.0, connect=5.0, read=20.0 Numeric timeout values do not change. Existing string URLs do not change. Custom transport subclasses, mounted transports, proxy integrations, and connection-pool instrumentation must target HTTPX2's transport interfaces. Authentication handlers and hooks receive HTTPX2 request and response objects. Update custom auth classes and annotations accordingly: python import httpx2 from openai import OpenAI, DefaultHttpx2Client def log request request: httpx2.Request - None: print request.method, request.url client = OpenAI http client=DefaultHttpx2Client event hooks={"request": log request } If you subclass an HTTP authentication or transport interface, subclass the matching httpx2 class. Third-party instrumentation, tracing middleware, and auth integrations must explicitly support HTTPX2. Parsed SDK response models are unchanged. When using a native HTTPX2 client, transport-facing objects belong to HTTPX2: python import httpx2 from openai import OpenAI client = OpenAI response = client.models.with raw response.list assert isinstance response.http response, httpx2.Response assert isinstance response.http request, httpx2.Request With a native client, use cast to=httpx2.Response when requesting an unparsed HTTP response. Streaming response wrappers also expose HTTPX2 response objects. Application code should usually catch SDK exceptions such as openai.APITimeoutError and openai.APIConnectionError ; with a native client, an exception's underlying transport cause is an HTTPX2 exception. These type guarantees apply only to native HTTPX2 clients. An injected legacy HTTPX client produces httpx.Request , httpx.Response , and HTTPX transport exceptions instead, even if cast to=httpx2.Response is supplied. The supported aiohttp extra uses an HTTPX2-native transport. It does not install legacy HTTPX or the external httpx-aiohttp adapter: pip install 'openai aiohttp ' python from openai import AsyncOpenAI, DefaultAioHttpClient client = AsyncOpenAI http client=DefaultAioHttpClient DefaultAioHttpClient is an httpx2.AsyncClient . Applications using this helper do not need to construct or import the transport directly. Mocks must intercept HTTPX2 requests and return HTTPX2 responses. For example: python import httpx2 from openai import OpenAI def handler request: httpx2.Request - httpx2.Response: return httpx2.Response 200, request=request, json={"object": "list", "data": }, client = OpenAI http client=httpx2.Client transport=httpx2.MockTransport handler assert client.models.list .data == If your test suite uses RESPX, update to an HTTPX2-compatible RESPX version or fork. A RESPX version that patches only legacy HTTPX cannot intercept the SDK's default HTTPX2 client. If you cannot migrate that integration immediately, the temporary legacy-client escape hatch below lets existing HTTPX-only RESPX setups continue to work while you migrate. Applications that depend on an HTTPX-only transport, integration, or mocking library can explicitly install legacy HTTPX and inject a legacy client: pip install openai httpx Legacy HTTPX support is runtime-only. The SDK's public type annotations accept HTTPX2 clients, so passing a legacy client directly fails static type checking in mypy, Pyright, and similar tools. Use cast Any, ... or a targeted type-ignore when deliberately choosing this compatibility path: python from typing import Any, cast import httpx from openai import OpenAI client = OpenAI http client=cast Any, httpx.Client The asynchronous form requires the same workaround: python from typing import Any, cast import httpx from openai import AsyncOpenAI client = AsyncOpenAI http client=cast Any, httpx.AsyncClient Legacy clients preserve the HTTPX request, response, and exception families. Request raw responses as httpx.Response , using the same type-checking workaround for the legacy response class: python from typing import Any, cast import httpx from openai import OpenAI client = OpenAI http client=cast Any, httpx.Client response = client.get "/models", cast to=cast Any, httpx.Response assert isinstance response, httpx.Response Passing cast to=httpx2.Response does not convert a legacy HTTPX response into an HTTPX2 response. Install and maintain the legacy dependency yourself. Legacy HTTPX support is provided as a migration aid and may be discontinued. If you must retain an existing httpx-aiohttp integration, install it explicitly and inject its legacy client: pip install openai httpx-aiohttp python from typing import Any, cast from httpx aiohttp import HttpxAiohttpClient from openai import AsyncOpenAI client = AsyncOpenAI http client=cast Any, HttpxAiohttpClient This path is covered by dedicated compatibility tests, including a real request through the aiohttp transport, but remains a temporary escape hatch. Prefer openai aiohttp and DefaultAioHttpClient for new code.