huggingface/smolagents · error · ImportError

You must install package `ddgs` to run this tool: for instan

Error message

You must install package `ddgs` to run this tool: for instance run `pip install ddgs`.

What it means

Raised in DuckDuckGoSearchTool.__init__ when the optional `ddgs` package is not installed. smolagents keeps search dependencies optional, so the tool fails fast at construction time with an ImportError chained from the underlying ModuleNotFoundError.

Source

Thrown at src/smolagents/default_tools.py:135

        >>> print(results)
        ```
    """

    name = "web_search"
    description = """Performs a duckduckgo web search based on your query (think a Google search) then returns the top search results."""
    inputs = {"query": {"type": "string", "description": "The search query to perform."}}
    output_type = "string"

    def __init__(self, max_results: int = 10, rate_limit: float | None = 1.0, **kwargs):
        super().__init__()
        self.max_results = max_results
        self.rate_limit = rate_limit
        self._min_interval = 1.0 / rate_limit if rate_limit else 0.0
        self._last_request_time = 0.0
        try:
            from ddgs import DDGS
        except ImportError as e:
            raise ImportError(
                "You must install package `ddgs` to run this tool: for instance run `pip install ddgs`."
            ) from e
        self.ddgs = DDGS(**kwargs)

    def forward(self, query: str) -> str:
        self._enforce_rate_limit()
        results = self.ddgs.text(query, max_results=self.max_results)
        if len(results) == 0:
            raise Exception("No results found! Try a less restrictive/shorter query.")
        postprocessed_results = [f"[{result['title']}]({result['href']})\n{result['body']}" for result in results]
        return "## Search Results\n\n" + "\n\n".join(postprocessed_results)

    def _enforce_rate_limit(self) -> None:
        import time

        # No rate limit enforced
        if not self.rate_limit:
            return

View on GitHub (pinned to 30bb116109)

Solutions

pip install ddgs (or pip install 'smolagents[search]' if using extras).
Pin/verify the dependency in requirements.txt or pyproject so CI installs it.
If ddgs is installed but still failing, check you're not in a different virtualenv than the one running the code.

Example fix

# before
tool = DuckDuckGoSearchTool()  # ImportError
# after
# pip install ddgs
tool = DuckDuckGoSearchTool()

Defensive patterns

Strategy: validation

Validate before calling

try:
    import ddgs  # noqa
except ImportError:
    raise SystemExit('pip install ddgs before using DuckDuckGoSearchTool')

Prevention

Install optional search extras up front: pip install 'smolagents[search]'.
Check importability in entrypoint scripts before building agents.

When it happens

Trigger: Instantiating DuckDuckGoSearchTool (or referencing it via the default tools) in an environment where `import ddgs` raises ImportError — i.e. `pip install smolagents` without the search extra.

Common situations: Fresh installs without extras, CI environments with trimmed dependencies, or migration from the deprecated `duckduckgo_search` package to `ddgs` after a smolagents upgrade.

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