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