github.com/benbusby/whoogle-search @v1.2.4 sqlite

[!WARNING]

Final Release Notice 14 Apr 2026 Since early 2025, Google has been aggressively blocking search queries performed without JavaScript enabled by continuously banning working User-Agent strings. This is THE fundamental part of how Whoogle works. All efforts to find and build a method to continue working have failed, and as a result, this will be the final release of Whoogle.

Whoogle can theoretically continue to be used by bringing your own CSE Key (Custom Search Engine Key), or if you are able to find a working UA string, you can hardcode that. However, no additional efforts will be placed into finding a fix or maintaining workarounds unless someone stumbles upon a method that will work reliably and maintains a small, simple footprint.

---

SourceHut

GitHub

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. Features 3. Install/Deploy Options 1. Heroku Quick Deploy 1. Render.com 1. Repl.it 1. Fly.io 1. Koyeb 1. pipx 1. pip 1. Manual 1. Docker 1. Arch/AUR 1. Helm/Kubernetes 4. Environment Variables and Configuration 5. Google Custom Search (BYOK) 6. Usage 7. Extra Steps 1. Set Primary Search Engine 2. Custom Redirecting 2. Custom Bangs 3. Prevent Downtime (Heroku Only) 4. Manual HTTPS Enforcement 5. Using with Firefox Containers 6. Reverse Proxying 1. Nginx 8. Contributing 9. FAQ 10. Public Instances 11. Screenshots

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)
• Light/Dark/System theme modes (with support for custom CSS theming)
• Auto-generated Safari User Agents with random rotation
• 10 unique Safari-based UAs generated on startup from 115 language variants
• Randomly rotated for each search request to avoid detection patterns
• Cached across restarts with configurable refresh options
• Fallback to safe default UA if generation fails
• Optional display of current UA in search results footer
• Easy to install/deploy
• DDG-style bang (i.e. !<tag> <query>) searches
• User-defined custom bangs
• Optional location-based searching (i.e. results near \<city>)
• Optional NoJS mode to view search results in a separate window with JavaScript blocked
• JSON output for results via content negotiation (see "JSON results (API)")

^{*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

Supported Platforms

Official Docker images are built for: - linux/amd64 (x86_64) - linux/arm64 (ARM 64-bit, Raspberry Pi 3/4/5, Apple Silicon)

Note: ARMv7 support (32-bit ARM, Raspberry Pi 2) was dropped in v1.2.0 due to incompatibility with modern security libraries on Alpine Linux. Users with ARMv7 devices can either: - Use an older version (v1.1.x or earlier) - Build locally with pinned dependencies (see notes in Dockerfile) - Upgrade to a 64-bit OS if hardware supports it (Raspberry Pi 3+)

There are a few different ways to begin using the app, depending on your preferences:

---

Heroku Quick Deploy

Provides: - Easy Deployment of App - A HTTPS url (https://\<your app name>.herokuapp.com)

Notes: - Requires a PAID Heroku Account. - Sometimes has issues with auto-redirecting to https. Make sure to navigate to the https version of your app before adding as a default search engine.

---

Render

Create an account on render.com and import the Whoogle repo with the following settings:

• Runtime: Python 3
• Build Command: pip install -r requirements.txt
• Run Command: ./run

---

Repl.it

Note: Requires a (free) Replit account

Provides: - Free deployment of app - Free HTTPS url (https://\<app name>.\<username>.repl.co) - Supports custom domains - Downtime after periods of inactivity (solution)

---

Fly.io

You will need a Fly.io account to deploy Whoogle.

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.

Notes: - Requires a PAID Fly.io Account.

---

Koyeb

Use one of the following guides to install Whoogle on Koyeb:

1. Using GitHub: https://www.koyeb.com/docs/quickstart/deploy-with-git
2. Using Docker: https://www.koyeb.com/docs/quickstart/deploy-a-docker-application

---

RepoCloud

1. Sign up for a free RepoCloud account and receive free credits to get started.
2. Click "Deploy" to launch the app and access it instantly via your RepoCloud URL.

---

pipx

Persistent install:

pipx install https://github.com/benbusby/whoogle-search/archive/refs/heads/main.zip

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

• Python3
• libcurl4-openssl-dev and libssl-dev
• macOS: brew install openssl curl-openssl
• Ubuntu: sudo apt-get install -y libcurl4-openssl-dev libssl-dev
• Arch: pacman -S curl openssl

Install

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
#Environment=WHOOGLE_ALT_SO=farside.link/anonymousoverflow
# Load values from dotenv only
#Environment=WHOOGLE_DOTENV=1
# specify dotenv location if not in default location
#Environment=WHOOGLE_DOTENV_PATH=<path/to>/whoogle.env
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 1. Uncomment or add the following lines in your torrc: - ControlPort 9051 - CookieAuthentication 1 - DataDirectoryGroupReadable 1 - CookieAuthFileGroupReadable 1

2. Make the tor auth cookie readable:
   - This is assuming that you are using a dedicated user to run whoogle. If you are using a different user replace `whoogle` with that user.

   1. `chmod tor:whoogle /var/lib/tor`
   2. `chmod tor:whoogle /var/lib/tor/control_auth_cookie`

3. Restart the tor service:
   - `systemctl restart tor`

4. Set the Tor environment variable to 1, `WHOOGLE_CONFIG_TOR`. Refer to the [Environment Variables](#environment-variables) section for more details.
   - This may be added in the systemd unit file or env file `WHOOGLE_CONFIG_TOR=1`

• Password

  1. Run this command:
  2. tor --hash-password {Your Password Here}; put your password in place of {Your Password Here}.
  3. Keep the output of this command, you will be placing it in your torrc.

  4. Keep the password input of this command, you will be using it later.

  5. Uncomment or add the following lines in