ddgs

ddgs (Dux Distributed Global Search, formerly published as duckduckgo_search) is a Python library and CLI for querying multiple web search engines through one unified DDGS class. It normalizes text, image, news, and video search across a set of pluggable backend engines instead of scraping a single provider, giving callers a consistent result schema regardless of which engine actually served the query.

Beyond the importable DDGS client, the project ships a ddgs console script for ad-hoc terminal searches (including proxy support, e.g. routing through Tor), and an api_server module that exposes the same search capability as an HTTP API and an MCP (Model Context Protocol) server — making it usable directly as a tool source for LLM agents.

What You Get

• A unified DDGS client with .text(), .images(), .news(), and .videos() methods across 18 pluggable backend engines
• A ddgs console-script CLI with proxy support (including routing through Tor) and result export/download options
• An api_server module exposing search as both a plain HTTP API and an MCP (Model Context Protocol) server for LLM agent tool use
• Region and safesearch filtering plus pagination controls for each search type
• Typed package (py.typed) with a dedicated exceptions module for engine/rate-limit errors

Common Use Cases

• Adding real-time web search results to an LLM agent or RAG pipeline via the MCP server or direct DDGS calls
• Scripting bulk text/image/news lookups from Python without managing per-engine scraping logic
• Running ad-hoc terminal searches and downloading matching files (e.g. filetype:pdf queries) via the CLI
• Standing up a lightweight internal search API by wrapping api_server for services that need engine-agnostic search

Under The Hood

Architecture - ddgs.py (272 lines) defines the DDGS client that dispatches .text()/.images()/.news()/.videos() calls to one of 18 backend engine modules under ddgs/engines/, each responsible for querying and parsing one search provider into the common results.py schema (148 lines). base.py (123 lines) defines the shared engine interface all backends implement, cli.py (700 lines) is the largest module and wraps the same client in a full-featured terminal tool with proxy/Tor/export options, and ddgs/api_server/ layers an HTTP API (api.py) and an MCP server (mcp.py) on top of the identical DDGS calls, so all four surfaces (library, CLI, HTTP API, MCP) share one query/parsing core.

Tech Stack - Python 3.10+ using httpx (with HTTP/2, SOCKS, and Brotli extras) and primp for outbound requests, lxml for HTML parsing, click for the CLI, and fake-useragent for request header rotation. Packaging is modern pyproject.toml with setuptools and a dynamic version sourced from ddgs.__version__; a Dockerfile/docker-compose.yml are included for running the API/MCP server as a container.

Code Quality - tests/ covers both the core client (ddgs_test.py) and the CLI (cli_test.py); coverage is real but comparatively thin relative to the 18-engine surface area, meaning individual engine parsers are more exposed to upstream HTML/API changes than the core dispatch logic. exceptions.py centralizes engine and rate-limit errors rather than leaking raw HTTP exceptions, and the codebase is fully typed (py.typed marker present).

API Design - The core flow is minimal — DDGS().text("query") — and stays consistent across all four search types and all 18 engines, so switching engines or search kinds doesn’t change calling conventions. The MCP server addition is a notable ergonomic strength: it lets the same engine layer be consumed by LLM agents with zero custom integration code, though the README’s density (CLI options, region codes, proxy setup) means first-time users need to skim past a fair amount of reference material before finding the three-line quickstart.