{"slug": "openai-migrating-to-httpx2", "title": "OpenAI: Migrating to HTTPX2", "summary": "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.", "body_md": "The OpenAI Python SDK now uses [HTTPX2](https://httpx2.pydantic.dev/) for its\nsynchronous and asynchronous HTTP clients. HTTPX2 is installed automatically\nwith `openai`\n\n; the previous `httpx`\n\npackage is not. This guide explains what\nchanges for applications that interact with the SDK's HTTP layer.\n\nIf you construct an `OpenAI`\n\nor\n`AsyncOpenAI`\n\nclient without providing `http_client`\n\n, your existing API calls,\nparsed response models, streaming APIs, authentication, retries, and numeric\ntimeouts continue to work:\n\n``` python\nfrom openai import OpenAI\n\nclient = OpenAI(timeout=30.0)\nresponse = client.responses.create(model=\"gpt-5.5\", input=\"Hello\")\n```\n\nNo HTTPX2 extra or separate installation is required:\n\n```\npip install openai\n```\n\nIf your application imported `httpx`\n\nonly because an earlier SDK installed it\ntransitively, add your own `httpx`\n\ndependency or migrate those imports to\n`httpx2`\n\n. Installing the SDK no longer installs `httpx`\n\nfor you.\n\n**HTTPX2 changes the default TLS trust store, including for applications that\nuse the SDK's default HTTP client.** HTTPX previously verified certificates\nagainst the CA bundle provided by `certifi`\n\n. HTTPX2 instead uses the\noperating-system trust store, and the SDK no longer installs `certifi`\n\n.\n\nThis can break certificate verification in minimal container images without\nsystem CA certificates, environments using corporate TLS-inspecting proxies,\nand deployments that relied on a custom or modified `certifi`\n\nbundle. Install\nthe required CA certificates in the operating-system trust store, or configure\nan explicit certificate bundle:\n\n```\nexport SSL_CERT_FILE=/path/to/ca-bundle.pem\n```\n\nAlternatively, configure a directory of trusted CA certificates:\n\n```\nexport SSL_CERT_DIR=/path/to/ca-directory\n```\n\nThese environment variables are honored when `trust_env=True`\n\n, which is the\ndefault. To control trust explicitly on a custom client, pass an\n`ssl.SSLContext`\n\nthrough `verify`\n\n:\n\n``` python\nimport ssl\nfrom openai import OpenAI, DefaultHttpx2Client\n\nssl_context = ssl.create_default_context(cafile=\"/path/to/ca-bundle.pem\")\nclient = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))\n```\n\nUse `DefaultAsyncHttpx2Client(verify=ssl_context)`\n\nfor the equivalent async\nconfiguration. The SDK's aiohttp transport uses the same HTTPX2 TLS settings.\n\nUse HTTPX2 clients and HTTPX2 configuration objects. The SDK provides helpers that preserve its recommended timeout, connection-pool, and redirect defaults:\n\n``` python\nimport httpx2\nfrom openai import OpenAI, AsyncOpenAI, DefaultHttpx2Client, DefaultAsyncHttpx2Client\n\nproxy_client = OpenAI(http_client=DefaultHttpx2Client(proxy=\"http://proxy.example.com:8080\"))\n\ntransport_client = OpenAI(\n    http_client=DefaultHttpx2Client(\n        transport=httpx2.HTTPTransport(local_address=\"0.0.0.0\"),\n        timeout=httpx2.Timeout(30.0, connect=5.0),\n    )\n)\n\nasync_client = AsyncOpenAI(http_client=DefaultAsyncHttpx2Client(timeout=httpx2.Timeout(30.0)))\n```\n\nDirectly constructed `httpx2.Client`\n\nand `httpx2.AsyncClient`\n\ninstances are\nalso supported. When you construct a client directly, its own HTTPX2 defaults\napply unless you configure them yourself.\n\nThe existing `DefaultHttpxClient`\n\nand `DefaultAsyncHttpxClient`\n\nnames continue\nto work, but now construct HTTPX2 clients. Prefer `DefaultHttpx2Client`\n\nand\n`DefaultAsyncHttpx2Client`\n\nwhen making the HTTP client family explicit.\n\nModule-level configuration follows the same rule:\n\n``` python\nimport openai\n\nopenai.http_client = openai.DefaultHttpx2Client()\n```\n\nReplace HTTPX-specific objects with the corresponding HTTPX2 objects:\n\n| Previous object | HTTPX2 object |\n|---|---|\n`httpx.Client` |\n`httpx2.Client` |\n`httpx.AsyncClient` |\n`httpx2.AsyncClient` |\n`httpx.Timeout` |\n`httpx2.Timeout` |\n`httpx.URL` |\n`httpx2.URL` |\n`httpx.Limits` |\n`httpx2.Limits` |\n`httpx.HTTPTransport` |\n`httpx2.HTTPTransport` |\n`httpx.AsyncHTTPTransport` |\n`httpx2.AsyncHTTPTransport` |\n`httpx.MockTransport` |\n`httpx2.MockTransport` |\n\nFor example, a granular SDK timeout becomes:\n\n``` python\nimport httpx2\nfrom openai import OpenAI\n\nclient = OpenAI(timeout=httpx2.Timeout(60.0, connect=5.0, read=20.0))\n```\n\nNumeric 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.\n\nAuthentication handlers and hooks receive HTTPX2 request and response objects. Update custom auth classes and annotations accordingly:\n\n``` python\nimport httpx2\nfrom openai import OpenAI, DefaultHttpx2Client\n\ndef log_request(request: httpx2.Request) -> None:\n    print(request.method, request.url)\n\nclient = OpenAI(http_client=DefaultHttpx2Client(event_hooks={\"request\": [log_request]}))\n```\n\nIf you subclass an HTTP authentication or transport interface, subclass the\nmatching `httpx2`\n\nclass. Third-party instrumentation, tracing middleware, and\nauth integrations must explicitly support HTTPX2.\n\nParsed SDK response models are unchanged. When using a native HTTPX2 client, transport-facing objects belong to HTTPX2:\n\n``` python\nimport httpx2\nfrom openai import OpenAI\n\nclient = OpenAI()\nresponse = client.models.with_raw_response.list()\n\nassert isinstance(response.http_response, httpx2.Response)\nassert isinstance(response.http_request, httpx2.Request)\n```\n\nWith a native client, use `cast_to=httpx2.Response`\n\nwhen requesting an unparsed\nHTTP response. Streaming response wrappers also expose HTTPX2 response objects.\nApplication code should usually catch SDK exceptions such as\n`openai.APITimeoutError`\n\nand `openai.APIConnectionError`\n\n; with a native client,\nan exception's underlying transport cause is an HTTPX2 exception.\n\nThese type guarantees apply only to native HTTPX2 clients. An injected legacy\nHTTPX client produces `httpx.Request`\n\n, `httpx.Response`\n\n, and HTTPX transport\nexceptions instead, even if `cast_to=httpx2.Response`\n\nis supplied.\n\nThe supported aiohttp extra uses an HTTPX2-native transport. It does not\ninstall legacy HTTPX or the external `httpx-aiohttp`\n\nadapter:\n\n```\npip install 'openai[aiohttp]'\npython\nfrom openai import AsyncOpenAI, DefaultAioHttpClient\n\nclient = AsyncOpenAI(http_client=DefaultAioHttpClient())\n```\n\n`DefaultAioHttpClient()`\n\nis an `httpx2.AsyncClient`\n\n. Applications using this\nhelper do not need to construct or import the transport directly.\n\nMocks must intercept HTTPX2 requests and return HTTPX2 responses. For example:\n\n``` python\nimport httpx2\nfrom openai import OpenAI\n\ndef handler(request: httpx2.Request) -> httpx2.Response:\n    return httpx2.Response(\n        200,\n        request=request,\n        json={\"object\": \"list\", \"data\": []},\n    )\n\nclient = OpenAI(http_client=httpx2.Client(transport=httpx2.MockTransport(handler)))\nassert client.models.list().data == []\n```\n\nIf 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.\n\nApplications that depend on an HTTPX-only transport, integration, or mocking library can explicitly install legacy HTTPX and inject a legacy client:\n\n```\npip install openai httpx\n```\n\n**Legacy HTTPX support is runtime-only.** The SDK's public type annotations\naccept HTTPX2 clients, so passing a legacy client directly fails static type\nchecking in mypy, Pyright, and similar tools. Use `cast(Any, ...)`\n\nor a\ntargeted type-ignore when deliberately choosing this compatibility path:\n\n``` python\nfrom typing import Any, cast\n\nimport httpx\nfrom openai import OpenAI\n\nclient = OpenAI(http_client=cast(Any, httpx.Client()))\n```\n\nThe asynchronous form requires the same workaround:\n\n``` python\nfrom typing import Any, cast\n\nimport httpx\nfrom openai import AsyncOpenAI\n\nclient = AsyncOpenAI(http_client=cast(Any, httpx.AsyncClient()))\n```\n\nLegacy clients preserve the HTTPX request, response, and exception families.\nRequest raw responses as `httpx.Response`\n\n, using the same type-checking\nworkaround for the legacy response class:\n\n``` python\nfrom typing import Any, cast\n\nimport httpx\nfrom openai import OpenAI\n\nclient = OpenAI(http_client=cast(Any, httpx.Client()))\nresponse = client.get(\"/models\", cast_to=cast(Any, httpx.Response))\n\nassert isinstance(response, httpx.Response)\n```\n\nPassing `cast_to=httpx2.Response`\n\ndoes not convert a legacy HTTPX response into\nan HTTPX2 response. Install and maintain the legacy dependency yourself.\nLegacy HTTPX support is provided as a migration aid and may be discontinued.\n\nIf you must retain an existing `httpx-aiohttp`\n\nintegration, install it\nexplicitly and inject its legacy client:\n\n```\npip install openai httpx-aiohttp\npython\nfrom typing import Any, cast\n\nfrom httpx_aiohttp import HttpxAiohttpClient\nfrom openai import AsyncOpenAI\n\nclient = AsyncOpenAI(http_client=cast(Any, HttpxAiohttpClient()))\n```\n\nThis path is covered by dedicated compatibility tests, including a real\nrequest through the aiohttp transport, but remains a temporary escape hatch.\nPrefer `openai[aiohttp]`\n\nand `DefaultAioHttpClient()`\n\nfor new code.", "url": "https://wpnews.pro/news/openai-migrating-to-httpx2", "canonical_source": "https://github.com/openai/openai-python/blob/main/httpx2.md", "published_at": "2026-08-28 11:51:20+00:00", "updated_at": "2026-08-28 12:18:39.438247+00:00", "lang": "en", "topics": ["developer-tools", "ai-infrastructure"], "entities": ["OpenAI", "HTTPX2", "httpx", "certifi", "DefaultHttpx2Client", "DefaultAsyncHttpx2Client", "DefaultHttpxClient", "DefaultAsyncHttpxClient"], "alternates": {"html": "https://wpnews.pro/news/openai-migrating-to-httpx2", "markdown": "https://wpnews.pro/news/openai-migrating-to-httpx2.md", "text": "https://wpnews.pro/news/openai-migrating-to-httpx2.txt", "jsonld": "https://wpnews.pro/news/openai-migrating-to-httpx2.jsonld"}}