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

Raised by _connect_ws when importing the WebSocket transport (openai.lib._websocket) fails because the `websockets` dependency is not installed. The realtime-style Responses WebSocket API is an optional extra, so the SDK tells you to install openai[realtime].

Source

Thrown at src/openai/resources/responses/responses.py:4414

            initial_delay=self.__initial_delay,
            max_delay=self.__max_delay,
            extra_query=self.__extra_query,
            extra_headers=self.__extra_headers,
            send_queue=self.__send_queue,
        )

        self.__event_handler_registry.merge_into(self.__connection._event_handler_registry)
        await self.__connection._flush_send_queue()

        return self.__connection

    enter = __aenter__

    async def _connect_ws(self, extra_query: Query, extra_headers: Headers) -> AsyncWebSocketConnection:
        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

        url = self._prepare_url().copy_with(
            params={
                **self.__client.base_url.params,
                **extra_query,
            },
        )
        log.debug("Connecting to WebSocket API")
        if self.__websocket_connection_options:
            log.debug("Custom WebSocket connection options provided")

        return await connect(
            str(url),
            user_agent_header=self.__client.user_agent,
            additional_headers=_merge_mappings(
                {
                    **self.__client.auth_headers,
                },

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Install the extra: pip install 'openai[realtime]' (or uv add 'openai[realtime]')
  2. Add websockets to requirements/pyproject alongside openai
  3. Rebuild the Docker image/deployment package to include the extra

Example fix

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

Strategy: validation

Validate before calling

try:
    import websockets  # noqa: F401
    ws_ok = True
except ImportError:
    ws_ok = False
if not ws_ok:
    raise RuntimeError("install 'openai[realtime]' before using WebSocket APIs")

Type guard

def realtime_available() -> bool:
    try:
        import websockets  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

from openai import OpenAIError
try:
    conn = await client.responses._connect_ws(q, h)
except OpenAIError as e:
    if 'openai[realtime]' in str(e):
        raise SystemExit("Run: pip install 'openai[realtime]'") from e
    raise

Prevention

When it happens

Trigger: Calling client.responses.websocket or any WS-connecting method in an environment where `pip install openai` was done without extras and no websockets package is present.

Common situations: Slim Docker images installing only openai; deploying to serverless/Lambda layers that strip optional deps; CI environments missing extras; upgrading the SDK and adopting the WS API without adding the extra.

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

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