FoundationAgents/MetaGPT · error · ImportError

To use this module, you should have the `duckduckgo_search`

Error message

To use this module, you should have the `duckduckgo_search` Python package installed. You can install it by running the command: `pip install -e.[search-ddg]`

What it means

Module-level ImportError raised while importing metagpt.tools.search_engine_ddg: the optional duckduckgo_search package is not installed, so the module cannot define DDGS and refuses to load. This fails at import time, not at search time, because the try/except sits at top level.

Source

Thrown at metagpt/tools/search_engine_ddg.py:15

#!/usr/bin/env python

from __future__ import annotations

import asyncio
import json
from concurrent import futures
from typing import Literal, Optional, overload

from pydantic import BaseModel, ConfigDict

try:
    from duckduckgo_search import DDGS
except ImportError:
    raise ImportError(
        "To use this module, you should have the `duckduckgo_search` Python package installed. "
        "You can install it by running the command: `pip install -e.[search-ddg]`"
    )


class DDGAPIWrapper(BaseModel):
    model_config = ConfigDict(arbitrary_types_allowed=True)

    loop: Optional[asyncio.AbstractEventLoop] = None
    executor: Optional[futures.Executor] = None
    proxy: Optional[str] = None

    @property
    def ddgs(self):
        return DDGS(proxies=self.proxy)

    @overload
    def run(

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Install the extra: pip install -e.[search-ddg]
2. Verify: python -c "import duckduckgo_search"
3. Or switch config to a search engine whose dependencies you already have

Example fix

# before: ImportError on import
from metagpt.tools.search_engine_ddg import DDGAPIWrapper
# after
# pip install -e.[search-ddg]
from metagpt.tools.search_engine_ddg import DDGAPIWrapper

try:
    import duckduckgo_search  # noqa: F401
    ok = True
except ImportError:
    ok = False

try:
    from metagpt.tools.search_engine_ddg import DDGAPIWrapper
except ImportError:
    from metagpt.tools.search_engine_serper import SerperWrapper  # substitute engine

When it happens

Trigger: import metagpt.tools.search_engine_ddg or configuring DDGAPIWrapper as the search engine in a MetaGPT install lacking the search-ddg extra.

Common situations: Core `pip install metagpt` without extras; choosing DuckDuckGo as the default SearchEngine in config; CI image without optional deps.

Related errors

• To use this module, you should have the `google-api-python-c
• To use the similarity search, you need to install the RAG mo
• Query cannot be empty or contain only whitespace.
• To use the RoleZeroMemory, you need to install the rag modul
• Directory {dir_path} not found

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/0ebd2e1282026327. Report an issue: GitHub.