huggingface/smolagents · error · ModuleNotFoundError

Please install 'openai' extra to use OpenAIModel: `pip insta

Error message

Please install 'openai' extra to use OpenAIModel: `pip install 'smolagents[openai]'`

What it means

OpenAIModel.create_client imports the openai package; if it is missing, the ModuleNotFoundError is re-raised with instructions to install the `openai` extra. The class definition itself doesn't require openai, but constructing the model does.

Source

Thrown at src/smolagents/models.py:1701

        self.client_kwargs = {
            **(client_kwargs or {}),
            "api_key": api_key,
            "base_url": api_base,
            "organization": organization,
            "project": project,
        }
        super().__init__(
            model_id=model_id,
            custom_role_conversions=custom_role_conversions,
            flatten_messages_as_text=flatten_messages_as_text,
            **kwargs,
        )

    def create_client(self):
        try:
            import openai
        except ModuleNotFoundError as e:
            raise ModuleNotFoundError(
                "Please install 'openai' extra to use OpenAIModel: `pip install 'smolagents[openai]'`"
            ) from e

        return openai.OpenAI(**self.client_kwargs)

    def generate_stream(
        self,
        messages: list[ChatMessage | dict],
        stop_sequences: list[str] | None = None,
        response_format: dict[str, str] | None = None,
        tools_to_call_from: list[Tool] | None = None,
        **kwargs,
    ) -> Generator[ChatMessageStreamDelta]:
        completion_kwargs = self._prepare_completion_kwargs(
            messages=messages,
            stop_sequences=stop_sequences,
            response_format=response_format,
            tools_to_call_from=tools_to_call_from,

View on GitHub (pinned to 30bb116109)

Solutions

Install the extra: `pip install 'smolagents[openai]'` (equivalent to adding openai).
Confirm with `python -c "import openai"` in the interpreter you actually run.
Add the extra to requirements/pyproject so environments are reproducible.

Example fix

# before
pip install smolagents
model = OpenAIModel(model_id="qwen2.5", api_base="http://localhost:11434/v1")  # ModuleNotFoundError

# after
pip install 'smolagents[openai]'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import openai  # noqa
    ok = True
except ModuleNotFoundError:
    ok = False
assert ok, "pip install 'smolagents[openai]'"

Type guard

null

Try / catch

try:
    model = OpenAIModel(model_id=mid, api_base=url)
except ModuleNotFoundError as e:
    print("Install the extra:", e)
    sys.exit(1)

Prevention

Put smolagents[openai] in requirements for any OpenAI-compatible usage.
Add a startup dependency check for optional SDKs.

When it happens

Trigger: Instantiating OpenAIModel (create_client is called from __init__) in an environment where the openai package is not installed — i.e. `pip install smolagents` without extras.

Common situations: Base smolagents install used with a custom OpenAI-compatible endpoint (vLLM, Ollama, LM Studio); slim Docker/CI images; stale lockfiles; wrong virtualenv activated.

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 huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/8264fca8a7053040. Report an issue: GitHub.