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.4metadata:5 source: https://skillmd.com/skills/deedy5/ddgs6---78# ddgs — Web Search for Agents910## Overview1112**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.1314## Python API1516```python17from ddgs import DDGS1819# Text search20results = DDGS().text("python async", max_results=5)2122# Images, news, videos, books23images = DDGS().images("butterfly", max_results=5)24news = DDGS().news("ai regulation", timelimit="w")25videos = DDGS().videos("rust programming")26books = DDGS().books("machine learning")2728# Extract content from a URL29page = DDGS().extract("https://example.com")30page["content"] # Markdown text (default)31page = DDGS().extract("https://example.com", fmt="text_plain")32page = DDGS().extract("https://example.com", fmt="content") # raw bytes33```3435All search methods return `list[dict[str, Any]]`. Each dict has keys depending on category:3637| Method | Keys |38|--------|------|39| `text()` | `title`, `href`, `body` |40| `images()` | `title`, `image`, `thumbnail`, `url`, `height`, `width`, `source` |41| `videos()` | `title`, `content`, `description`, `duration`, `embed_url`, `images`, `publisher` |42| `news()` | `date`, `title`, `body`, `url`, `image`, `source` |43| `books()` | `title`, `author`, `publisher`, `info`, `url`, `thumbnail` |4445## CLI4647```bash48# Text search49ddgs text -q "python async" --max_results 55051# Other categories52ddgs images -q "cats" --color Blue53ddgs news -q "tech" --timelimit d54ddgs videos -q "cars" --duration medium55ddgs books -q "sea wolf"5657# Extract content58ddgs extract -u https://example.com59ddgs extract -u https://example.com -f text_plain6061# Save results62ddgs text -q "dogs" -o results.json63ddgs text -q "dogs" -o results.csv6465# Version66ddgs version67```6869## CLI for Agents7071Agents can also use `ddgs` as a CLI tool via subprocess. Auto-detects non-TTY — outputs plain text without colors or interactive pauses.7273To discover available options:74```bash75ddgs --help76ddgs text --help77ddgs images --help78```7980## MCP Server8182### stdio (for local MCP clients like Cursor, Claude Desktop)8384```bash85pip install ddgs[mcp]86ddgs mcp # stdio MCP server87ddgs mcp -pr socks5h://127.0.0.1:9150 # with proxy88```8990Client configuration:91```json92{93 "mcpServers": {94 "ddgs": {95 "command": "ddgs",96 "args": ["mcp"]97 }98 }99}100```101102### Available MCP Tools103104| Tool | Description |105|------|-------------|106| `search_text` | Web text search |107| `search_images` | Image search |108| `search_news` | News search |109| `search_videos` | Video search |110| `search_books` | Book search |111| `extract_content` | Extract content from a URL |112113## Quick Reference114115| Parameter | Values | Default |116|-----------|--------|---------|117| `region` | `us-en`, `uk-en`, `ru-ru`, `de-de`, etc. | `us-en` |118| `safesearch` | `on`, `moderate`, `off` | `moderate` |119| `timelimit` | `d` (day), `w` (week), `m` (month), `y` (year) | None |120| `max_results` | int | 10 |121| `page` | int | 1 |122| `backend` | `auto`, `all`, or engine name | `auto` |123124Available backends by method:125126| Method | Backends |127|--------|----------|128| `text()` | `bing`, `brave`, `duckduckgo`, `google`, `grokipedia`, `mojeek`, `startpage`, `yandex`, `yahoo`, `wikipedia` |129| `images()` | `bing`, `duckduckgo` |130| `videos()` | `duckduckgo` |131| `news()` | `bing`, `duckduckgo`, `yahoo` |132| `books()` | `annasarchive` |133134## Tips135136- **Proxy (Python)**: `DDGS(proxy="socks5h://127.0.0.1:9150")` or set env `DDGS_PROXY`137- **Proxy (MCP)**: `ddgs mcp -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`138- **Proxy (API)**: `ddgs api -pr socks5h://127.0.0.1:9150` or `export DDGS_PROXY=...`139- **SSL verification**: `DDGS(verify=False)` or `DDGS(verify="/path/to/cert.pem")`140- **Timeout**: `DDGS(timeout=10)` (default: 5 seconds)141- **Errors**: catches `DDGSException`, `RatelimitException`, `TimeoutException`142- **Multiple backends**: `backend="bing,google"` (comma-separated)