DuckDuckGo Search via ddgs Reference

This document describes how to perform free web searches using DuckDuckGo through the ddgs package. It requires no API key and provides text, news, image, and video search capabilities via both a command-line interface (CLI) and a Python API.

When to Use

Use ddgs in the following situations:

When web_search is unavailable or unsuitable, such as when FIRECRAWL_API_KEY is not set.
When DuckDuckGo results are specifically desired.
As a standalone search path when other search tools are not available.

Capabilities

Text search for general research, companies, and documentation.
News search for current events, breaking news, and latest updates.
Image search for visual references, product images, and diagrams.
Video search for tutorials, demos, and explainers.
Region filtering.
Time-based filtering (day, week, month, year).
JSON output for parsing.
Safe search toggle.
Max results limit.
CLI and Python API interfaces.

Prerequisites

For CLI: The ddgs package must be installed (pip install ddgs).
For Python API: The ddgs package must be installed in the same runtime that will execute the code.
Check CLI availability with command -v ddgs before using.
Verify Python import with from ddgs import DDGS before using in execute_code.

Detection Flow

Follow these steps to determine how to use ddgs:

Check CLI availability by running:

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

If the ddgs CLI is installed, prefer using the terminal with ddgs.
If the 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.

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 the workflow depends on Python imports, verify that the same runtime can import ddgs before using from ddgs import DDGS.

CLI Search (Preferred)

Use the ddgs command via the terminal when it exists. The general syntax is ddgs <subcommand> -q "query" -m N. The subcommands are text, news, images, and videos.

Basic Commands

# 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

Filters and Output

# 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 Parameters

-q: Search query string (required). Example: -q "search terms".
-m: Maximum number of results to return. Example: -m 5.
-r: Region filter. Example: -r us-en.
-t: Time limit: d for day, w for week, m for month, y for year. Example: -t w.
-s: Safe search setting. Example: -s off.
-o: Output format. Example: -o json.

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

Python API (Only After Verification)

Verify that ddgs is installed in the Python runtime before using. Use the with DDGS() as ddgs: context manager. The max_results parameter must always be passed as a keyword argument – positional usage raises an error.

Text Search

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()

News Search

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()

Image Search

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()

Video Search

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()

Python API Fields

Common fields include title, href, body, date, url, image, source, thumbnail, height, width, content, description, duration, provider, published, statistics, and uploader. Use .get() for optional fields to avoid KeyError.

Method Names

text() for text search.
news() for news search.
images() for image search.
videos() for video search.

Workflow: Search then Extract

Use ddgs to search and get titles, URLs, and snippets.
Select the most relevant URL from results.
Extract full page content using web_extract, browser tools, or curl.

CLI Workflow Example

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

Then extract the best URL with web_extract.

Python Workflow Example

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"])