A self-hosted, ad-free, privacy-respecting metasearch engine
<a href="https://sr.ht/~benbusby/whoogle-search" rel="nofollow">SourceHut</a>
<a href="https://github.com/benbusby/whoogle-search" rel="nofollow">GitHub</a>
Get Google search results, but without any ads, JavaScript, AMP links, cookies, or IP address tracking. Easily deployable in one click as a Docker app, and customizable with a single config file. Quick and simple to implement as a primary search engine replacement on both desktop and mobile.
Contents
!<tag> <query>
) searches*No third party JavaScript. Whoogle can be used with JavaScript disabled, but if enabled, uses JavaScript for things like presenting search suggestions.
**No third party cookies. Whoogle uses server side cookies (sessions) to store non-sensitive configuration settings such as theme, language, etc. Just like with JavaScript, cookies can be disabled and not affect Whoogle's search functionality.
***If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.
Install
There are a few different ways to begin using the app, depending on your preferences:
Provides:
Notes:
https
. Make sure to navigate to the https
version of your app before adding as a default search engine.Note: Requires a (free) Replit account
Provides:
You will need a Fly.io account to deploy Whoogle. The free allowances are enough for personal use.
Install the CLI: https://fly.io/docs/hands-on/installing/
Deploy the app
flyctl auth login flyctl launch --image benbusby/whoogle-search:latest
The first deploy won't succeed because the default internal_port
is wrong.
To fix this, open the generated fly.toml
file, set services.internal_port
to 5000
and run flyctl launch
again.
Your app is now available at https://<app-name>.fly.dev
.
Use one of the following guides to install Whoogle on Koyeb:
Persistent install:
pipx install git+https://github.com/benbusby/whoogle-search.git
Sandboxed temporary instance:
pipx run --spec git+https://github.com/benbusby/whoogle-search.git whoogle-search
pip
pip install whoogle-search
$ whoogle-search --help usage: whoogle-search [-h] [--port <port number>] [--host <ip address>] [--debug] [--https-only] [--userpass <username:password>] [--proxyauth <username:password>] [--proxytype <socks4|socks5|http>] [--proxyloc <location:port>]Whoogle Search console runner
optional arguments: -h, --help Show this help message and exit --port <port number> Specifies a port to run on (default 5000) --host <ip address> Specifies the host address to use (default 127.0.0.1) --debug Activates debug mode for the server (default False) --https-only Enforces HTTPS redirects for all requests --userpass <username:password> Sets a username/password basic auth combo (default None) --proxyauth <username:password> Sets a username/password for a HTTP/SOCKS proxy (default None) --proxytype <socks4|socks5|http> Sets a proxy type for all connections (default None) --proxyloc <location:port> Sets a proxy location for all connections (default None)
See the available environment variables for additional configuration.
Manual
Note: Content-Security-Policy
headers can be sent by Whoogle if you set WHOOGLE_CSP
.
Dependencies
libcurl4-openssl-dev
and libssl-dev
brew install openssl curl-openssl
sudo apt-get install -y libcurl4-openssl-dev libssl-dev
pacman -S curl openssl
Clone the repo and run the following commands to start the app in a local-only environment:
git clone https://github.com/benbusby/whoogle-search.git cd whoogle-search python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ./run
See the available environment variables for additional configuration.
systemd Configuration
After building the virtual environment, you can add something like the following to /lib/systemd/system/whoogle.service
to set up a Whoogle Search systemd service:
[Unit] Description=Whoogle[Service]
Basic auth configuration, uncomment to enable
Environment=WHOOGLE_USER=<username>
Environment=WHOOGLE_PASS=<password>
Proxy configuration, uncomment to enable
Environment=WHOOGLE_PROXY_USER=<proxy username>
Environment=WHOOGLE_PROXY_PASS=<proxy password>
Environment=WHOOGLE_PROXY_TYPE=<proxy type (http|https|proxy4|proxy5)
Environment=WHOOGLE_PROXY_LOC=<proxy host/ip>
Site alternative configurations, uncomment to enable
Note: If not set, the feature will still be available
with default values.
Environment=WHOOGLE_ALT_TW=farside.link/nitter
Environment=WHOOGLE_ALT_YT=farside.link/invidious
Environment=WHOOGLE_ALT_RD=farside.link/libreddit
Environment=WHOOGLE_ALT_MD=farside.link/scribe
Environment=WHOOGLE_ALT_TL=farside.link/lingva
Environment=WHOOGLE_ALT_IMG=farside.link/rimgo
Environment=WHOOGLE_ALT_WIKI=farside.link/wikiless
Environment=WHOOGLE_ALT_IMDB=farside.link/libremdb
Environment=WHOOGLE_ALT_QUORA=farside.link/quetre
Load values from dotenv only
Environment=WHOOGLE_DOTENV=1
Type=simple User=<username>
If installed as a package, add:
ExecStart=<python_install_dir>/python3 <whoogle_install_dir>/whoogle-search --host 127.0.0.1 --port 5000
For example:
ExecStart=/usr/bin/python3 /home/my_username/.local/bin/whoogle-search --host 127.0.0.1 --port 5000
Otherwise if running the app from source, add:
ExecStart=<whoogle_repo_dir>/run
For example:
ExecStart=/var/www/whoogle-search/run
WorkingDirectory=<whoogle_repo_dir> ExecReload=/bin/kill -HUP $MAINPID Restart=always RestartSec=3 SyslogIdentifier=whoogle
[Install] WantedBy=multi-user.target
Then,
sudo systemctl daemon-reload
sudo systemctl enable whoogle
sudo systemctl start whoogle
Tor Configuration optional
If routing your request through Tor you will need to make the following adjustments. Due to the nature of interacting with Google through Tor we will need to be able to send signals to Tor and therefore authenticate with it.
There are two authentication methods, password and cookie. You will need to make changes to your torrc:
Cookie
Uncomment or add the following lines in your torrc:
ControlPort 9051
CookieAuthentication 1
DataDirectoryGroupReadable 1
CookieAuthFileGroupReadable 1
Make the tor auth cookie readable:
whoogle
with that user.chmod tor:whoogle /var/lib/tor
chmod tor:whoogle /var/lib/tor/control_auth_cookie
Restart the tor service:
systemctl restart tor
Set the Tor environment variable to 1, WHOOGLE_CONFIG_TOR
. Refer to the Environment Variables section for more details.
WHOOGLE_CONFIG_TOR=1
Password
Run this command:
tor --hash-password {Your Password Here}
; put your password in place of {Your Password Here}
.Uncomment or add the following lines in your torrc:
ControlPort 9051
HashedControlPassword {Place output here}
; put the output of the previous command in place of {Place output here}
.Now take the password from the first step and place it in the control.conf file within the whoogle working directory, ie. misc/tor/control.conf
WHOOGLE_TOR_CONF
environment variable. Refer to the Environment Variables section for more details.Heavily restrict access to control.conf to only be readable by the user running whoogle:
chmod 400 control.conf
Finally set the Tor environment variable and use password variable to 1, WHOOGLE_CONFIG_TOR
and WHOOGLE_TOR_USE_PASS
. Refer to the Environment Variables section for more details.
WHOOGLE_CONFIG_TOR=1
WHOOGLE_TOR_USE_PASS=1
Manual (Docker)
sudo usermod -aG docker yourusername
docker ps
should return something besides an error. If you encounter an error saying the daemon isn't running, try sudo systemctl start docker
(Linux) or ensure the docker tool is running (Windows/macOS).Docker CLI
Through Docker Hub:
docker pull benbusby/whoogle-search docker run --publish 5000:5000 --detach --name whoogle-search benbusby/whoogle-search:latest
or with docker-compose:
git clone https://github.com/benbusby/whoogle-search.git cd whoogle-search docker-compose up
or by building yourself:
git clone https://github.com/benbusby/whoogle-search.git cd whoogle-search docker build --tag whoogle-search:1.0 . docker run --publish 5000:5000 --detach --name whoogle-search whoogle-search:1.0
Optionally, you can also enable some of the following environment variables to further customize your instance:
docker run --publish 5000:5000 --detach --name whoogle-search \ -e WHOOGLE_USER=username \ -e WHOOGLE_PASS=password \ -e WHOOGLE_PROXY_USER=username \ -e WHOOGLE_PROXY_PASS=password \ -e WHOOGLE_PROXY_TYPE=socks5 \ -e WHOOGLE_PROXY_LOC=ip \ whoogle-search:1.0
And kill with: docker rm --force whoogle-search
Using Heroku CLI
heroku login heroku container:login git clone https://github.com/benbusby/whoogle-search.git cd whoogle-search heroku create heroku container:push web heroku container:release web heroku open
This series of commands can take a while, but once you run it once, you shouldn't have to run it again. The final command, heroku open
will launch a tab in your web browser, where you can test out Whoogle and even set it as your primary search engine.
You may also edit environment variables from your app’s Settings tab in the Heroku Dashboard.
Arch Linux & Arch-based Distributions
There is an AUR package available, as well as a pre-built and daily updated package available at Chaotic-AUR.
Helm chart for Kubernetes
To use the Kubernetes Helm Chart:
>=3.0.0
installedhelm install whoogle ./charts/whoogle
Using your own server, or alternative container deployment
There are other methods for deploying docker containers that are well outlined in this article, but there are too many to describe set up for each here. Generally it should be about the same amount of effort as the Heroku deployment.
Depending on your preferences, you can also deploy the app yourself on your own infrastructure. This route would require a few extra steps:
Environment Variables
There are a few optional environment variables available for customizing a Whoogle instance. These can be set manually, or copied into whoogle.env
and enabled for your preferred deployment method:
WHOOGLE_DOTENV=1
before runningdocker-compose
: Uncomment the env_file
optiondocker build/run
: Add --env-file ./whoogle.env
to your commandVariable Description
WHOOGLE_URL_PREFIX The URL prefix to use for the whoogle instance (i.e. "/whoogle")
WHOOGLE_DOTENV
Load environment variables in whoogle.env
WHOOGLE_USER The username for basic auth. WHOOGLE_PASS must also be set if used.
WHOOGLE_PASS The password for basic auth. WHOOGLE_USER must also be set if used.
WHOOGLE_PROXY_USER The username of the proxy server.
WHOOGLE_PROXY_PASS The password of the proxy server.
WHOOGLE_PROXY_TYPE The type of the proxy server. Can be "socks5", "socks4", or "http".
WHOOGLE_PROXY_LOC The location of the proxy server (host or ip).
WHOOGLE_USER_AGENT The desktop user agent to use. Defaults to a randomly generated one.
WHOOGLE_USER_AGENT_MOBILE The mobile user agent to use. Defaults to a randomly generated one.
WHOOGLE_USE_CLIENT_USER_AGENT Enable to use your own user agent for all requests. Defaults to false.
WHOOGLE_REDIRECTS Specify sites that should be redirected elsewhere. See custom redirecting.
EXPOSE_PORT The port where Whoogle will be exposed.
HTTPS_ONLY Enforce HTTPS. (See here)
WHOOGLE_ALT_TW The twitter.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_YT The youtube.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_RD The reddit.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_TL The Google Translate alternative to use. This is used for all "translate ____" searches. Set to "" to disable.
WHOOGLE_ALT_MD The medium.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_IMG The imgur.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_WIKI The wikipedia.org alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_IMDB The imdb.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_ALT_QUORA The quora.com alternative to use when site alternatives are enabled in the config. Set to "" to disable.
WHOOGLE_AUTOCOMPLETE Controls visibility of autocomplete/search suggestions. Default on -- use '0' to disable.
WHOOGLE_MINIMAL Remove everything except basic result cards from all search queries.
WHOOGLE_CSP Sets a default set of 'Content-Security-Policy' headers
WHOOGLE_RESULTS_PER_PAGE Set the number of results per page
WHOOGLE_TOR_SERVICE Enable/disable the Tor service on startup. Default on -- use '0' to disable.
WHOOGLE_TOR_USE_PASS Use password authentication for tor control port.
WHOOGLE_TOR_CONF The absolute path to the config file containing the password for the tor control port. Default: ./misc/tor/control.conf WHOOGLE_TOR_PASS must be 1 for this to work.
Config Environment Variables
These environment variables allow setting default config values, but can be overwritten manually by using the home page config menu. These allow a shortcut for destroying/rebuilding an instance to the same config state every time.
Variable Description
WHOOGLE_CONFIG_DISABLE Hide config from UI and disallow changes to config by client
WHOOGLE_CONFIG_COUNTRY Filter results by hosting country
WHOOGLE_CONFIG_LANGUAGE Set interface language
WHOOGLE_CONFIG_SEARCH_LANGUAGE Set search result language
WHOOGLE_CONFIG_BLOCK Block websites from search results (use comma-separated list)
WHOOGLE_CONFIG_BLOCK_TITLE Block search result with a REGEX filter on title
WHOOGLE_CONFIG_BLOCK_URL Block search result with a REGEX filter on URL
WHOOGLE_CONFIG_THEME Set theme mode (light, dark, or system)
WHOOGLE_CONFIG_SAFE Enable safe searches
WHOOGLE_CONFIG_ALTS Use social media site alternatives (nitter, invidious, etc)
WHOOGLE_CONFIG_NEAR Restrict results to only those near a particular city
WHOOGLE_CONFIG_TOR Use Tor routing (if available)
WHOOGLE_CONFIG_NEW_TAB Always open results in new tab
WHOOGLE_CONFIG_VIEW_IMAGE Enable View Image option
WHOOGLE_CONFIG_GET_ONLY Search using GET requests only
WHOOGLE_CONFIG_URL
The root url of the instance (https://<your url>/
)
WHOOGLE_CONFIG_STYLE The custom CSS to use for styling (should be single line)
WHOOGLE_CONFIG_PREFERENCES_ENCRYPTED Encrypt preferences token, requires preferences key
WHOOGLE_CONFIG_PREFERENCES_KEY Key to encrypt preferences in URL (REQUIRED to show url)
WHOOGLE_CONFIG_ANON_VIEW Include the "anonymous view" option for each search result
Usage
Same as most search engines, with the exception of filtering by time range.
To filter by a range of time, append ":past " to the end of your search, where can be hour
, day
, month
, or year
. Example: coronavirus updates :past hour
Extra Steps Set Whoogle as your primary search engine
Note: If you're using a reverse proxy to run Whoogle Search, make sure the "Root URL" config option on the home page is set to your URL before going through these steps.
Browser settings:
http[s]://\<your whoogle url\>/search?q=%s
https://\<your whoogle url\>/search?q=%s
Go to Alfred Preferences
> Features
> Web Search
and click Add Custom Search
. Then configure these settings
Whoogle for '{query}'
(or whatever you want)whoogle
Go to Default Results
and click the Setup fallback results
button. Click +
and add Whoogle, then drag it to the top.
<whoogle url>/search?q=%s
formatted search URL.You can set custom site redirects using the WHOOGLE_REDIRECTS
environment
variable. A lot of sites, such as Twitter, Reddit, etc, have built-in redirects
to Farside links, but you may want to define
your own.
To do this, you can use the following syntax:
WHOOGLE_REDIRECTS="<parent_domain>:<new_domain>"
For example, if you want to redirect from "badsite.com" to "goodsite.com":
WHOOGLE_REDIRECTS="badsite.com:goodsite.com"
This can be used for multiple sites as well, with comma separation:
WHOOGLE_REDIRECTS="badA.com:goodA.com,badB.com:goodB.com"
NOTE: Do not include "http(s)://" when defining your redirect.
Prevent Downtime (Heroku only)
Part of the deal with Heroku's free tier is that you're allocated 550 hours/month (meaning it can't stay active 24/7), and the app is temporarily shut down after 30 minutes of inactivity. Once it becomes inactive, any Whoogle searches will still work, but it'll take an extra 10-15 seconds for the app to come back online before displaying the result, which can be frustrating if you're in a hurry.
A good solution for this is to set up a simple cronjob on any device at your home that is consistently powered on and connected to the internet (in my case, a PiHole worked perfectly). All the device needs to do is fetch app content on a consistent basis to keep the app alive in whatever ~17 hour window you want it on (17 hrs * 31 days = 527, meaning you'd still have 23 leftover hours each month if you searched outside of your target window).
For instance, adding */20 7-23 * * * curl https://<your heroku app name>.herokuapp.com > /home/<username>/whoogle-refresh
will fetch the home page of the app every 20 minutes between 7am and midnight, allowing for downtime from midnight to 7am. And again, this wouldn't be a hard limit - you'd still have plenty of remaining hours of uptime each month in case you were searching after this window has closed.
Since the instance is destroyed and rebuilt after inactivity, config settings will be reset once the app enters downtime. If you have configuration settings active that you'd like to keep between periods of downtime (like dark mode for example), you could instead add */20 7-23 * * * curl -d "dark=1" -X POST https://<your heroku app name>.herokuapp.com/config > /home/<username>/whoogle-refresh
to keep these settings more or less permanent, and still keep the app from entering downtime when you're using it.
HTTPS Enforcement
Only needed if your setup requires Flask to redirect to HTTPS on its own -- generally this is something that doesn't need to be handled by Whoogle Search.
Note: You should have your own domain name and an https certificate in order for this to work properly.
Root URL
configuration on the home page begins with https://
and not http://
--build-arg use_https=1
to your run command--https-only
flag to the end of the whoogle-search
commandrun
script: Modify the script locally to include the --https-only
flag at the end of the python run commandUsing with Firefox Containers
Unfortunately, Firefox Containers do not currently pass through POST
requests (the default) to the engine, and Firefox caches the opensearch template on initial page load. To get around this, you can take the following steps to get it working as expected:
GET Requests Only
in Whoogle configReverse Proxying Nginx
Here is a sample Nginx config for Whoogle:
server {
server_name your_domain_name.com;
access_log /dev/null;
error_log /dev/null;
location / {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;
proxy_set_header X-NginX-Proxy true;
proxy_pass http://localhost:5000;
}
}
You can then add SSL support using LetsEncrypt by following a guide such as this one.
Contributing
Under the hood, Whoogle is a basic Flask app with the following structure:
app/
routes.py
: Primary app entrypoint, contains all API routesrequest.py
: Handles all outbound requests, including proxied/Tor connectivityfilter.py
: Functions and utilities used for filtering out content from upstream Google search resultsutils/
bangs.py
: All logic related to handling DDG-style "bang" queriesresults.py
: Utility functions for interpreting/modifying individual search resultssearch.py
: Creates and handles new search queriessession.py
: Miscellaneous methods related to user sessionstemplates/
index.html
: The home page templatedisplay.html
: The search results templateheader.html
: A general "top of the page" query header for desktop and mobilesearch.html
: An iframe-able search pagelogo.html
: A template consisting mostly of the Whoogle logo as an SVG (separated to help keep index.html
a bit cleaner)opensearch.xml
: A template used for supporting OpenSearch.imageresults.html
: An "experimental" template used for supporting the "Full Size" image feature on desktop.static/<css|js>
static/settings
If you're new to the project, the easiest way to get started would be to try fixing an open bug report. If there aren't any open, or if the open ones are too stale, try taking on a feature request. Generally speaking, if you can write something that has any potential of breaking down in the future, you should write a test for it.
The project follows the PEP 8 Style Guide, but is liable to change. Static typing should always be used when possible. Function documentation is greatly appreciated, and typically follows the below format:
def contains(x: list, y: int) -> bool: """Check a list (x) for the presence of an element (y)Args: x: The list to inspect y: The int to look for Returns: bool: True if the list contains the item, otherwise False """ return y in x</pre>
Translating
Whoogle currently supports translations using
translations.json
. Language values in this file need to match the "value" of the according language inlanguages.json
(i.e. "lang_en" for English, "lang_es" for Spanish, etc). After you add a new set of translations totranslations.json
, open a PR with your changes and they will be merged in as soon as possible.FAQ
What's the difference between this and Searx?
Whoogle is intended to only ever be deployed to private instances by individuals of any background, with as little effort as possible. Prior knowledge of/experience with the command line or deploying applications is not necessary to deploy Whoogle, which isn't the case with Searx. As a result, Whoogle is missing some features of Searx in order to be as easy to deploy as possible.
Whoogle also only uses Google search results, not Bing/Quant/etc, and uses the existing Google search UI to make the transition away from Google search as unnoticeable as possible.
I'm a huge fan of Searx though and encourage anyone to use that instead if they want access to other search engines/a different UI/more configuration.
Why does the image results page look different?
A lot of the app currently piggybacks on Google's existing support for fetching results pages with JavaScript disabled. To their credit, they've done an excellent job with styling pages, but it seems that the image results page - particularly on mobile - is a little rough. Moving forward, with enough interest, I'd like to transition to fetching the results and parsing them into a unique Whoogle-fied interface that I can style myself.
Public Instances
Note: Use public instances at your own discretion. The maintainers of Whoogle do not personally validate the integrity of any other instances. Popular public instances are more likely to be rate-limited or blocked.
Website Country Language Cloudflare
https://search.albony.xyz 🇮🇳 IN Multi-choice
https://search.garudalinux.org 🇫🇮 FI Multi-choice ✅
https://search.dr460nf1r3.org 🇩🇪 DE Multi-choice ✅
https://s.tokhmi.xyz 🇺🇸 US Multi-choice ✅
https://search.sethforprivacy.com 🇩🇪 DE English
https://whoogle.dcs0.hu ðŸ‡ðŸ‡º HU Multi-choice
https://gowogle.voring.me 🇺🇸 US Multi-choice
https://whoogle.privacydev.net 🇫🇷 FR English
https://wg.vern.cc 🇺🇸 US English
https://whoogle.hxvy0.gq 🇨🇦 CA Turkish Only ✅
https://whoogle.hostux.net 🇫🇷 FR Multi-choice
https://whoogle.lunar.icu 🇩🇪 DE Multi-choice ✅
https://wgl.frail.duckdns.org 🇧🇷 BR Multi-choice
https://whoogle.no-logs.com 🇸🇪 SE Multi-choice
https://whoogle.ftw.lol 🇩🇪 DE Multi-choice
https://whoogle-search--replitcomreside.repl.co 🇺🇸 US English
https://search.notrustverify.ch 🇨🇠CH Multi-choice
https://whoogle.datura.network 🇩🇪 DE Multi-choice
https://whoogle.yepserver.xyz 🇺🇦 UA Multi-choice
Onion Instances
Website Country Language
http://whoglqjdkgt2an4tdepberwqz3hk7tjo4kqgdnuj77rt7nshw2xqhqad.onion 🇺🇸 US Multi-choice
http://nuifgsnbb2mcyza74o7illtqmuaqbwu4flam3cdmsrnudwcmkqur37qd.onion 🇩🇪 DE English
http://whoogle.vernccvbvyi5qhfzyqengccj7lkove6bjot2xhh5kajhwvidqafczrad.onion 🇺🇸 US English
http://whoogle.g4c3eya4clenolymqbpgwz3q3tawoxw56yhzk4vugqrl6dtu3ejvhjid.onion 🇫🇷 FR English
http://whoogle.daturab6drmkhyeia4ch5gvfc2f3wgo6bhjrv3pz6n7kxmvoznlkq4yd.onion 🇩🇪 DE Multi-choice
I2P Instances
Website Country Language
http://verneks7rfjptpz5fpii7n7nrxilsidi2qxepeuuf66c3tsf4nhq.b32.i2p 🇺🇸 US English
Screenshots Desktop
Mobile
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.