Transitioning to HTTPX2

The OpenAI Python SDK has officially migrated its synchronous and asynchronous HTTP client implementations to HTTPX2.

While openai now automatically installs httpx2, it no longer installs the legacy httpx package. This guide outlines the necessary adjustments for developers interacting with the SDK's underlying HTTP layer.

🛠️ Impact Assessment

For Users of the Default HTTP Client

If you initialize OpenAI or AsyncOpenAI without specifying a custom http_client, your workflow remains largely unchanged. The following features continue to function as expected:

• Standard API requests and parsed response models.
• Streaming interfaces.
• Authentication mechanisms and retry logic.
• Numeric timeout settings.

from openai import OpenAI

# Numeric timeouts still work perfectly
client = OpenAI(timeout=30.0)
response = client.create(model="gpt-5.5", input="Hello")

Installation Note: No additional steps are needed beyond pip install openai. However, if your project relied on httpx because it was a transitive dependency of the SDK, you must now either:

1. Explicitly add httpx to your dependencies.
2. Migrate your imports to httpx2.

---

🔐 TLS Certificates and Trust Stores

HTTPX2 introduces a significant change in how TLS trust stores are handled, affecting all users, including those using the default client.

[!WARNING] Breaking Change: HTTPX previously relied on the certifi CA bundle. HTTPX2 now defaults to the operating-system trust store. Consequently, the SDK no longer installs certifi.

This shift may cause certificate verification failures in the following scenarios:

• Minimal container images lacking system CA certificates.
• Corporate environments utilizing TLS-inspecting proxies.
• Deployments relying on modified certifi bundles.

Resolution Strategies

You can resolve these issues by installing CA certificates into the OS trust store or by defining explicit bundles via environment variables:

• export SSL_CERT_FILE=/path/to/ca-bundle.pem
• export SSL_CERT_DIR=/path/to/ca-directory

These variables are processed when $\text{trust\_env} = \text{True}$ (the default setting).

Explicit SSL Configuration

To manually control trust via a custom client, pass an ssl.SSLContext to the verify parameter:

import ssl
from openai import OpenAI, DefaultHttpx2Client

# Create a custom SSL context
ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")

# Apply it to the client
client = OpenAI(
    http_client=DefaultHttpx2Client(verify=ssl_context)
)

Note: Use DefaultAsyncHttpx2Client(verify=ssl_context) for asynchronous setups. The SDK's aiohttp transport follows these same TLS rules.

---

⚙️ Custom HTTP Client Configuration

If you provide your own client, you must now use HTTPX2 clients and configuration objects. The SDK provides helper classes to ensure that recommended defaults for connection pools, redirects, and timeouts are maintained.

Implementation Example

import httpx2
from openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client

# 1. Using a proxy
proxy_client = OpenAI(
    http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080")
)

# 2. Custom transport and granular timeouts
transport_client = OpenAI(
    http_client=DefaultHttpx2Client(
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
        timeout=httpx2.Timeout(30.0, connect=5.0),
    )
)

# 3. Async configuration
async_client = AsyncOpenAI(
    http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0))
)

Client Compatibility Matrix

• DefaultHttpx2Client / DefaultAsyncHttpx2Client: Recommended (Explicitly HTTPX2).
• DefaultHttpxClient / DefaultAsyncHttpxClient: Supported (Legacy names that now instantiate HTTPX2).
• httpx2.Client / httpx2.AsyncClient: Supported (Uses standard HTTPX2 defaults instead of SDK defaults).

Architecture Flow

---

🔄 Object Mapping and API Changes

When updating your code, replace all httpx specific objects with their httpx2 counterparts:

Example of granular timeout migration:

import httpx2
from openai import OpenAI

client = OpenAI(
    timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0)
)

---

🛠️ Advanced Integrations

Authentication and Event Hooks

All authentication handlers and event hooks now receive httpx2 request and response objects. Ensure your type annotations and custom classes are updated.

import httpx2
from openai import OpenAI, DefaultHttpx2Client

def log_request(request: httpx2.Request):
    print(f"Requesting: {request.url}")

client = OpenAI(
    http_client=DefaultHttpx2Client(
        event_hooks={"request": [log_request]}
    )
)

Important: Any third-party tracing middleware, instrumentation, or custom transport subclasses must be updated to target the httpx2 interfaces.

Responses, Streaming, and Errors

While the SDK's parsed response models remain identical, the underlying transport objects have changed:

1. Raw Responses: To obtain an unparsed response, use cast_to=httpx2.Response.
2. Streaming: Response wrappers now expose httpx2 response objects.
3. Exception Handling: Continue to catch SDK-level exceptions (e.g., openai.APITimeoutError) rather than transport-specific ones.

For further details, refer to the official httpx2 documentation.