ddgs — Web Search for Agents
Overview
ddgs (Dux Distributed Global Search) is a Python metasearch library that aggregates results from multiple search engines. Agents can use it via Python API, CLI, or MCP server.
Python API
from ddgs import DDGS
# Text search
results = DDGS().text("python async", max_results=5)
# Images, news, videos, books
images = DDGS().images("butterfly", max_results=5)
news = DDGS().news("ai regulation", timelimit="w")
videos = DDGS().videos("rust programming")
books = DDGS().books("machine learning")
# Extract content from a URL
page = DDGS().extract("https://example.com")
page["content"] # Markdown text (default)
page = DDGS().extract("https://example.com", fmt="text_plain")
page = DDGS().extract("https://example.com", fmt="content") # raw bytes
All search methods return list[dict[str, Any]]. Each dict has keys depending on category:
| Method |
Keys |
text() |
title, href, body |
images() |
title, image, thumbnail, url, height, width, source |
videos() |
title, content, description, duration, embed_url, images, publisher |
news() |
date, title, body, url, image, source |
books() |
title, author, publisher, info, url, thumbnail |
CLI
# Text search
ddgs text -q "python async" --max_results 5
# Other categories
ddgs images -q "cats" --color Blue
ddgs news -q "tech" --timelimit d
ddgs videos -q "cars" --duration medium
ddgs books -q "sea wolf"
# Extract content
ddgs extract -u https://example.com
ddgs extract -u https://example.com -f text_plain
# Save results
ddgs text -q "dogs" -o results.json
ddgs text -q "dogs" -o results.csv
# Version
ddgs version
CLI for Agents
Agents can also use ddgs as a CLI tool via subprocess. Auto-detects non-TTY — outputs plain text without colors or interactive pauses.
To discover available options:
ddgs --help
ddgs text --help
ddgs images --help
MCP Server
stdio (for local MCP clients like Cursor, Claude Desktop)
pip install ddgs[mcp]
ddgs mcp # stdio MCP server
ddgs mcp -pr socks5h://127.0.0.1:9150 # with proxy
Client configuration:
{
"mcpServers": {
"ddgs": {
"command": "ddgs",
"args": ["mcp"]
}
}
}
Available MCP Tools
| Tool |
Description |
search_text |
Web text search |
search_images |
Image search |
search_news |
News search |
search_videos |
Video search |
search_books |
Book search |
extract_content |
Extract content from a URL |
Quick Reference
| Parameter |
Values |
Default |
region |
us-en, uk-en, ru-ru, de-de, etc. |
us-en |
safesearch |
on, moderate, off |
moderate |
timelimit |
d (day), w (week), m (month), y (year) |
None |
max_results |
int |
10 |
page |
int |
1 |
backend |
auto, all, or engine name |
auto |
Available backends by method:
| Method |
Backends |
text() |
bing, brave, duckduckgo, google, grokipedia, mojeek, startpage, yandex, yahoo, wikipedia |
images() |
bing, duckduckgo |
videos() |
duckduckgo |
news() |
bing, duckduckgo, yahoo |
books() |
annasarchive |
Tips
- Proxy (Python):
DDGS(proxy="socks5h://127.0.0.1:9150") or set env DDGS_PROXY
- Proxy (MCP):
ddgs mcp -pr socks5h://127.0.0.1:9150 or export DDGS_PROXY=...
- Proxy (API):
ddgs api -pr socks5h://127.0.0.1:9150 or export DDGS_PROXY=...
- SSL verification:
DDGS(verify=False) or DDGS(verify="/path/to/cert.pem")
- Timeout:
DDGS(timeout=10) (default: 5 seconds)
- Errors: catches
DDGSException, RatelimitException, TimeoutException
- Multiple backends:
backend="bing,google" (comma-separated)
1---2name: ddgs3description: Use when an agent needs to search the web, find images/news/videos/books, or extract content from a URL. Covers the ddgs Python library, CLI, and MCP server integration.4---56# ddgs — Web Search for Agents78## Overview910**ddgs** (Dux Distributed Global Search) is a Python metasearch library that aggregates results from multiple search engines. Agents can use it via Python API, CLI, or MCP server.1112## Python API1314```python15from ddgs import DDGS1617# Text search18results = DDGS().text("python async", max_results=5)1920# Images, news, videos, books21images = DDGS().images("butterfly", max_results=5)22news = DDGS().news("ai regulation", timelimit="w")23videos = DDGS().videos("rust programming")24books = DDGS().books("machine learning")2526# Extract content from a URL27page = DDGS().extract("https://example.com")28page["content"] # Markdown text (default)29page = DDGS().extract("https://example.com", fmt="text_plain")30page = DDGS().extract("https://example.com", fmt="content") # raw bytes31```3233All search methods return `list[dict[str, Any]]`. Each dict has keys depending on category:3435| Method | Keys |36|--------|------|37| `text()` | `title`, `href`, `body` |38| `images()` | `title`, `image`, `thumbnail`, `url`, `height`, `width`, `source` |39| `videos()` | `title`, `content`, `description`, `duration`, `embed_url`, `images`, `publisher` |40| `news()` | `date`, `title`, `body`, `url`, `image`, `source` |41| `books()` | `title`, `author`, `publisher`, `info`, `url`, `thumbnail` |4243## CLI4445```bash46# Text search47ddgs text -q "python async" --max_results 54849# Other categories50ddgs images -q "cats" --color Blue51ddgs news -q "tech" --timelimit d52ddgs videos -q "cars" --duration medium53ddgs books -q "sea wolf"5455# Extract content56ddgs extract -u https://example.com57ddgs extract -u https://example.com -f text_plain5859# Save results60ddgs text -q "dogs" -o results.json61ddgs text -q "dogs" -o results.csv6263# Version64ddgs version65```6667## CLI for Agents6869Agents can also use `ddgs` as a CLI tool via subprocess. Auto-detects non-TTY — outputs plain text without colors or interactive pauses.7071To discover available options:72```bash73ddgs --help74ddgs text --help75ddgs images --help76```7778## MCP Server7980### stdio (for local MCP clients like Cursor, Claude Desktop)8182```bash83pip install ddgs[mcp]84ddgs mcp # stdio MCP server85ddgs mcp -pr socks5h://127.0.0.1:9150 # with proxy86```8788Client configuration:89```json90{91 "mcpServers": {92 "ddgs": {93 "command": "ddgs",94 "args": ["mcp"]95 }96 }97}98```99100### Available MCP Tools101102| Tool | Description |103|------|-------------|104| `search_text` | Web text search |105| `search_images` | Image search |106| `search_news` | News search |107| `search_videos` | Video search |108| `search_books` | Book search |109| `extract_content` | Extract content from a URL |110111## Quick Reference112113| Parameter | Values | Default |114|-----------|--------|---------|115| `region` | `us-en`, `uk-en`, `ru-ru`, `de-de`, etc. | `us-en` |116| `safesearch` | `on`, `moderate`, `off` | `moderate` |117| `timelimit` | `d` (day), `w` (week), `m` (month), `y` (year) | None |118| `max_results` | int | 10 |119| `page` | int | 1 |120| `backend` | `auto`, `all`, or engine name | `auto` |121122Available backends by method:123124| Method | Backends |125|--------|----------|126| `text()` | `bing`, `brave`, `duckduckgo`, `google`, `grokipedia`, `mojeek`, `startpage`, `yandex`, `yahoo`, `wikipedia` |127| `images()` | `bing`, `duckduckgo` |128| `videos()` | `duckduckgo` |129| `news()` | `bing`, `duckduckgo`, `yahoo` |130| `books()` | `annasarchive` |131132## Tips133134- **Proxy (Python)**: `DDGS(proxy="socks5h://127.0.0.1:9150")` or set env `DDGS_PROXY`135- **Proxy (MCP)**: `ddgs mcp -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`136- **Proxy (API)**: `ddgs api -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`137- **SSL verification**: `DDGS(verify=False)` or `DDGS(verify="/path/to/cert.pem")`138- **Timeout**: `DDGS(timeout=10)` (default: 5 seconds)139- **Errors**: catches `DDGSException`, `RatelimitException`, `TimeoutException`140- **Multiple backends**: `backend="bing,google"` (comma-separated)
deedy5