openai/openai-python · error · OpenAIError

You need to install `openai[realtime]` to use this method

Error message

You need to install `openai[realtime]` to use this method

What it means

The async Realtime session `__aenter__` imports the websocket helper from `openai.lib._websocket`, which depends on the optional `websockets` package. If the `[realtime]` extra is not installed, the ImportError is re-raised as OpenAIError telling you to install `openai[realtime]`.

Source

Thrown at src/openai/resources/beta/realtime/realtime.py:357

        self.__websocket_connection_options = websocket_connection_options

    async def __aenter__(self) -> AsyncRealtimeConnection:
        """
        👋 If your application doesn't work well with the context manager approach then you
        can call this method directly to initiate a connection.

        **Warning**: You must remember to close the connection with `.close()`.

        ```py
        connection = await client.beta.realtime.connect(...).enter()
        # ...
        await connection.close()
        ```
        """
        try:
            from ....lib._websocket import _WebSocketConnect as connect
        except ImportError as exc:
            raise OpenAIError("You need to install `openai[realtime]` to use this method") from exc

        extra_query = self.__extra_query
        await self.__client._refresh_api_key()
        auth_headers = self.__client.auth_headers
        if is_async_azure_client(self.__client):
            from ....lib._azure_websocket import _AzureWebSocketConnect as connect

            url, auth_headers = await self.__client._configure_realtime(self.__model, extra_query)
        else:
            url = self._prepare_url().copy_with(
                params={
                    **self.__client.base_url.params,
                    "model": self.__model,
                    **extra_query,
                },
            )
        log.debug("Connecting to WebSocket API")
        if self.__websocket_connection_options:

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Install the extra: `pip install 'openai[realtime]'` (or `uv add 'openai[realtime]'`)
2. Verify `python -c "import websockets"` succeeds in the runtime environment
3. Rebuild deployment images to include extras and pin versions

Example fix

# before
pip install openai
# after
pip install 'openai[realtime]'

try:
    from websockets.asyncio.client import connect  # noqa: F401
    realtime_ok = True
except ImportError:
    realtime_ok = False

import importlib.util

def realtime_available() -> bool:
    return importlib.util.find_spec("websockets") is not None

from openai import OpenAIError
try:
    async with client.beta.realtime.connect(model="gpt-4o-realtime-preview") as rt:
        ...
except OpenAIError as e:
    if "openai[realtime]" in str(e):
        raise RuntimeError("Install extra: pip install 'openai[realtime]'") from e
    raise

When it happens

Trigger: Using `async with client.beta.realtime.connect(model=...) as rt:` without the websockets dependency installed (realtime.py:357).

Common situations: Installing plain `openai` instead of `openai[realtime]`; slim Docker/CI images that strip optional deps; upgrading the SDK without reinstalling extras.

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

• You need to install `openai[realtime]` to use this method
• You need to install `openai[realtime]` to use this method
• MissingStreamClassError
• WebSocket connection closed with unsent messages
• WebSocket error: {event}

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