Duckduckgo search

DuckDuckGo Search

Free web search using DuckDuckGo. No API key required.

Preferred when WebSearch is unavailable or unsuitable (for example when FIRECRAWL_API_KEY is not set). Can also be used as a standalone search path when DuckDuckGo results are specifically desired.

Detection Flow

Check what is actually available before choosing an approach:

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

Decision tree:

1. If ddgs CLI is installed, prefer Bash + ddgs
2. If ddgs CLI is missing, do not assume Bash can import ddgs
3. If the user wants DuckDuckGo specifically, install ddgs first in the relevant environment
4. Otherwise fall back to built-in web/browser tools

Important runtime note:

• Terminal and Bash are separate runtimes
• A successful shell install does not guarantee Bash can import ddgs
• Never assume third-party Python packages are preinstalled inside Bash

Installation

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

# Python package + CLI entrypoint
pip install ddgs

# Verify CLI
ddgs --help

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

Method 1: CLI Search (Preferred)

Use the ddgs command via Bash when it exists. This is the preferred path because it avoids assuming the Bash 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

Flag	Description	Example
-q	Query — required	-q "search terms"
-m	Max results	-m 5
-r	Region	-r us-en
-t	Time limit	-t w (week)
-s	Safe search	-s off
-o	Output format	-o json

Method 2: Python API (Only After Verification)

Use the DDGS class in Bash or another Python runtime only after verifying that ddgs is installed there. Do not assume Bash includes third-party packages by default.

Safe wording:

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

Avoid saying:

• "Bash includes ddgs"
• "DuckDuckGo search works by default in Bash"

Important: max_results must always be passed as a keyword argument — positional usage raises an error on all methods.

Text Search

Best for: 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

Best for: current events, breaking news, latest updates.

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

Best for: visual references, product images, 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

Best for: 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

Method	Use When	Key Fields
text()	General research, companies	title, href, body
news()	Current events, updates	date, title, source, body, url
images()	Visuals, diagrams	title, image, thumbnail, url
videos()	Tutorials, demos	title, content, duration, provider

Workflow: Search then Extract

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

CLI example:

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

Python example, 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 WebFetch or another content-retrieval tool.

Limitations

• 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 WebFetch, browser tools, or curl for the full article/page.
• Results quality: Generally good but less configurable than Firecrawl's search.
• Availability: 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 Bash can import it.

Troubleshooting

Problem	Likely Cause	What To Do
ddgs: command not found	CLI not installed in the shell environment	Install ddgs, or use built-in web/browser tools instead
ModuleNotFoundError: No module named 'ddgs'	Python runtime does not have the package installed	Do not use Python DDGS there until that runtime is prepared
Search returns nothing	Temporary rate limiting or poor query	Wait a few seconds, retry, or adjust the query
CLI works but Bash import fails	Terminal and Bash are different runtimes	Keep using CLI, or separately prepare the Python runtime

Pitfalls

• max_results is keyword-only: ddgs.text("query", 5) raises an error. Use ddgs.text("query", max_results=5).
• Do not assume the CLI exists: Check command -v ddgs before using it.
• Do not assume Bash can import ddgs: from ddgs import DDGS may fail with ModuleNotFoundError unless that runtime was prepared separately.
• Package name: The package is ddgs (previously duckduckgo-search). Install with pip install ddgs.
• Don't confuse -q and -m (CLI): -q is for the query, -m is for max results count.
• Empty results: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.

Validated With

Validated examples against ddgs==9.11.2 semantics. Skill guidance now treats CLI availability and Python import availability as separate concerns so the documented workflow matches actual runtime behavior.