OpenAI: Migrating to HTTPX2

Aug 28, 2026 06:51 PM - 6 days ago 10

The OpenAI Python SDK now uses HTTPX2 for its synchronous and asynchronous HTTP clients. HTTPX2 is installed automatically with openai; the erstwhile httpx package is not. This guideline explains what changes for applications that interact pinch the SDK's HTTP layer.

If you usage the SDK's default HTTP client

If you conception an OpenAI or AsyncOpenAI customer without providing http_client, your existing API calls, parsed consequence models, streaming APIs, authentication, retries, and numeric timeouts proceed to work:

from openai import OpenAI client = OpenAI(timeout=30.0) response = client.responses.create(model="gpt-5.5", input="Hello")

No HTTPX2 other aliases abstracted installation is required:

If your exertion imported httpx only because an earlier SDK installed it transitively, adhd your ain httpx dependency aliases migrate those imports to httpx2. Installing the SDK nary longer installs httpx for you.

TLS certificates and spot stores

HTTPX2 changes the default TLS spot store, including for applications that use the SDK's default HTTP client. HTTPX antecedently verified certificates against the CA bundle provided by certifi. HTTPX2 alternatively uses the operating-system spot store, and the SDK nary longer installs certifi.

This tin break certificate verification successful minimal instrumentality images without system CA certificates, environments utilizing firm TLS-inspecting proxies, and deployments that relied connected a civilization aliases modified certifi bundle. Install the required CA certificates successful the operating-system spot store, aliases configure an definitive 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 situation variables are honored erstwhile trust_env=True, which is the default. To power spot explicitly connected a civilization client, walk an ssl.SSLContext done verify:

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 balanced async configuration. The SDK's aiohttp carrier uses the aforesaid HTTPX2 TLS settings.

If you supply a civilization HTTP client

Use HTTPX2 clients and HTTPX2 configuration objects. The SDK provides helpers that sphere its recommended timeout, connection-pool, and redirect defaults:

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 conception a customer directly, its ain HTTPX2 defaults apply unless you configure them yourself.

The existing DefaultHttpxClient and DefaultAsyncHttpxClient names continue to work, but now conception HTTPX2 clients. Prefer DefaultHttpx2Client and DefaultAsyncHttpx2Client erstwhile making the HTTP customer family explicit.

Module-level configuration follows the aforesaid rule:

import openai openai.http_client = openai.DefaultHttpx2Client()

Timeouts, URLs, transports, and relationship settings

Replace HTTPX-specific objects pinch 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:

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 drawstring URLs do not change. Custom carrier subclasses, mounted transports, proxy integrations, and connection-pool instrumentation must target HTTPX2's carrier interfaces.

Authentication and arena hooks

Authentication handlers and hooks person HTTPX2 petition and consequence objects. Update civilization auth classes and annotations accordingly:

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 aliases carrier interface, subclass the matching httpx2 class. Third-party instrumentation, tracing middleware, and auth integrations must explicitly support HTTPX2.

Raw responses, streaming, and exceptions

Parsed SDK consequence models are unchanged. When utilizing a autochthonal HTTPX2 client, transport-facing objects beryllium to HTTPX2:

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 autochthonal client, usage cast_to=httpx2.Response erstwhile requesting an unparsed HTTP response. Streaming consequence wrappers besides expose HTTPX2 consequence objects. Application codification should usually drawback SDK exceptions specified as openai.APITimeoutError and openai.APIConnectionError; pinch a autochthonal client, an exception's underlying carrier origin is an HTTPX2 exception.

These type guarantees use only to autochthonal HTTPX2 clients. An injected legacy HTTPX customer produces httpx.Request, httpx.Response, and HTTPX transport exceptions instead, moreover if cast_to=httpx2.Response is supplied.

The supported aiohttp other uses an HTTPX2-native transport. It does not install bequest HTTPX aliases the outer httpx-aiohttp adapter:

pip instal 'openai[aiohttp]'

from openai import AsyncOpenAI, DefaultAioHttpClient client = AsyncOpenAI(http_client=DefaultAioHttpClient())

DefaultAioHttpClient() is an httpx2.AsyncClient. Applications utilizing this helper do not request to conception aliases import the carrier directly.

Request mocking and tests

Mocks must intercept HTTPX2 requests and return HTTPX2 responses. For example:

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 trial suite uses RESPX, update to an HTTPX2-compatible RESPX type or fork. A RESPX type that patches only bequest HTTPX cannot intercept the SDK's default HTTPX2 client. If you cannot migrate that integration immediately, the temporary legacy-client flight hatch beneath lets existing HTTPX-only RESPX setups proceed to activity while you migrate.

Temporary flight hatch: a bequest HTTPX client

Applications that dangle connected an HTTPX-only transport, integration, aliases mocking library tin explicitly instal bequest HTTPX and inject a bequest client:

Legacy HTTPX support is runtime-only. The SDK's nationalist type annotations accept HTTPX2 clients, truthful passing a bequest customer straight fails fixed type checking successful mypy, Pyright, and akin tools. Use cast(Any, ...) aliases a targeted type-ignore erstwhile deliberately choosing this compatibility path:

from typing import Any, cast import httpx from openai import OpenAI client = OpenAI(http_client=cast(Any, httpx.Client()))

The asynchronous shape requires the aforesaid workaround:

from typing import Any, cast import httpx from openai import AsyncOpenAI client = AsyncOpenAI(http_client=cast(Any, httpx.AsyncClient()))

Legacy clients sphere the HTTPX request, response, and objection families. Request earthy responses arsenic httpx.Response, utilizing the aforesaid type-checking workaround for the bequest consequence class:

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 person a bequest HTTPX consequence into an HTTPX2 response. Install and support the bequest dependency yourself. Legacy HTTPX support is provided arsenic a migration assistance and whitethorn beryllium discontinued.

Existing bequest aiohttp adapters

If you must clasp an existing httpx-aiohttp integration, instal it explicitly and inject its bequest client:

pip instal openai httpx-aiohttp

from typing import Any, cast from httpx_aiohttp import HttpxAiohttpClient from openai import AsyncOpenAI client = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient()))

This way is covered by dedicated compatibility tests, including a real request done the aiohttp transport, but remains a impermanent flight hatch. Prefer openai[aiohttp] and DefaultAioHttpClient() for caller code.