# GitHub - jarun/ddgr: :duck: DuckDuckGo from the terminal [![Latest release](https://camo.githubusercontent.com/fce542c7b319fe4b54a60c1d6f23ba3fe9b88b7a9cf21847a7b6c872ef7814ac/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f6a6172756e2f646467722e7376673f6d61784167653d363030)](https://github.com/jarun/ddgr/releases/latest) [![Availability](https://camo.githubusercontent.com/d46cab5ce14c64f8ef30f40ce798ab142e5fa32209a89d4b3a74eeac095e34ac/68747470733a2f2f7265706f6c6f67792e6f72672f62616467652f74696e792d7265706f732f646467722e7376673f6865616465723d7265706f73)](https://repology.org/project/ddgr/versions) [![PyPI](https://camo.githubusercontent.com/9c2750668193688ff00d8b10f19c9adb74463a3d3377f8f6fef0d6888816a406/68747470733a2f2f696d672e736869656c64732e696f2f707970692f762f646467722e7376673f6d61784167653d363030)](https://pypi.org/project/ddgr/) [![Build Status](https://camo.githubusercontent.com/905bd0a857b6d256aad36c844ed6fd72ec13388d4b1346e2788be596c74db3f7/68747470733a2f2f696d672e736869656c64732e696f2f636972636c6563692f70726f6a6563742f6769746875622f6a6172756e2f646467722e737667)](https://circleci.com/gh/jarun/workflows/ddgr) [![Privacy Awareness](https://camo.githubusercontent.com/0cc63dbf74b07accfe854d6f9be1c06dbbd5740893cde09664e4f01da11aba51/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f707269766163792de29c932d6372696d736f6e)](https://en.wikipedia.org/wiki/Privacy-invasive_software) [![License](https://camo.githubusercontent.com/8d5b80640d86e3f13c72e617456f9294602945954c7693663f3e6713456a31f0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c76332d79656c6c6f77677265656e2e7376673f6d61784167653d32353932303030)](https://github.com/jarun/ddgr/blob/master/LICENSE) [![Asciicast](https://private-user-images.githubusercontent.com/5959286/553163056-52a51b1c-656e-41c6-85ec-3d20319fda70.svg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODQ3NTM5NzgsIm5iZiI6MTc4NDc1MzY3OCwicGF0aCI6Ii81OTU5Mjg2LzU1MzE2MzA1Ni01MmE1MWIxYy02NTZlLTQxYzYtODVlYy0zZDIwMzE5ZmRhNzAuc3ZnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDcyMiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA3MjJUMjA1NDM4WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9MWJiMmY4OTk3Y2Y3YmM5MmRjOTkxMjg4OGEzYTJjZTU2ZjM0M2IwOGVhYjEyY2IyYWM2NDkwNWVlMDU2ZWViNSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QmcmVzcG9uc2UtY29udGVudC10eXBlPWltYWdlJTJGc3ZnJTJCeG1sIn0.dJO0js8Gkmh9NLxK2PcMSy4xsfJkMT4cR6byNLrfGGk)](https://asciinema.org/a/212198) `ddgr` is a cmdline utility to search DuckDuckGo ([html version](https://html.duckduckgo.com/html/)) from the terminal. While [googler](https://github.com/jarun/googler) is extremely popular among cmdline users, in many forums the need of a similar utility for privacy-aware DuckDuckGo came up. [DuckDuckGo Bangs](https://duckduckgo.com/bang) are super-cool too! So here's `ddgr` for you! Unlike the web interface, you can specify the number of search results you would like to see per page. It's more convenient than skimming through 30-odd search results per page. The default interface is carefully designed to use minimum space without sacrificing readability. A big advantage of `ddgr` over `googler` is DuckDuckGo works over the Tor network. `ddgr` isn't affiliated to DuckDuckGo in any way. [![Donate via PayPal!](https://camo.githubusercontent.com/d7f9ec8fcb722a75d9911aa635ab55db5e3e0f694a0bfa39948c0f483fe49baa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d4050617950616c2d3165623066632e737667)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RMLTQ76JSXJ4Q) ### Table of contents [](#table-of-contents) - [Features](#features) - [Installation](#installation) - [Dependencies](#dependencies) - [From a package manager](#from-a-package-manager) - [From source](#from-source) - [Running standalone](#running-standalone) - [Shell completion](#shell-completion) - [Usage](#usage) - [Cmdline options](#cmdline-options) - [Configuration file](#configuration-file) - [Text-based browser integration](#text-based-browser-integration) - [Colors](#colors) - [Examples](#examples) - [Troubleshooting](#troubleshooting) - [Notes](#notes) - [Collaborators](#collaborators) - [In the Press](#in-the-press) ### Features [](#features) - Fast and clean; custom color - Designed for maximum readability at minimum space - Instant answers (supported by DDG html version) - Custom number of results per page - Navigation, browser integration - Search and option completion scripts (Bash, Fish, Zsh) - DuckDuckGo Bangs (along with completion) - Open the first result in browser (I'm Feeling Ducky) - REPL for continuous searches - Keywords (e.g. `filetype:mime`, `site:somesite.com`) - Limit search by time, specify region, disable safe search - HTTPS proxy support, optionally disable User Agent - Do Not Track set by default - Supports custom url handler script or cmdline utility - Privacy-aware (no unconfirmed user data collection) - Thoroughly documented, man page with examples - Minimal dependencies ### Installation [](#installation) #### Dependencies [](#dependencies) `ddgr` requires Python 3.8 or later. Only the latest patch release of each minor version is supported. To copy url to clipboard at the omniprompt, `ddgr` looks for `wl-copy` (only under Wayland) or `xsel` or `xclip` or `termux-clipboard-set` (in the same order) on Linux, `pbcopy` (default installed) on OS X, `clip` (default installed) on Windows and `clipboard` (default installed) on Haiku. It also supports GNU Screen and tmux copy-paste buffers in the absence of X11. Note: v1.1 and below require the Python3 `requests` library to make HTTPS requests. This dependency is removed in the later releases. #### From a package manager [](#from-a-package-manager) Install `ddgr` from your package manager. If the version available is dated try an alternative installation method. Packaging status (expand) [![Packaging status](https://camo.githubusercontent.com/e5eb20e0f2c66c3571456fa8f69efb23ac0cb888385dac36c18c733383edf0bf/68747470733a2f2f7265706f6c6f67792e6f72672f62616467652f766572746963616c2d616c6c7265706f732f646467722e737667)](https://repology.org/project/ddgr/versions) Unlisted packagers: ● [Awesome](https://github.com/shinokada/awesome) (`awesome -install jarun/ddgr`) ● [PyPI](https://pypi.org/project/ddgr/) (`pip3 install ddgr`) ● [Snap Store](https://snapcraft.io/ddgr/) (`snap install ddgr`) ● [Source Mage](http://codex.sourcemage.org/test/utils/ddgr/) (`cast ddgr`) ● Termux (`pip3 install ddgr`) #### From source [](#from-source) If you have git installed, clone this repository. Otherwise download the [latest stable release](https://github.com/jarun/ddgr/releases/latest) or [development version](https://github.com/jarun/ddgr/archive/master.zip). To install to the default location (`/usr/local`): To remove `ddgr` and associated docs, run `PREFIX` is supported, in case you want to install to a different location. #### Running standalone [](#running-standalone) `ddgr` is a standalone executable (and can run even on environments like Termux). From the containing directory: #### Shell completion [](#shell-completion) Search keyword and option completion scripts for Bash, Fish and Zsh can be found in respective subdirectories of [`auto-completion/`](https://github.com/jarun/ddgr/blob/main/auto-completion). Please refer to your shell's manual for installation instructions. ### Usage [](#usage) #### Cmdline options [](#cmdline-options) ``` usage: ddgr [-h] [-n N] [-r REG] [--colorize [{auto,always,never}]] [-C] [--colors COLORS] [-j] [-t SPAN] [-w SITE] [-x] [-p URI] [--unsafe] [--noua] [--json] [--gb] [--np] [--url-handler UTIL] [--show-browser-logs] [-v] [-d] [KEYWORD [KEYWORD ...]] DuckDuckGo from the terminal. positional arguments: KEYWORD search keywords optional arguments: -h, --help show this help message and exit -n N, --num N show N (0<=N<=25) results per page (default 10); N=0 shows actual number of results fetched per page -r REG, --reg REG region-specific search e.g. 'us-en' for US (default); visit https://duckduckgo.com/params --colorize [{auto,always,never}] whether to colorize output; defaults to 'auto', which enables color when stdout is a tty device; using --colorize without an argument is equivalent to --colorize=always -C, --nocolor equivalent to --colorize=never --colors COLORS set output colors (see man page for details) -j, --ducky open the first result in a web browser; implies --np -i, --instant retrieve only an instant answer -t SPAN, --time SPAN time limit search [d (1 day), w (1 wk), m (1 month), y (1 year)] -w SITE, --site SITE search sites using DuckDuckGo -x, --expand Show complete url in search results -p URI, --proxy URI tunnel traffic through an HTTPS proxy; URI format: [http[s]://][user:pwd@]host[:port] --unsafe disable safe search --noua disable user agent --json output in JSON format; implies --np --gb, --gui-browser open a bang directly in gui browser --np, --noprompt perform search and exit, do not prompt --rev, --reverse list entries in reversed order --url-handler UTIL custom script or cli utility to open results --show-browser-logs do not suppress browser output (stdout and stderr) -v, --version show program's version number and exit -d, --debug enable debugging omniprompt keys: n, p, f fetch the next, prev or first set of search results index open the result corresponding to index in browser o [index|range|a ...] open space-separated result indices, ranges or all O [index|range|a ...] like key 'o', but try to open in a GUI browser d keywords new DDG search for 'keywords' with original options should be used to search omniprompt keys and indices x toggle url expansion c index copy url to clipboard q, ^D, double Enter exit ddgr ? show omniprompt help * other inputs are considered as new search keywords ``` #### Configuration file [](#configuration-file) `ddgr` doesn't have any! Use aliases, environment variables and auto-completion scripts. #### Text-based browser integration [](#text-based-browser-integration) `ddgr` works out of the box with several text-based browsers if the `BROWSER` environment variable is set. For instance, or for one-time use, Due to certain graphical browsers spewing messages to the console, `ddgr` suppresses browser output by default unless `BROWSER` is set to one of the known text-based browsers: currently `elinks`, `links`, `lynx`, `w3m` or `www-browser`. If you use a different text-based browser, you will need to explicitly enable browser output with the `--show-browser-logs` option. If you believe your browser is popular enough, please submit an issue or pull request and we will consider whitelisting it. See the man page for more details on `--show-browser-logs`. If you need to use a GUI browser with `BROWSER` set, use the omniprompt key `O`. `ddgr` will try to ignore text-based browsers and invoke a GUI browser. Browser logs are always suppressed with `O`. #### url handler [](#url-handler) Try the included url handler and report broken links ddgr --url-handler urlhandler #### Colors [](#colors) The color configuration is similar to that of [`googler` colors](https://github.com/jarun/googler#colors). The default color string is `oCdgxy`. `ddgr` recognizes the environment variable `DDGR_COLORS`. Details are available in the `ddgr` man page. ### Examples [](#examples) 01. DuckDuckGo **hello world**: 02. **I'm Feeling Ducky** search: 03. **DuckDuckGo Bang** search `hello world` in Wikipedia: ``` $ ddgr !w hello world $ ddgr \!w hello world // in (some) shells (e.g. bash, zsh, tcsh) '!' character need to be escaped ``` Bangs work at the omniprompt too. To look up bangs, visit [https://duckduckgo.com/bang?#bangs-list](https://duckduckgo.com/bang?#bangs-list). 04. **Bang alias** to fire from the cmdline, open results in a GUI browser and exit: ``` alias bang='ddgr --gb --np' $ bang !w hello world $ bang \!w hello world // in (some) shells (e.g. bash, zsh, tcsh) '!' character need to be escaped ``` 05. **Website specific** search: ``` $ ddgr -w amazon.com digital camera ``` Site specific search continues at omniprompt. 06. Search for a **specific file type**: ``` $ ddgr instrumental filetype:mp3 ``` 07. Fetch results on IPL cricket from **India** in **English**: ``` $ ddgr -r in-en IPL cricket ``` To find your region parameter token visit [https://duckduckgo.com/params](https://duckduckgo.com/params). 08. Search **quoted text**: ``` $ ddgr it\'s a \"beautiful world\" in spring ``` 09. Show **complete urls** in search results (instead of only domain name): 10. Use a **custom color scheme**, e.g., one warm color scheme designed for Solarized Dark: ``` $ ddgr --colors bjdxxy hello world $ DDGR_COLORS=bjdxxy ddgr hello world ``` 11. Tunnel traffic through an **HTTPS proxy**, e.g., a local Privoxy instance listening on port 8118: ``` $ ddgr --proxy localhost:8118 hello world ``` By default the environment variable `https_proxy` (or `HTTPS_PROXY`) is used, if defined. 12. Look up `n`, `p`, `o`, `O`, `q`, `d keywords` or a result index at the **omniprompt**: as the omniprompt recognizes these keys or index strings as commands, you need to prefix them with `d`, e.g., ### Troubleshooting [](#troubleshooting) 1. Some users have reported problems with a colored omniprompt (refer to issue [#40](https://github.com/jarun/ddgr/issues/40)) with iTerm2 on OS X. To force a plain omniprompt: ``` export DISABLE_PROMPT_COLOR=1 ``` ### Notes [](#notes) 1. The Albert Launcher python plugins repo ([awesome-albert-plugins](https://github.com/bergercookie/awesome-albert-plugins)) includes suggestions-enabled search plugins for a variety of websites using `ddgr`. Refer to the latter for demos and usage instructions. ### Collaborators [](#collaborators) - [Arun Prakash Jana](https://github.com/jarun) - [Johnathan Jenkins](https://github.com/shaggytwodope) - [SZ Lin](https://github.com/szlin) - [Alex Gontar](https://github.com/mosegontar) Copyright © 2016-2026 [Arun Prakash Jana](mailto:engineerarun@gmail.com) ### In the Press [](#in-the-press) - [Fossbytes](https://fossbytes.com/search-duckduckgo-from-terminal-ddgr/) - [Hacker News](https://news.ycombinator.com/item?id=19606101) - [Information Security Squad](http://itsecforu.ru/2017/11/21/%D0%BA%D0%B0%D0%BA-%D0%B8%D1%81%D0%BA%D0%B0%D1%82%D1%8C-%D0%B2-duckduckgo-%D0%B8%D0%B7-%D0%BA%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D0%BD%D0%BE%D0%B9-%D1%81%D1%82%D1%80%D0%BE%D0%BA%D0%B8-linux/) - [LinOxide](https://linoxide.com/tools/search-duckduckgo-command-line/) - [OMG! Ubuntu!](http://www.omgubuntu.co.uk/2017/11/duck-duck-go-terminal-app) - [Tecmint](https://www.tecmint.com/search-duckduckgo-from-linux-terminal/)