DuckDuckGo from the Terminal

Tutorial – ddgr

Article from Issue 270/2023

Since 2008, DuckDuckGo has been making waves as an efficient and much more private search engine alternative to Google. The unaffiliated command-line tool ddgr is designed to make running DuckDuckGo searches from the terminal a breeze.

Linux users do have reasons to be grateful to the almighty search engine Google. After all, Google gave the world the (mostly) open source Android operating system [1]. Still, many phones and devices come preinstalled with Google's app – a firm whose bottom line is largely based on serving you more and more targeted ads. This isn't good for your privacy, and as recently as late December 2022, the search engine was fined around $57 million in France due to its handling of customers' data [2].

As Linux users, we're used to finding workarounds, so in theory it's not much trouble to "de-Google" your life. In practice, this is very difficult given Google's market dominance. DuckDuckGo was originally created by Gabriel Weinberg to address these kind of privacy worries. Out of the box, the search engine does not serve you up personalized ads, nor does it rely on content farms to display results. The results come from the search engine's own crawler as well as partnerships it has with other search sites such as Bing and Yahoo! Search.

Unlike Google, DuckDuckGo doesn't use any hidden trackers. There are adverts, but these are personalized for you. It doesn't place you in a "filter bubble" by listing search results based on your location, nor does it try to trap you in an elaborate "ecosystem" of apps for mapping, email, travel, and so on [3].

You may wonder then, given the clear privacy advantages, why everyone isn't using this challenger search engine. The short answer is that many people do: DuckDuckGo has been adopted as the default search engine in Trisquel GNU/Linux and Linux Mint, as well as the Midori and Tor web browsers. Most major web browsers such as Firefox also support it out of the box, allowing users to switch easily or allow installation via a simple extension [4].

Still, no matter how well a browser is locked down, there are still privacy issues. Even running a simple search can expose you to adverts (personalized or not) and "super cookies" (which can't be removed from your device), and there's always a risk of your search results being stored on your device, even if you use "incognito mode." As Linux users, we're at home with the command line, so it's not surprising that developer jarun created ddgr, which allows you to segue around all these privacy concerns by running DuckDuckGo searches from your terminal. If the name sounds familiar, you may remember that jarun is also the creator of googler, which operates on similar lines but with the Google search engine [5].

Although jarun has no official connection with DuckDuckGo, the utility is still one privacy lovers will want to use: Not only is it quick and easy, but it doesn't record any data about searches. Tracking is disabled by default. You can turn off user-agent strings and can even connect via an HTTPS proxy, which means you can even run searches over the Tor network. The interface is very well laid out and you can tidy it up even further using ddgr's command-line parameters. There's even support for text-based web browsers.

Installing ddgr

Assuming that we've piqued your interest, the first step is to download and run ddgr (Figure 1). The utility is available in most Linux repositories already: For instance, on Ubuntu-based systems, it's just a case of running sudo apt-get install ddgr. There's also a version in the Snap Store, which you can install with snap install ddgr. Because ddgr is written in Python, you can also use the pip3 installer. Just run sudo pip3 install ddgr.

Figure 1: Make sure you have at least Python 3.7 before installing ddgr.

If these options aren't available or you're very privacy conscious, you can also clone the Git repository and run it as a standalone executable with:

git clone

Use cd to switch to the ddgr directory and then run ./ddgr.

You'll need to run at least Python 3.7 to use ddgr. You can check your Python version in your terminal by running python3 --version. If you want to be able to copy website URLs from ddgr to the clipboard, you'll also need to have installed either xsel, xclip, or termux-clipboard-set. If you're running a Debian- or Ubuntu-based flavor [6] of Linux, it should already have xsel installed.

The utility will open search results in your default browser unless you tell it otherwise, so make sure you have this set up correctly in Linux before continuing.

Taking Flight

Once ddgr is installed, simply run your first search with ddgr KEYWORD, for instance, type ddgr lighthouses to view all DuckDuckGo search results for the term "lighthouses." By default, the utility will list the first 10 results from DuckDuckGo.

You'll next be prompted to type an omniprompt key. This takes a little getting used to at first but is actually designed very logically. Type ? and press Enter the first time you run a search to see all the available options.

If you simply want to open a search result in your browser, just type the index number (e.g., 3) and hit Return. This will open the page.

If you haven't found exactly what you're looking for, you only need to enter n once a search is complete to see the next x-number of search results. Use p to return to the previous list of results or f to return to the very start.

Use x to toggle displaying URLs within search results. You can also copy URLs to the clipboard using c+Space+the index number (e.g., c 3) provided you have a compatible program (see above).

If you've run one search and now want to run another, just enter the keywords at the omniprompt and hit Enter. If you add the flag d before running another search, ddgr will retain the same search parameters as for the original. This can be very helpful if you want to fine-tune your search results.

On the Wing

By default, ddgr will show you the top 10 results for any search term. This can produce huge amounts of text and makes scrolling difficult. Fortunately there are a number of command-line parameters you can use to tweak your DuckDuckGo searches.

One of the most useful flags is -n, which you can use to change the number of search results displayed (Figure 2). For instance, to show just three search results for "lighthouses" at a time, use ddgr Lighthouses -n 3.

Figure 2: Use the -n flag to limit the number of search results. Enter the index number for a result to open in your browser.

If you're looking for a specific search term, then you can include keywords in quotes, just as you would when searching on a browser-based search engine such as Google, for example:

ddgr "We hold these truths to be self-evident, that all men are created equal"

You can also ask ddgr to search only specific types of files using the filetype: parameter. For instance, in the example above where we look for a specific extract from the Declaration of Independence, you could also instruct ddgr to look only for PDFs containing this phrase using (Figure 3):

ddgr "We hold these truths to be self-evident, that all men are created equal" filetype:pdf
Figure 3: The utility even supports searching for certain types of files such as PDFs.

Documents such as the Declaration of Independence are easy to find, but if you're looking for more recent news, ddgr also lets you filter search results to within a particular time frame using the -t parameter followed by the time in (d)ays, (m)onths, or (y)ears. For instance, if you wanted to see what the World Wide Web has had to say about Bitcoin in the past three months, you could enter

ddgr -t m 3 bitcoin

You can refine these results still further with -w flag, which instructs ddgr to list only results from a specific website. For instance, if you wanted to read only what Linux Magazine has had to say about Bitcoin recently, you could enter

ddgr -t m 3 bitcoin -w

You can also restrict your search results to particular regions if you want. The default is the US, but you can change this with the -r flag followed by the correct parameter for the country and language. For example, to see only British English pages on the subject of lighthouses, you'd type (Figure 4):

ddgr lighthouses -n 3 -r uk-en
Figure 4: Ddgr can also show results for a particular language or region.

A full list of DuckDuckGo's regional parameters are available on the main website [7].

The utility also has its own equivalent of Google's "I'm feeling lucky," in that you can tell it just to open the first search result that appears in your browser. You can do this with the -j flag. For example, running ddgr liberty bell center -j will open the official page for the Liberty Bell Center on the National Parks Service website because that's the first search result that appears in DuckDuckGo (Figure 5).

Figure 5: If you're feeling lucky, just use -j to open the first search result in your browser.

If you're still having trouble finding what you need, you can disable safe search to see results uncensored using the --unsafe flag at your own risk (e.g., ddgr --unsafe piratebay films). You can also disable the user agent using --noua, but I found in testing this that ddgr threw up a 403 (Forbidden) error when I tried to search for new sites.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More