openai/openai-python · error · RuntimeError

To use the aiohttp client you must have installed the packag

Error message

To use the aiohttp client you must have installed the package with the `aiohttp` extra

What it means

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.

Source

Thrown at src/openai/_base_client.py:1473

class _DefaultAsyncHttpxClient(httpx2.AsyncClient):
    def __init__(self, **kwargs: Any) -> None:
        kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
        kwargs.setdefault("limits", DEFAULT_CONNECTION_LIMITS)
        kwargs.setdefault("follow_redirects", True)
        super().__init__(**kwargs)


_DefaultAioHttpClient: type[httpx2.AsyncClient]

try:
    from ._vendor.httpx_aiohttp import Httpx2AiohttpClient
except ImportError:

    class _MissingAioHttpClient(httpx2.AsyncClient):
        def __init__(self, **_kwargs: Any) -> None:
            raise RuntimeError("To use the aiohttp client you must have installed the package with the `aiohttp` extra")

    _DefaultAioHttpClient = _MissingAioHttpClient
else:

    class _InstalledAioHttpClient(Httpx2AiohttpClient):
        def __init__(self, **kwargs: Any) -> None:
            kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
            kwargs.setdefault("limits", DEFAULT_CONNECTION_LIMITS)
            kwargs.setdefault("follow_redirects", True)
            super().__init__(**kwargs)

    _DefaultAioHttpClient = _InstalledAioHttpClient


if TYPE_CHECKING:
    DefaultAsyncHttpxClient = httpx2.AsyncClient
    """An alias to `httpx2.AsyncClient` that provides the same defaults that this SDK
    uses internally.

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Install the extra: `pip install 'openai[aiohttp]'` (or add `openai[aiohttp]` to your dependency list and reinstall)
2. Or pass an explicit `http_client=httpx2.AsyncClient(...)` to `OpenAI`/`AsyncOpenAI` to use a non-aiohttp transport
3. Verify the install with `python -c "from openai._vendor.httpx_aiohttp import Httpx2AiohttpClient"`

Example fix

# before
import openai
client = openai.AsyncOpenAI()  # RuntimeError: aiohttp extra missing

# after (shell)
pip install 'openai[aiohttp]'

try:
    from openai._vendor.httpx_aiohttp import Httpx2AiohttpClient  # noqa: F401
    aiohttp_ok = True
except ImportError:
    aiohttp_ok = False
if not aiohttp_ok:
    raise SystemExit("Install with: pip install 'openai[aiohttp]'")

try:
    client = AsyncOpenAI()
except RuntimeError as e:
    if 'aiohttp extra' in str(e):
        raise SystemExit("Missing optional dependency: pip install 'openai[aiohttp]'") from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• max_retries cannot be None. If you want to disable retries,
• Unexpected JSON data type, {type(json_data)}, cannot merge w
• Expected query input to be a dictionary for multipart reques
• Passing both `content` and `json_data` is not supported
• Passing both `body` and `content` is not supported

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/b82ac1d8debb896c. Report an issue: GitHub.