Whoogle
Container
Self-hosted, ad-free, privacy-respecting Google metasearch engine.
Image details
Source details
Configuration
TypeContainerlinuxbenbusby/whoogle-search:latest5001:5000/tcp/config : /portainer/Files/AppData/Config/Whoogleunless-stoppedTemplate by novaspirit
Notes
Check our Github page: https://github.com/pi-hosted/pi-hosted
Official Webpage: https://github.com/benbusby/whoogle-search
Official Docker Documentation: https://github.com/benbusby/whoogle-search#g-manual-docker
Pre-installation script must be RAN before you install: wget -qO- https://raw.githubusercontent.com/pi-hosted/pi-hosted/master/tools/install_whoogle.sh | bash
Youtube Video: Novaspirit Tech - How to Install Whoogle to replace using Google and repo notes
Standalone Install
Select an install method, to see config/commands for deploying Whoogle
Install on Portainer
Import all app templates into your Portainer instance, for easy 1-click deploys
- Ensure both Docker and Portainer are installed, and up-to-date
- Log into your Portainer web UI
- Under Settings → App Templates, paste the below URL
- Head to Home → App Templates, and the list of apps will show up
- Select Whoogle, fill in any config options, and hit Deploy
Template Import URL
https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me
More install options in our documentation, or see benbusby/whoogle-search for app-specific guidance.

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
1. [Heroku Quick Deploy](#a-heroku-quick-deploy)
2. [Repl.it](#b-replit)
3. [Fly.io](#c-flyio)
4. [pipx](#d-pipx)
5. [pip](#e-pip)
6. [Manual](#f-manual)
7. [Docker](#g-manual-docker)
8. [Arch/AUR](#arch-linux--arch-based-distributions)1. [Set Primary Search Engine](#set-whoogle-as-your-primary-search-engine)
2. [Prevent Downtime (Heroku Only)](#prevent-downtime-heroku-only)
3. [Manual HTTPS Enforcement](#https-enforcement)
4. [Using with Firefox Containers](#using-with-firefox-containers)- Contributing
- FAQ
- Public Instances
- Screenshots
- Mirrors (read-only)
1. [GitLab](https://gitlab.com/benbusby/whoogle-search)
2. [Gogs](https://gogs.benbusby.com/benbusby/whoogle-search)Features
- No ads or sponsored content
- No javascript
- No cookies
- No tracking/linking of your personal IP address\*
- No AMP links
- No URL tracking tags (i.e. utm=%s)
- No referrer header
- Tor and HTTP/SOCKS proxy support
- Autocomplete/search suggestions
- POST request search and suggestion queries (when possible)
- View images at full res without site redirect (currently mobile only)
- Dark mode
- Randomly generated User Agent
- Easy to install/deploy
- DDG-style bang (i.e.
!<tag> <query>) searches - Optional location-based searching (i.e. results near \
) - Optional NoJS mode to disable all Javascript in results
If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.
Dependencies
If using Heroku Quick Deploy, you can skip this section.- Docker (Windows, macOS, Ubuntu, other Linux distros)
- Python3
libcurl4-openssl-devandlibssl-dev
brew install openssl curl-openssl
- Ubuntu: sudo apt-get install -y libcurl4-openssl-dev libssl-dev
- Arch: pacman -S curl opensslInstall
There are a few different ways to begin using the app, depending on your preferences:A) Heroku Quick Deploy
Note: Requires a (free) Heroku account
Provides:
- Free deployment of app
- Free HTTPS url (https://\
.herokuapp.com) - Downtime after periods of inactivity \(solution\)
B) Repl.it
Note: Requires a (free) Replit account
Provides:
- Free deployment of app
- Free HTTPS url (https://\
.\ \.repl\.co)
- Supports custom domains- Downtime after periods of inactivity \(solution 1, solution 2\)
C) Fly.io
You will need a Fly.io account to do this. Fly requires a credit card to deploy anything, but you can have up to 3 shared-CPU VMs running full-time each month for free.Install the CLI:
curl -L https://fly.io/install.sh | shDeploy your app
fly apps create --org personal --port 5000
# Choose a name and the Image builder
# Enter `benbusby/whoogle-search:latest` as the image name
fly deployYour app is now available at
https://<app-name>.fly.dev.You can customize the
fly.toml:- Remove the non-https service
- Add environment variables under the
[env]key
fly secrets set NAME=value for more sensitive values like WHOOGLE_PASS and WHOOGLE_PROXY_PASS.D) pipx
Persistent install:pipx install git+https://github.com/benbusby/whoogle-search.gitSandboxed temporary instance:
pipx run --spec git+https://github.com/benbusby/whoogle-search.git whoogle-searchE) 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.F) Manual
Note:Content-Security-Policy headers are already sent by Whoogle -- you don't/shouldn't need to apply a CSP header yourselfClone 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 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=nitter.net
#Environment=WHOOGLE_ALT_YT=invidious.snopyta.org
#Environment=WHOOGLE_ALT_IG=bibliogram.art/u
#Environment=WHOOGLE_ALT_RD=libredd.it
#Environment=WHOOGLE_ALT_TL=lingva.ml
# Load values from dotenv only
#Environment=WHOOGLE_DOTENV=1
Type=simple
User=root
WorkingDirectory=<whoogle_directory>
ExecStart=<whoogle_directory>/venv/bin/python3 -um app --host 0.0.0.0 --port 5000
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 whoogleG) Manual (Docker)
- Ensure the Docker daemon is running, and is accessible by your user account
sudo usermod -aG docker yourusername
- Running 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).- Clone and deploy the docker app using a method below:
Docker CLI
Note: For ARM machines, use thebuildx-experimental Docker tag.Through Docker Hub:
docker pull benbusby/whoogle-search
docker run --publish 5000:5000 --detach --name whoogle-search benbusby/whoogle-search:latestor with docker-compose:
git clone https://github.com/benbusby/whoogle-search.git
cd whoogle-search
docker-compose upor 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.0Optionally, 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.0And kill with:
docker rm --force whoogle-searchUsing 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 openThis 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.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: - A server (I personally recommend Digital Ocean or Linode, their cheapest tiers will work fine) - Your own URL (I suppose this is optional, but recommended) - SSL certificates (free through Let's Encrypt) - A bit more experience or willingness to work through issues
Environment Variables
There are a few optional environment variables available for customizing a Whoogle instance. These can be set manually, or copied intowhoogle.env and enabled for your preferred deployment method:- Local runs: Set
WHOOGLE_DOTENV=1before running - With
docker-compose: Uncomment theenv_fileoption - With
docker build/run: Add--env-file ./whoogle.envto your command
| Variable | Description |
|---|---|
| WHOOGLEDOTENV | Load environment variables in whoogle.env |
| WHOOGLEUSER | The username for basic auth. WHOOGLEPASS must also be set if used. |
| WHOOGLEPASS | The password for basic auth. WHOOGLEUSER must also be set if used. |
| WHOOGLEPROXYUSER | The username of the proxy server. |
| WHOOGLEPROXYPASS | The password of the proxy server. |
| WHOOGLEPROXYTYPE | The type of the proxy server. Can be "socks5", "socks4", or "http". |
| WHOOGLEPROXYLOC | The location of the proxy server (host or ip). |
| EXPOSEPORT | The port where Whoogle will be exposed. |
| HTTPSONLY | Enforce HTTPS. (See here) |
| WHOOGLEALTTW | The twitter.com alternative to use when site alternatives are enabled in the config. |
| WHOOGLEALTYT | The youtube.com alternative to use when site alternatives are enabled in the config. |
| WHOOGLEALTIG | The instagram.com alternative to use when site alternatives are enabled in the config. |
| WHOOGLEALTRD | The reddit.com alternative to use when site alternatives are enabled in the config. |
| WHOOGLEALTTL | The Google Translate alternative to use. This is used for all "translate " searches. |
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 |
|---|---|
| WHOOGLECONFIGDISABLE | Hide config from UI and disallow changes to config by client |
| WHOOGLECONFIGCOUNTRY | Filter results by hosting country |
| WHOOGLECONFIGLANGUAGE | Set interface language |
| WHOOGLECONFIGSEARCHLANGUAGE | Set search result language |
| WHOOGLECONFIGBLOCK | Block websites from search results (use comma-separated list) |
| WHOOGLECONFIGTHEME | Set theme mode (light, dark, or system) |
| WHOOGLECONFIGSAFE | Enable safe searches |
| WHOOGLECONFIGALTS | Use social media site alternatives (nitter, invidious, etc) |
| WHOOGLECONFIGTOR | Use Tor routing (if available) |
| WHOOGLECONFIGNEWTAB | Always open results in new tab |
| WHOOGLECONFIGVIEWIMAGE | Enable View Image option |
| WHOOGLECONFIGGETONLY | Search using GET requests only |
| WHOOGLECONFIGURL | The root url of the instance (https://<your url>/) |
| WHOOGLECONFIGSTYLE | The custom CSS to use for styling (should be single line) |
Usage
Same as most search engines, with the exception of filtering by time range.To filter by a range of time, append ":past
Serve Whoogle on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.
Proxying whoogle.example.com to http://whoogle:5000
Add this to your Caddyfile
whoogle.example.com {
reverse_proxy http://whoogle:5000
}Check the logs first
Nine times out of ten the logs tell you exactly what went wrong.
- In Portainer, go to Containers, click the container, then Logs. Or run
docker logs whoogle - Exit codes help too:
137means killed, usually out of memory.126or127means the command inside the image is broken.
Port already in use
If deployment fails with "Bind for 0.0.0.0:5001 failed: port is already allocated", something else on your server is using that port.
- Find what's using it:
sudo ss -tlnp | grep :5001 - Stop the other service, or pick a different host port. In
5001:5000only the left number is yours to change, the right one belongs to the app.
Running but the page won't load
The container is up but nothing appears in your browser.
- Use your server's real IP:
http://your-server-ip:5001. The 0.0.0.0 link Portainer shows isn't a real address. - Give it a minute after first deploy, whoogle can take a while to initialise.
- Make sure your firewall allows the port, e.g.
sudo ufw allow 5001
Permission denied on volumes
If the logs show "permission denied", the app can't write to its data folder on the host.
- Fix the ownership:
sudo chown -R 1000:1000 /portainer/Files/AppData/Config/Whoogle
Image won't pull
Test the pull directly on the host: docker pull benbusby/whoogle-search:latest
- "manifest unknown" means the tag no longer exists. This template uses
latest, so try pinning a specific version instead. - "toomanyrequests" is the Docker Hub rate limit. Log in with
docker loginto raise it. - "no space left on device" means a full disk. Reclaim space with
docker system prune
"exec format error"
This means the image was built for a different CPU architecture than your server.
- This image supports:
amd64, arm64, arm/v7 - Check yours with
uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.
Container keeps restarting
The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.
- Check the logs right after a restart, the last few lines before it died are the useful ones.
- Get the exit code with
docker inspect whoogle --format '{{.State.ExitCode}}' - Still stuck? Redeploy once with the restart policy set to
noso the failure stays visible.
Upstream project is archived
The developers have archived benbusby/whoogle-search, so bugs and security issues won't be fixed.
- It'll keep working for now, but consider the similar apps below for a maintained alternative.
Raise an issue
Found something which isn't working as it should? Here's how to report it.
- Bug within the app: Open an issue on benbusby/whoogle-search
- Template not working: Open an issue on novaspirit/pi-hosted
- This website not working: Open an issue on lissy93/portainer-templates
A single container
Whoogle runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.
The app image
An image is the app packed up ready to go, everything Whoogle needs bundled into one download. This template pulls benbusby/whoogle-search:latest, which Docker fetches once (about 55 MB) and then starts your own copy from.
Where the image comes from
Docker pulls its images from registries, public libraries of ready-built apps. Whoogle's comes from Docker Hub, published by benbusby.
Version tags
The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Newest right now is 1.2.4. Pin a specific tag if you would rather stay on one version.
Which machines it runs on
Every image is built for particular CPU types. This one ships for amd64, arm64, arm/v7, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.
Ports
A port is the door the app answers on. A mapping like 5001:5000 means it's reachable on port 5001 of your server, where the left number is yours to change and the right one belongs to the app. It opens:
5001:5000
Volumes
A volume is where Whoogle keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:
/configfrom/portainer/Files/AppData/Config/Whoogleon the host
Restart policy
The restart policy here is unless-stopped, so Docker restarts Whoogle after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).
Networking
Nothing custom is set, so Whoogle sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.
Container name
Once it's deployed, Portainer names the container whoogle. That's what you'll spot in the containers list and use in commands like docker logs whoogle.
Platform
The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.
Open source license
Whoogle is open source, released under the MIT license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.
Portainer app templates
Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Whoogle up. Add the template list to Portainer once, then deploying Whoogle is a click rather than a wall of config.