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 WebSocket connection helper for BetaResponses failed to import the websockets library, which is an optional dependency shipped under the `realtime` extra. Without it the SDK cannot open the ws:// connection and raises OpenAIError before any network activity.

Source

Thrown at src/openai/resources/beta/responses/responses.py:4519

            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]' / poetry add 'openai[realtime]')
  2. Rebuild/refresh the environment after installation (uv sync --extra realtime, recreate the venv)
  3. Verify with python -c "import websockets" that the dependency is present

Example fix

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

Strategy: validation

Validate before calling

try:
    import websockets  # noqa: F401
except ImportError:
    raise SystemExit("Install with: pip install 'openai[realtime]'")

Prevention

When it happens

Trigger: Using the async BetaResponses WebSocket (client.beta.responses.connect(...)) without `websockets` installed, e.g. after installing plain `openai` instead of `openai[realtime]`, or in a slim Docker image that prunes extras.

Common situations: Distroless/minimal containers, dependency resolution dropping extras, teams upgrading openai and not noticing the realtime feature moved behind an optional 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/732cdcc1d93119e7. Report an issue: GitHub.