huggingface/smolagents · error · ModuleNotFoundError

Please install 'transformers' extra to use a PipelineTool: `

Error message

Please install 'transformers' extra to use a PipelineTool: `pip install 'smolagents[transformers]'`

What it means

PipelineTool (and its subclasses for transformers models) requires torch and accelerate at construction time. __init__ checks package availability and raises ModuleNotFoundError pointing at the 'transformers' extra when either is missing.

Source

Thrown at src/smolagents/tools.py:1231

    description = "This is a pipeline tool"
    name = "pipeline"
    inputs = {"prompt": str}
    output_type = str
    skip_forward_signature_validation = True

    def __init__(
        self,
        model=None,
        pre_processor=None,
        post_processor=None,
        device=None,
        device_map=None,
        model_kwargs=None,
        token=None,
        **hub_kwargs,
    ):
        if not _is_package_available("accelerate") or not _is_package_available("torch"):
            raise ModuleNotFoundError(
                "Please install 'transformers' extra to use a PipelineTool: `pip install 'smolagents[transformers]'`"
            )

        if model is None:
            if self.default_checkpoint is None:
                raise ValueError("This tool does not implement a default checkpoint, you need to pass one.")
            model = self.default_checkpoint
        if pre_processor is None:
            pre_processor = model

        self.model = model
        self.pre_processor = pre_processor
        self.post_processor = post_processor
        self.device = device
        self.device_map = device_map
        self.model_kwargs = {} if model_kwargs is None else model_kwargs
        if device_map is not None:
            self.model_kwargs["device_map"] = device_map

View on GitHub (pinned to 30bb116109)

Solutions

Install the extra: `pip install 'smolagents[transformers]'`
Or install the two required packages directly: `pip install torch accelerate`
For lightweight deployments, replace the PipelineTool with a Tool that calls a hosted inference API instead

Example fix

# before
tool = SpeechToTextTool()  # ModuleNotFoundError
# after  (after: pip install 'smolagents[transformers]')
tool = SpeechToTextTool()

Defensive patterns

Strategy: validation

Validate before calling

from smolagents.utils import _is_package_available
if not (_is_package_available("torch") and _is_package_available("accelerate")):
    raise SystemExit("Run: pip install 'smolagents[transformers]'")
tool = MyPipelineTool()

Try / catch

try:
    tool = MyPipelineTool()
except ModuleNotFoundError as e:
    if "smolagents[transformers]" in str(e):
        print("transformers extra missing; skipping ML tool")
    else:
        raise

Prevention

Install the transformers extra in environments using ML pipeline tools
Check torch/accelerate availability in startup health checks
Consider API-based tools in slim deployments

When it happens

Trigger: Instantiating any PipelineTool subclass (e.g. a TransformersTool like a translation or VAD tool) in an environment lacking `torch` or `accelerate`. The check happens before any model download.

Common situations: Using smolagents tools that wrap transformers pipelines with only the base install; slim Docker images that exclude torch; CI environments where heavy ML deps are intentionally omitted.

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