Install & Compatibility
Where this runs
tested against v9.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.028s · 45.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.024s · 45MB
44MB installed
● package 44MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DDGS
✓ from ddgs import DDGS
✗ from duckduckgo_search import DDGS
The package was renamed from 'duckduckgo_search' to 'ddgs'.
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')}")
Debug
Known issues
breakingThe 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.fixUninstall `duckduckgo-search` and install `ddgs` via `pip install --upgrade ddgs`. Update all imports from `from duckduckgo_search import DDGS` to `from ddgs import DDGS`.
affects: All versions 9.0.0 and above
breakingPython 3.9 support was dropped in version 9.9.0. Projects using `ddgs` (version 9.9.0+) must use Python 3.10 or newer.fixEnsure your project's Python environment is 3.10 or higher. Upgrade Python if necessary.
affects: 9.9.0 and above
gotchaThe 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.fixKeep the `ddgs` library updated to the latest version. The developers frequently release fixes for backend changes. Monitor GitHub releases for relevant updates.
affects: All versions
gotchaFrequent or high-volume requests without proper proxy management can lead to rate limiting or IP bans from search engines.fixUtilize 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.
affects: All versions
gotchaThe 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.fixAlways access results by indexing the list (e.g., `results[0]`) after checking if the list is not empty.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ddgs'
The 'ddgs' package has not been installed in your Python environment or the environment where your code is running.
fixInstall the package using pip: `pip install ddgs`
ImportError: cannot import name 'DDGS' from partially initialized module 'du'
This error typically occurs due to a circular import, incorrect module path, or if you have a local file named 'du.py' that conflicts with a module being imported.
fixRename any local files or modules that might conflict with Python's import system, or restructure your code to avoid circular dependencies.
ImportError: cannot import name 'ddg_images' from 'duckduckgo_search'
You are trying to import a deprecated function (`ddg_images`) or class from an older version of the `duckduckgo_search` library. The `ddgs` library (and newer versions of `duckduckgo_search`) uses a class-based interface.
fixUpdate your code to import the `DDGS` class and use its methods, for example: `from ddgs import DDGS` and then `DDGS().images(...)`.
Upgrade
Version history
9.16.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
lxmlrequiredHTML parsing
primprequiredDependency management
clickrequiredCommand-line interface (CLI)