huggingface/smolagents · error · ImportError

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

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.

Solutions

  1. pip install ddgs (or pip install 'smolagents[search]' if using extras).
  2. Pin/verify the dependency in requirements.txt or pyproject so CI installs it.
  3. 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

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.

Appendix: 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)