SIGN IN SIGN UP

feat(api)!: migrate to HTTPX2 (#3594)

Makes HTTPX2 the default HTTP client for the next major Python SDK
release. See the [HTTPX Migration
Guide](https://github.com/openai/openai-python/blob/2e4a69261f6c2b7c9038a4ff34d2a329d3680417/httpx2.md)
for complete customer-facing migration instructions.

## Customer migration

- **Default clients:** `OpenAI()` and `AsyncOpenAI()` use HTTPX2
automatically; API calls, parsed responses, streaming, retries,
authentication, and numeric timeouts retain their existing interfaces.
- **Dependencies:** `pip install openai` installs HTTPX2 instead of
HTTPX. Applications importing `httpx` through the SDK's former
transitive dependency must migrate to `httpx2` or install `httpx`
explicitly.
- **TLS trust store:** HTTPX2 uses the operating-system trust store
instead of `certifi`. This can break certificate verification even with
the default client; configure the system trust store, `SSL_CERT_FILE`,
`SSL_CERT_DIR`, or a custom `ssl.SSLContext` as needed.
- **Custom HTTP integrations:** Migrate custom clients, transports,
timeout objects, authentication handlers, hooks, request mocks, and
instrumentation to their HTTPX2 equivalents. Raw requests, responses,
and transport exceptions are now HTTPX2 objects.
- **aiohttp:** `openai[aiohttp]` and `DefaultAioHttpClient()` remain
supported through an HTTPX2-native transport without installing HTTPX or
`httpx-aiohttp`.
- **Legacy escape hatch:** Explicitly installed `httpx.Client`,
`httpx.AsyncClient`, and `httpx-aiohttp` clients remain supported when
passed through `http_client`. **This compatibility is runtime-only;
legacy clients are not supported by static type checkers such as mypy or
Pyright.** Legacy HTTPX support is provided as a migration aid and may
be discontinued.

See
[httpx2.md](https://github.com/openai/openai-python/blob/2e4a69261f6c2b7c9038a4ff34d2a329d3680417/httpx2.md)
for examples and detailed migration cases.

## Implementation notes

- Replace the SDK’s default clients and HTTP-facing types with HTTPX2.
- Test legacy HTTPX and aiohttp compatibility separately, including a
real request through the legacy aiohttp adapter.

**Vendored dependencies**
We've vendored a few dependencies in so that we can avoid installing
`httpx` by default for both normal dependencies and dev dependencies.
This was the fastest path to unblock migration; we are happy to upstream
these changes if it makes sense for those package's dependencies.

- Fork RESPX under `tests/respx2` so existing request-mocking tests work
without HTTPX.
   - This is for convenience so we can mechanically rewrite tests.
- Vendor the upstream HTTPX2 aiohttp adapter, including its original
license and attribution.
   - This is to avoid `aiohttp` bringing in `httpx` by default for now. 

**Issues**
- https://github.com/openai/openai-python/issues/3375

Co-authored-by: apcha-oai <228803254+apcha-oai@users.noreply.github.com>
A
Alex Chang committed
ae8c3d5d8be96c8253e5875e7c79b646a0c239d6
Parent: 03b3ec4
Committed by GitHub <noreply@github.com> on 8/12/2026, 1:35:14 AM