huggingface/smolagents · error · ImportError

Gradio should be installed in order to launch a gradio demo.

Error message

Gradio should be installed in order to launch a gradio demo.

What it means

This ImportError is raised by Tool.launch_gradio_demo when the optional `gradio` dependency is not installed. The method wraps a Tool in an interactive Gradio UI, which requires gradio at runtime. Gradio is an optional extra, so a base `pip install smolagents` does not include it.

Source

Thrown at src/smolagents/tools.py:805

                        input_key = next(iter(self.inputs))
                        tool_input[input_key] = argument
                return self.langchain_tool.run(tool_input)

        return LangChainToolWrapper(langchain_tool)


def launch_gradio_demo(tool: Tool):
    """
    Launches a gradio demo for a tool. The corresponding tool class needs to properly implement the class attributes
    `inputs` and `output_type`.

    Args:
        tool (`Tool`): The tool for which to launch the demo.
    """
    try:
        import gradio as gr
    except ImportError:
        raise ImportError("Gradio should be installed in order to launch a gradio demo.")

    TYPE_TO_COMPONENT_CLASS_MAPPING = {
        "boolean": gr.Checkbox,
        "image": gr.Image,
        "audio": gr.Audio,
        "string": gr.Textbox,
        "integer": gr.Number,
        "number": gr.Number,
    }

    def tool_forward(*args, **kwargs):
        return tool(*args, sanitize_inputs_outputs=True, **kwargs)

    tool_forward.__signature__ = inspect.signature(tool.forward)

    gradio_inputs = []
    for input_name, input_details in tool.inputs.items():
        input_gradio_component_class = TYPE_TO_COMPONENT_CLASS_MAPPING[input_details["type"]]

View on GitHub (pinned to 30bb116109)

Solutions

  1. Install gradio: `pip install gradio` (or `pip install 'smolagents[gradio]'` if the extra exists in your version)
  2. Gate the demo launch behind an availability check (importlib.util.find_spec('gradio')) in scripts/CI
  3. Separate demo dependencies into a dev/demo requirements file so interactive UIs are only installed where needed

Example fix

# before
tool.launch_gradio_demo()
# after
import importlib.util
if importlib.util.find_spec("gradio") is None:
    raise SystemExit("Install gradio to run the demo: pip install gradio")
tool.launch_gradio_demo()
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("gradio") is None:
    print("gradio not installed; skipping demo launch")
else:
    tool.launch_gradio_demo()

Try / catch

try:
    tool.launch_gradio_demo()
except ImportError as e:
    if "Gradio" in str(e):
        print("Install gradio to run demos")
    else:
        raise

Prevention

When it happens

Trigger: Calling `tool.launch_gradio_demo()` (or `agent.launch_gradio_demo()`) on any Tool instance in an environment where `import gradio` fails, e.g. base install without extras or a restricted CI container.

Common situations: Running demos in CI, Docker images, or minimal virtualenvs where only core dependencies were installed; gradio was dropped during a dependency cleanup or unpinned environment rebuild.

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