ddgs
installs/mo · pypistarsforks
How to install ddgs?
deedy5/ddgs
$git clone https://github.com/deedy5/ddgsA metasearch library that aggregates results from diverse web search services.
README.md
| 1 |  [](https://github.com/deedy5/ddgs/releases) [](https://pypi.org/project/ddgs) |
| 2 | # DDGS | Dux Distributed Global Search<a name="TOP"></a> |
| 3 | |
| 4 | A metasearch library that aggregates results from diverse web search services. |
| 5 | |
| 6 | |
| 7 | ## Table of Contents |
| 8 | * [Install](#install) |
| 9 | * [CLI version](#cli-version) |
| 10 | * [API Server](#api-server) |
| 11 | * [MCP Server](#mcp-server) |
| 12 | * [Engines](#engines) |
| 13 | * [DDGS class](#ddgs-class) |
| 14 | * [1. text()](#1-text) |
| 15 | * [2. images()](#2-images) |
| 16 | * [3. videos()](#3-videos) |
| 17 | * [4. news()](#4-news) |
| 18 | * [5. books()](#5-books) |
| 19 | * [6. extract()](#6-extract) |
| 20 | * [Disclaimer](#disclaimer) |
| 21 | |
| 22 | ___ |
| 23 | ## Install |
| 24 | ```python |
| 25 | pip install -U ddgs # Base install |
| 26 | pip install -U ddgs[api] # API server (FastAPI) |
| 27 | pip install -U ddgs[mcp] # MCP server (stdio) |
| 28 | ``` |
| 29 | |
| 30 | ## CLI version |
| 31 | |
| 32 | ```python3 |
| 33 | ddgs --help |
| 34 | ``` |
| 35 | |
| 36 | [Go To TOP](#TOP) |
| 37 | ___ |
| 38 | |
| 39 | ## API Server |
| 40 | |
| 41 | -- **Install** |
| 42 | ```bash |
| 43 | pip install -U ddgs[api] |
| 44 | ``` |
| 45 | |
| 46 | -- **CLI** |
| 47 | ```bash |
| 48 | ddgs api # Start server in foreground |
| 49 | ddgs api -d # Start in detached mode (background) |
| 50 | ddgs api -s # Stop detached server |
| 51 | ddgs api --host 127.0.0.1 --port 4479 # Default port 4479 |
| 52 | ddgs api -pr socks5h://127.0.0.1:9150 # With proxy |
| 53 | ``` |
| 54 | |
| 55 | -- **Docker compose** |
| 56 | ```bash |
| 57 | git clone https://github.com/deedy5/ddgs && cd ddgs |
| 58 | docker-compose up --build |
| 59 | ``` |
| 60 | |
| 61 | -- **Bash script** |
| 62 | ```bash |
| 63 | git clone https://github.com/deedy5/ddgs && cd ddgs |
| 64 | chmod +x start_api.sh |
| 65 | ./start_api.sh |
| 66 | ``` |
| 67 | |
| 68 | #### Endpoints |
| 69 | |
| 70 | | Endpoint | Method | Description | |
| 71 | |----------|--------|-------------| |
| 72 | | `/search/text` | GET, POST | Text search | |
| 73 | | `/search/images` | GET, POST | Image search | |
| 74 | | `/search/news` | GET, POST | News search | |
| 75 | | `/search/videos` | GET, POST | Video search | |
| 76 | | `/search/books` | GET, POST | Book search | |
| 77 | | `/extract` | GET, POST | Extract content from URL | |
| 78 | | `/health` | GET | Health check | |
| 79 | | `/docs` | GET | Swagger UI | |
| 80 | | `/redoc` | GET | ReDoc documentation | |
| 81 | |
| 82 | [Go To TOP](#TOP) |
| 83 | ___ |
| 84 | |
| 85 | ## MCP Server |
| 86 | |
| 87 | - **Install** |
| 88 | ```bash |
| 89 | pip install -U ddgs[mcp] |
| 90 | ``` |
| 91 | |
| 92 | - **CLI** |
| 93 | ```bash |
| 94 | ddgs mcp # Start MCP server (stdio transport) |
| 95 | ddgs mcp -pr socks5h://127.0.0.1:9150 # With proxy |
| 96 | ``` |
| 97 | |
| 98 | #### Available Tools |
| 99 | |
| 100 | | Tool | Description | |
| 101 | |------|-------------| |
| 102 | | `search_text` | Web text search | |
| 103 | | `search_images` | Image search | |
| 104 | | `search_news` | News search | |
| 105 | | `search_videos` | Video search | |
| 106 | | `search_books` | Book search | |
| 107 | | `extract_content` | Extract content from a URL | |
| 108 | |
| 109 | #### Client Configuration |
| 110 | |
| 111 | For MCP clients like Cursor or Claude Desktop: |
| 112 | ```json |
| 113 | { |
| 114 | "mcpServers": { |
| 115 | "ddgs": { |
| 116 | "command": "ddgs", |
| 117 | "args": ["mcp"] |
| 118 | } |
| 119 | } |
| 120 | } |
| 121 | ``` |
| 122 | |
| 123 | [Go To TOP](#TOP) |
| 124 | ___ |
| 125 | |
| 126 | ## Engines |
| 127 | |
| 128 | | DDGS function | Available backends | |
| 129 | | --------------|:-------------------| |
| 130 | | text() | `bing`, `brave`, `duckduckgo`, `google`, `grokipedia`, `mojeek`, `startpage`, `yandex`, `yahoo`, `wikipedia`| |
| 131 | | images() | `bing`, `duckduckgo` | |
| 132 | | videos() | `duckduckgo` | |
| 133 | | news() | `bing`, `duckduckgo`, `yahoo` | |
| 134 | | books() | `annasarchive` | |
| 135 | |
| 136 | [Go To TOP](#TOP) |
| 137 | |
| 138 | ## DDGS class |
| 139 | |
| 140 | DDGS class is lazy-loaded. |
| 141 | |
| 142 | ```python3 |
| 143 | class DDGS: |
| 144 | """Dux Distributed Global Search. A metasearch library that aggregates results from diverse web search services. |
| 145 | |
| 146 | Args: |
| 147 | proxy (str, optional): proxy for the HTTP client, supports http/https/socks5 protocols. |
| 148 | example: "http://user:pass@example.com:3128". Defaults to None. |
| 149 | timeout (int, optional): Timeout value for the HTTP client. Defaults to 5. |
| 150 | verify: (bool | str): True to verify, False to skip, or a str path to a PEM file. Defaults to True. |
| 151 | """ |
| 152 | ``` |
| 153 | |
| 154 | Here is an example of initializing the DDGS class. |
| 155 | ```python3 |
| 156 | from ddgs import DDGS |
| 157 | |
| 158 | results = DDGS().text("python programming", max_results=5) |
| 159 | print(results) |
| 160 | ``` |
| 161 | |
| 162 | [Go To TOP](#TOP) |
| 163 | |
| 164 | ## 1. text() |
| 165 | |
| 166 | ```python |
| 167 | def text( |
| 168 | query: str, |
| 169 | region: str = "us-en", |
| 170 | safesearch: st |
People who liked this also viewed
6 picksType
- firecrawl-mcp-server🔥 Official Firecrawl MCP Server - Adds powerful web scraping and search to Cursor, Claude and any other LLM clients.MCP ServersJul 2026
- fliGoogle Flights MCP, CLI and Python LibraryMCP ServersJul 2026
- sembleFast and Accurate Code Search for Agents. Uses ~98% fewer tokens than grep+readMCP ServersJul 2026
- duckduckgo-mcp-serverA Model Context Protocol (MCP) server that provides web search capabilities through DuckDuckGo, with additional features for content fetching and parsing.MCP ServersJul 2026
- wikipedia-mcpA Model Context Protocol (MCP) server that retrieves information from Wikipedia to provide context to LLMs.MCP ServersMay 2026
- arxiv-mcp-serverA Model Context Protocol server for searching and analyzing arXiv papersMCP ServersJul 2026
