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