huggingface/smolagents · error · ModuleNotFoundError

Please install 'litellm' extra to use LiteLLMRouterModel: `p

Error message

Please install 'litellm' extra to use LiteLLMRouterModel: `pip install 'smolagents[litellm]'`

What it means

LiteLLMRouterModel.create_client tries to import litellm.router.Router; the ModuleNotFoundError is caught and re-raised with a friendly message telling you the `litellm` optional extra is not installed. smolagents keeps heavy provider SDKs optional, so the class is importable but unusable without the extra.

Source

Thrown at src/smolagents/models.py:1450

        flatten_messages_as_text: bool | None = None,
        **kwargs,
    ):
        self.client_kwargs = {
            "model_list": model_list,
            **(client_kwargs or {}),
        }
        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:
            from litellm.router import Router
        except ModuleNotFoundError as e:
            raise ModuleNotFoundError(
                "Please install 'litellm' extra to use LiteLLMRouterModel: `pip install 'smolagents[litellm]'`"
            ) from e
        return Router(**self.client_kwargs)


class InferenceClientModel(ApiModel):
    """A class to interact with Hugging Face's Inference Providers for language model interaction.

    This model allows you to communicate with Hugging Face's models using Inference Providers. It can be used in both serverless mode, with a dedicated endpoint, or even with a local URL, supporting features like stop sequences and grammar customization.

    Providers include Cerebras, Cohere, Fal, Fireworks, HF-Inference, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together, and more.

    Parameters:
        model_id (`str`, *optional*, default `"Qwen/Qwen3-Next-80B-A3B-Thinking"`):
            The Hugging Face model ID to be used for inference.
            This can be a model identifier from the Hugging Face model hub or a URL to a deployed Inference Endpoint.
            Currently, it defaults to `"Qwen/Qwen3-Next-80B-A3B-Thinking"`, but this may change in the future.
        provider (`str`, *optional*):

View on GitHub (pinned to 30bb116109)

Solutions

Install the extra: `pip install 'smolagents[litellm]'` (or plain `pip install litellm`).
Verify the active environment: `python -c "import litellm"` in the same interpreter you run the app from.
Pin litellm in requirements/pyproject once installed so builds stay reproducible.

Example fix

# before
pip install smolagents
model = LiteLLMRouterModel(...)  # ModuleNotFoundError: install 'litellm' extra

# after
pip install 'smolagents[litellm]'

Defensive patterns

Strategy: validation

Validate before calling

try:
    import litellm.router  # noqa
    can_use = True
except ModuleNotFoundError:
    can_use = False
assert can_use, "pip install 'smolagents[litellm]'"

Type guard

null

Try / catch

try:
    model = LiteLLMRouterModel(...)
except ModuleNotFoundError as e:
    print("Missing extra:", e)
    sys.exit(1)

Prevention

Declare extras in requirements: smolagents[litellm].
Add an environment check step in CI that imports optional deps your code uses.

When it happens

Trigger: Instantiating LiteLLMRouterModel (which calls create_client from __init__) in an environment where the litellm package is absent, e.g. `pip install smolagents` without extras.

Common situations: Fresh environment with base smolagents install; CI caching a requirements file that predates litellm usage; deploying to a slim Docker image without extras; multiple virtualenvs and running in the wrong one.

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/0d6f2899b5dfe7cb. Report an issue: GitHub.