{"record":{"id":"b82ac1d8debb896c","repo":"openai/openai-python","slug":"to-use-the-aiohttp-client-you-must-have-installed","errorCode":null,"errorMessage":"To use the aiohttp client you must have installed the package with the `aiohttp` extra","messagePattern":"To use the aiohttp client you must have installed the package with the `aiohttp` extra","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/openai/_base_client.py","lineNumber":1473,"sourceCode":"\n\nclass _DefaultAsyncHttpxClient(httpx2.AsyncClient):\n    def __init__(self, **kwargs: Any) -> None:\n        kwargs.setdefault(\"timeout\", DEFAULT_TIMEOUT)\n        kwargs.setdefault(\"limits\", DEFAULT_CONNECTION_LIMITS)\n        kwargs.setdefault(\"follow_redirects\", True)\n        super().__init__(**kwargs)\n\n\n_DefaultAioHttpClient: type[httpx2.AsyncClient]\n\ntry:\n    from ._vendor.httpx_aiohttp import Httpx2AiohttpClient\nexcept ImportError:\n\n    class _MissingAioHttpClient(httpx2.AsyncClient):\n        def __init__(self, **_kwargs: Any) -> None:\n            raise RuntimeError(\"To use the aiohttp client you must have installed the package with the `aiohttp` extra\")\n\n    _DefaultAioHttpClient = _MissingAioHttpClient\nelse:\n\n    class _InstalledAioHttpClient(Httpx2AiohttpClient):\n        def __init__(self, **kwargs: Any) -> None:\n            kwargs.setdefault(\"timeout\", DEFAULT_TIMEOUT)\n            kwargs.setdefault(\"limits\", DEFAULT_CONNECTION_LIMITS)\n            kwargs.setdefault(\"follow_redirects\", True)\n            super().__init__(**kwargs)\n\n    _DefaultAioHttpClient = _InstalledAioHttpClient\n\n\nif TYPE_CHECKING:\n    DefaultAsyncHttpxClient = httpx2.AsyncClient\n    \"\"\"An alias to `httpx2.AsyncClient` that provides the same defaults that this SDK\n    uses internally.","sourceCodeStart":1455,"sourceCodeEnd":1491,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/_base_client.py#L1455-L1491","documentation":"The SDK's optional aiohttp transport lives in the `aiohttp` extra (a vendored httpx_aiohttp bridge). When `http_client` is not supplied and the aiohttp transport is selected (e.g. via environment or default configuration), the SDK falls back to a stub class whose __init__ always raises this RuntimeError if the extra was never installed.","triggerScenarios":"Constructing an async client that resolves to the aiohttp transport without having installed `openai[aiohttp]`; installing the bare `openai` package and relying on the aiohttp engine; CI images that strip optional dependencies.","commonSituations":"Pinning `openai` without extras in requirements.txt; a base Docker image that omits extra deps; upgrading to an SDK version where aiohttp became the optional async default transport.","solutions":["Install the extra: `pip install 'openai[aiohttp]'` (or add `openai[aiohttp]` to your dependency list and reinstall)","Or pass an explicit `http_client=httpx2.AsyncClient(...)` to `OpenAI`/`AsyncOpenAI` to use a non-aiohttp transport","Verify the install with `python -c \"from openai._vendor.httpx_aiohttp import Httpx2AiohttpClient\"`"],"exampleFix":"# before\nimport openai\nclient = openai.AsyncOpenAI()  # RuntimeError: aiohttp extra missing\n\n# after (shell)\npip install 'openai[aiohttp]'","handlingStrategy":"validation","validationCode":"try:\n    from openai._vendor.httpx_aiohttp import Httpx2AiohttpClient  # noqa: F401\n    aiohttp_ok = True\nexcept ImportError:\n    aiohttp_ok = False\nif not aiohttp_ok:\n    raise SystemExit(\"Install with: pip install 'openai[aiohttp]'\")","typeGuard":null,"tryCatchPattern":"try:\n    client = AsyncOpenAI()\nexcept RuntimeError as e:\n    if 'aiohttp extra' in str(e):\n        raise SystemExit(\"Missing optional dependency: pip install 'openai[aiohttp]'\") from e\n    raise","preventionTips":["Declare `openai[aiohttp]` (not bare `openai`) in dependency manifests when using the aiohttp transport","Add a startup smoke test that constructs the async client before serving traffic"],"tags":["aiohttp","extras","dependency","async","runtime-error"],"backgroundTag":"missing-optional-dependency","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}