DDGS (formerly duckduckgo-search)

9.13.0 · active · verified Thu Apr 09

DDGS is a Python metasearch library that aggregates results from various web search services, including DuckDuckGo, Bing, and Google, without requiring an API key. It provides programmatic access to different search types such as text, images, videos, news, and books. The library is actively maintained, with frequent releases; the current version is 9.13.0.

Warnings

breaking The package name has been officially changed from `duckduckgo-search` to `ddgs`. Continuing to use the old package name will lead to `RuntimeWarning` and may prevent access to newer features and bug fixes.
Fix: Uninstall `duckduckgo-search` and install `ddgs` via `pip install --upgrade ddgs`. Update all imports from `from duckduckgo_search import DDGS` to `from ddgs import DDGS`.
breaking Python 3.9 support was dropped in version 9.9.0. Projects using `ddgs` (version 9.9.0+) must use Python 3.10 or newer.
Fix: Ensure your project's Python environment is 3.10 or higher. Upgrade Python if necessary.
gotcha The library acts as a metasearch tool, using various backends (DuckDuckGo, Bing, Google, etc.). Specific backends can be unstable or have their scraping methods change, leading to temporary issues or irrelevant results. This often necessitates updating the library.
Fix: Keep the `ddgs` library updated to the latest version. The developers frequently release fixes for backend changes. Monitor GitHub releases for relevant updates.
gotcha Frequent or high-volume requests without proper proxy management can lead to rate limiting or IP bans from search engines.
Fix: Utilize rotating proxies or services like Tor (by setting `proxy="tb"` for Tor Browser's SOCKS5 proxy) to distribute requests. Avoid making too many requests in a short period without a delay.
gotcha The search methods (e.g., `text()`, `images()`) always return a list of dictionaries, even when `max_results=1`. Users might incorrectly assume a single dictionary is returned.
Fix: Always access results by indexing the list (e.g., `results[0]`) after checking if the list is not empty.

Install

pip install ddgs Latest stable version

Imports

DDGS
```
from ddgs import DDGS
```
The package was renamed from 'duckduckgo_search' to 'ddgs'.

Quickstart

This example demonstrates how to initialize the DDGS client and perform a basic text search. It also includes an example of an image search, showcasing common parameters like region, safesearch, timelimit, and max_results. Results are returned as a list of dictionaries.

from ddgs import DDGS

# Initialize DDGS with optional proxy or timeout
ddgs_client = DDGS(timeout=20)

# Perform a text search
results = ddgs_client.text(
    "python programming tutorials",
    region="wt-wt", # worldwide
    safesearch="moderate",
    timelimit="y", # past year
    max_results=5
)

for r in results:
    print(f"Title: {r.get('title')}\nURL: {r.get('href')}\n")

# Example of an image search
image_results = ddgs_client.images(
    "cute puppies",
    region="us-en",
    safesearch="off",
    max_results=3
)

if image_results:
    print(f"First image URL: {image_results[0].get('image')}")

view raw JSON →