name	duckduckgo-search
description	Free keyless web, news, and image search via ddgs.
version	1.3.0
author	gamedevCloudy
license	MIT
platforms	["linux","macos","windows"]
metadata	{"hermes":{"tags":["search","duckduckgo","web-search","free","fallback"],"related_skills":["arxiv"],"fallback_for_toolsets":["web"]}}

DuckDuckGo Search

Free web search using DuckDuckGo. No API key required.

Preferred when web_search 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:

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

Important runtime note:

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

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 terminal when it exists. This is the preferred path because it 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

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 execute_code or another Python runtime only after verifying that ddgs is installed there. Do not assume execute_code includes third-party packages by default.

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"

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 web_extract, 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 web_extract 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 web_extract, 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 execute_code 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 `execute_code` import fails	Terminal and `execute_code` 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 execute_code 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.