Duckduckgo Search

DuckDuckGo Search

Free web search using DuckDuckGo. No API key required. Prefer the ddgs CLI when installed; use the Python DDGS library only after verifying that ddgs is importable in the target Python runtime.

When to Use

• web_search is unavailable or unsuitable.
• FIRECRAWL_API_KEY is not set and a free search fallback is needed.
• DuckDuckGo results are specifically desired (different index than Google/Bing).
• You need text, news, image, or video results without an API key.

Trigger keywords: duckduckgo, ddgs, free search, web search fallback, search without api key, ddg search.

Prerequisites

• Python 3.8+ available on the host.
• pip available in the environment where ddgs will run.
• Network access to DuckDuckGo endpoints (some cloud IPs may be blocked).

Windows (PowerShell) is the primary host. Bash equivalents are noted where relevant.

Procedure

Step 1 — Detect what is available

Check whether the ddgs CLI is installed before choosing an approach.

PowerShell:

if (Get-Command ddgs -ErrorAction SilentlyContinue) { "DDGS_CLI=installed" } else { "DDGS_CLI=missing" }

Bash (Linux/macOS):

command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"

Decision tree:

1. If ddgs CLI is installed → use Method 1 (CLI) via terminal.
2. If ddgs CLI is missing → do not assume execute_code can import ddgs.
3. If the user wants DuckDuckGo specifically → install ddgs in the relevant environment first.
4. Otherwise → fall back to built-in web/browser tools.

Runtime separation: Terminal and execute_code are separate runtimes. A successful shell install does not guarantee execute_code can import ddgs. Never assume third-party Python packages are preinstalled inside execute_code.

Step 2 — Install ddgs (only when needed)

Install ddgs only when DuckDuckGo search is specifically needed and the runtime does not already provide it.

pip install ddgs
ddgs --help

If a workflow depends on Python imports, verify that the same runtime can import ddgs before using from ddgs import DDGS.

Package name: The package is ddgs (previously duckduckgo-search). Install with pip install ddgs.

Step 3 — Choose a method

Method 1: CLI Search (Preferred)

Use the ddgs command via terminal when it exists. This avoids assuming the execute_code sandbox has the ddgs Python package installed.

# Text search
ddgs text -q "python async programming" -m 5

# News search
ddgs news -q "artificial intelligence" -m 5

# Image search
ddgs images -q "landscape photography" -m 10

# Video search
ddgs videos -q "python tutorial" -m 5

# With region filter
ddgs text -q "best restaurants" -m 5 -r us-en

# Recent results only (d=day, w=week, m=month, y=year)
ddgs text -q "latest AI news" -m 5 -t w

# JSON output for parsing
ddgs text -q "fastapi tutorial" -m 5 -o json

CLI flags:

Do not confuse -q (query) and -m (max results count).

Method 2: Python API (Only After Verification)

Use the DDGS class in execute_code or another Python runtime only after verifying that ddgs is installed there.

Safe wording:

• "Use execute_code with ddgs after installing or verifying the package if needed."

Avoid saying:

• "execute_code includes ddgs."
• "DuckDuckGo search works by default in execute_code."

HARD RULE: max_results must always be passed as a keyword argument. Positional usage raises an error on all methods: ddgs.text("query", 5) → error. Use ddgs.text("query", max_results=5).

Text search — general research, companies, documentation:

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.text("python async programming", max_results=5):
        print(r["title"])
        print(r["href"])
        print(r.get("body", "")[:200])
        print()

Returns: title, href, body.

News search — current events, breaking news:

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.news("AI regulation 2026", max_results=5):
        print(r["date"], "-", r["title"])
        print(r.get("source", ""), "|", r["url"])
        print(r.get("body", "")[:200])
        print()

Returns: date, title, body, url, image, source.

Image search — visual references, diagrams:

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.images("semiconductor chip", max_results=5):
        print(r["title"])
        print(r["image"])
        print(r.get("thumbnail", ""))
        print(r.get("source", ""))
        print()

Returns: title, image, thumbnail, url, height, width, source.

Video search — tutorials, demos, explainers:

from ddgs import DDGS

with DDGS() as ddgs:
    for r in ddgs.videos("FastAPI tutorial", max_results=5):
        print(r["title"])
        print(r.get("content", ""))
        print(r.get("duration", ""))
        print(r.get("provider", ""))
        print(r.get("published", ""))
        print()

Returns: title, content, description, duration, provider, published, statistics, uploader.

Quick reference:

Step 4 — Search then extract (full content)

DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full page content, search first, then extract the most relevant URL with web_extract, browser tools, or curl.

CLI:

ddgs text -q "fastapi deployment guide" -m 3 -o json

Python (only after verifying ddgs is installed in that runtime):

from ddgs import DDGS

with DDGS() as ddgs:
    results = list(ddgs.text("fastapi deployment guide", max_results=3))
    for r in results:
        print(r["title"], "->", r["href"])

Then extract the best URL with web_extract or another content-retrieval tool.

Pitfalls

• max_results is keyword-only: ddgs.text("query", 5) raises an error. Always use ddgs.text("query", max_results=5).
• Do not assume the CLI exists: Check Get-Command ddgs (PowerShell) or command -v ddgs (bash) before using it.
• Do not assume execute_code can import ddgs: from ddgs import DDGS may fail with ModuleNotFoundError unless that runtime was prepared separately.
• Package name confusion: The package is ddgs (previously duckduckgo-search). Install with pip install ddgs.
• CLI flag confusion: -q is the query; -m is max results count. Do not swap them.
• Empty results: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.
• Rate limiting: DuckDuckGo may throttle after many rapid requests. Add a short delay between searches if needed.
• No content extraction: ddgs returns snippets, not full page content. Use web_extract, browser tools, or curl for the full article/page.
• Cloud IP blocking: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or wait a few seconds.
• Field variability: Return fields may vary between results or ddgs versions. Use .get() for optional fields to avoid KeyError.
• Separate runtimes: A successful ddgs install in terminal does not automatically mean execute_code can import it.

Verification

Verify CLI is installed

PowerShell:

Get-Command ddgs
ddgs --help

Bash:

command -v ddgs && ddgs --help

Expected: help text listing text, news, images, videos subcommands.

Verify a text search returns results

ddgs text -q "python async programming" -m 3 -o json

Expected: JSON array with objects containing title, href, and body fields.

Verify Python import (only if using Method 2)

from ddgs import DDGS
with DDGS() as ddgs:
    results = list(ddgs.text("test query", max_results=1))
    print(results[0]["title"])

Expected: at least one result printed. If ModuleNotFoundError occurs, the Python runtime does not have ddgs installed — do not use Method 2 there.

Troubleshooting

Related Skills

• arxiv — academic paper search (complementary for research workflows).
• Firecrawl-based search skills — more configurable but require FIRECRAWL_API_KEY.

Validated against ddgs==9.11.2 semantics. CLI availability and Python import availability are treated as separate concerns so the documented workflow matches actual runtime behavior.