or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdimage-search.mdindex.mdnews-search.mdtext-search.mdvideo-search.md
tile.json

tessl/pypi-duckduckgo-search

Search for words, documents, images, news, maps and text translation using the DuckDuckGo.com search engine.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/duckduckgo-search@8.1.x

To install, run

npx @tessl/cli install tessl/pypi-duckduckgo-search@8.1.0

index.mddocs/

DuckDuckGo Search

A Python library for searching DuckDuckGo.com across multiple content types including text, images, videos, and news. It provides both programmatic API access through the DDGS class and command-line interface functionality for direct search operations, with support for advanced search features, regional settings, proxy configuration, and bulk download capabilities.

Package Information

  • Package Name: duckduckgo_search
  • Language: Python
  • Installation: pip install duckduckgo_search

Note: This package has been renamed to ddgs. When using the DDGS class, a RuntimeWarning will be displayed recommending migration to the newer ddgs package via pip install ddgs.

Core Imports

from duckduckgo_search import DDGS

Import version information:

from duckduckgo_search import __version__

Import exceptions for error handling:

from duckduckgo_search.exceptions import (
    DuckDuckGoSearchException,
    RatelimitException, 
    TimeoutException,
    ConversationLimitException
)

Basic Usage

from duckduckgo_search import DDGS

# Basic text search
with DDGS() as ddgs:
    results = ddgs.text("python programming", max_results=5)
    for result in results:
        print(f"Title: {result['title']}")
        print(f"URL: {result['href']}")
        print(f"Summary: {result['body']}")
        print("---")

# Image search
with DDGS() as ddgs:
    images = ddgs.images("cats", max_results=10)
    for image in images:
        print(f"Image URL: {image['image']}")
        print(f"Source: {image['url']}")
        print("---")

# News search
with DDGS() as ddgs:
    news = ddgs.news("AI technology", max_results=5) 
    for article in news:
        print(f"Title: {article['title']}")
        print(f"Date: {article['date']}")
        print(f"Source: {article['source']}")
        print("---")

Architecture

The DDGS class serves as the central interface for all search operations:

  • DDGS: Main search class supporting context manager protocol for resource management
  • Search Methods: Specialized methods for different content types (text, images, videos, news)
  • Configuration: Proxy support, SSL verification, custom headers, and timeout settings
  • Backend Selection: Multiple search backends (auto, html, lite, bing) with automatic fallback
  • Rate Limiting: Built-in request rate limiting and error handling

The library maintains simplicity through minimal dependencies while providing comprehensive search capabilities across DuckDuckGo's various search verticals.

Capabilities

Text Search

Performs text-based web searches with support for regional filtering, safe search settings, time-based filtering, and multiple backend options with automatic fallback.

def text(
    keywords: str,
    region: str | None = None,
    safesearch: str = "moderate", 
    timelimit: str | None = None,
    backend: str = "auto",
    max_results: int | None = None
) -> list[dict[str, str]]: ...

Text Search

Image Search

Searches for images with comprehensive filtering options including size, color, type, layout, and licensing filters, returning detailed metadata for each result.

def images(
    keywords: str,
    region: str = "us-en",
    safesearch: str = "moderate",
    timelimit: str | None = None,
    size: str | None = None,
    color: str | None = None, 
    type_image: str | None = None,
    layout: str | None = None,
    license_image: str | None = None,
    max_results: int | None = None
) -> list[dict[str, str]]: ...

Image Search

Video Search

Searches for videos with filtering by resolution, duration, and licensing, returning comprehensive video metadata and source information.

def videos(
    keywords: str,
    region: str = "us-en", 
    safesearch: str = "moderate",
    timelimit: str | None = None,
    resolution: str | None = None,
    duration: str | None = None,
    license_videos: str | None = None,
    max_results: int | None = None
) -> list[dict[str, str]]: ...

Video Search

News Search

Searches for news articles with time-based filtering and regional settings, returning structured news data with publication dates and source information.

def news(
    keywords: str,
    region: str = "us-en",
    safesearch: str = "moderate", 
    timelimit: str | None = None,
    max_results: int | None = None
) -> list[dict[str, str]]: ...

News Search

Command Line Interface

Complete CLI functionality for all search operations with result saving, downloading, and output formatting options.

# CLI functions from duckduckgo_search.cli module
def cli() -> None: ...
def safe_entry_point() -> None: ...

Command Line Interface

Types

class DDGS:
    """DuckDuckgo_search class to get search results from duckduckgo.com."""
    
    def __init__(
        self,
        headers: dict[str, str] | None = None,
        proxy: str | None = None,
        proxies: dict[str, str] | str | None = None,  # deprecated
        timeout: int | None = 10,
        verify: bool = True,
    ) -> None: ...
    
    def __enter__(self) -> DDGS: ...
    
    def __exit__(
        self,
        exc_type: type[BaseException] | None = None, 
        exc_val: BaseException | None = None,
        exc_tb: TracebackType | None = None,
    ) -> None: ...

class DuckDuckGoSearchException(Exception):
    """Base exception class for duckduckgo_search."""

class RatelimitException(DuckDuckGoSearchException):
    """Raised for rate limit exceeded errors during API requests."""

class TimeoutException(DuckDuckGoSearchException):
    """Raised for timeout errors during API requests."""

class ConversationLimitException(DuckDuckGoSearchException):
    """Raised for conversation limit during API requests to AI endpoint."""