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 when the async Realtime websocket connect cannot import the optional `websockets` dependency. The Realtime API requires the `openai[realtime]` extra; without it, _connect_ws raises OpenAIError with install instructions.

Source

Thrown at src/openai/resources/realtime/realtime.py:687

            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

        await self.__client._refresh_api_key()
        auth_headers = self.__client.auth_headers
        if self.__call_id is not omit:
            extra_query = {**extra_query, "call_id": self.__call_id}
        if is_async_azure_client(self.__client):
            from ...lib._azure_websocket import _AzureWebSocketConnect as connect

            model = self.__model
            if not model:
                raise OpenAIError("`model` is required for Azure Realtime API")
            else:
                url, auth_headers = await self.__client._configure_realtime(model, extra_query)
        else:
            url = self._prepare_url().copy_with(
                params={
                    **self.__client.base_url.params,
                    **({"model": self.__model} if self.__model is not omit else {}),

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Install the extra: pip install "openai[realtime]" (or uv add "openai[realtime]" / poetry add "openai[realtime]")
2. Verify with `python -c "import websockets"` that the dependency now resolves
3. Pin the extra in requirements.txt/pyproject so environments stay consistent

Example fix

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

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

try:
    async with client.beta.realtime.connect(model=m) as conn: ...
except OpenAIError as e:
    if "openai[realtime]" in str(e):
        subprocess check / install instructions

When it happens

Trigger: Entering `async with client.beta.realtime.connect(...)` (or lower-level Realtime context managers) on an environment where openai was installed without the [realtime] extra.

Common situations: Fresh environments with plain `pip install openai`, CI images, slim Docker containers, or upgrading from a setup that previously had websockets installed transitively.

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
• WebSocket connection closed with unsent messages
• WebSocket error: {event}
• `model` is required for Azure Realtime API

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