[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-9982":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":18,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":16,"starSnapshotCount":16,"syncStatus":40,"lastSyncTime":41,"discoverSource":42},9982,"whoogle-search","benbusby\u002Fwhoogle-search","benbusby","A self-hosted, ad-free, privacy-respecting metasearch engine","https:\u002F\u002Fpypi.org\u002Fproject\u002Fwhoogle-search\u002F",null,"Python",11548,1040,102,1,0,3,12,46,85.65,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34,35,36],"adblock","docker","easy-deploy","flask","heroku","metasearch","metasearch-engine","privacy","python","search","search-engine","2026-06-12 04:00:47",">[!WARNING]\n>\n>**Final Release Notice 14 Apr 2026**\n>Since early 2025, Google has been aggressively blocking search queries performed without JavaScript enabled by continuously banning working User-Agent strings.\n>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**.\n>\n>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.\n\n___\n\n![Whoogle Search](docs\u002Fbanner.png)\n\n[![Latest Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fbenbusby\u002Fwhoogle-search)](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fshoogle\u002Freleases)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![tests](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Factions\u002Fworkflows\u002Ftests.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Factions\u002Fworkflows\u002Ftests.yml)\n[![buildx](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Factions\u002Fworkflows\u002Fbuildx.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Factions\u002Fworkflows\u002Fbuildx.yml)\n[![Docker Pulls](https:\u002F\u002Fimg.shields.io\u002Fdocker\u002Fpulls\u002Fbenbusby\u002Fwhoogle-search)](https:\u002F\u002Fhub.docker.com\u002Fr\u002Fbenbusby\u002Fwhoogle-search)\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd>\u003Ca href=\"https:\u002F\u002Fsr.ht\u002F~benbusby\u002Fwhoogle-search\">SourceHut\u003C\u002Fa>\u003C\u002Ftd>\n    \u003Ctd>\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\">GitHub\u003C\u002Fa>\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\nGet 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.\n\nContents\n1. [Features](#features)\n3. [Install\u002FDeploy Options](#install)\n    1. [Heroku Quick Deploy](#heroku-quick-deploy)\n    1. [Render.com](#render)\n    1. [Repl.it](#replit)\n    1. [Fly.io](#flyio)\n    1. [Koyeb](#koyeb)\n    1. [pipx](#pipx)\n    1. [pip](#pip)\n    1. [Manual](#manual)\n    1. [Docker](#manual-docker)\n    1. [Arch\u002FAUR](#arch-linux--arch-based-distributions)\n    1. [Helm\u002FKubernetes](#helm-chart-for-kubernetes)\n4. [Environment Variables and Configuration](#environment-variables)\n5. [Google Custom Search (BYOK)](#google-custom-search-byok)\n6. [Usage](#usage)\n7. [Extra Steps](#extra-steps)\n    1. [Set Primary Search Engine](#set-whoogle-as-your-primary-search-engine)\n\t2. [Custom Redirecting](#custom-redirecting)\n\t2. [Custom Bangs](#custom-bangs)\n    3. [Prevent Downtime (Heroku Only)](#prevent-downtime-heroku-only)\n    4. [Manual HTTPS Enforcement](#https-enforcement)\n    5. [Using with Firefox Containers](#using-with-firefox-containers)\n    6. [Reverse Proxying](#reverse-proxying)\n        1. [Nginx](#nginx)\n8. [Contributing](#contributing)\n9. [FAQ](#faq)\n10. [Public Instances](#public-instances)\n11. [Screenshots](#screenshots)\n\n## Features\n- No ads or sponsored content\n- No JavaScript\\*\n- No cookies\\*\\*\n- No tracking\u002Flinking of your personal IP address\\*\\*\\*\n- No AMP links\n- No URL tracking tags (i.e. utm=%s)\n- No referrer header\n- Tor and HTTP\u002FSOCKS proxy support\n- Autocomplete\u002Fsearch suggestions\n- POST request search and suggestion queries (when possible)\n- View images at full res without site redirect (currently mobile only)\n- Light\u002FDark\u002FSystem theme modes (with support for [custom CSS theming](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fwiki\u002FUser-Contributed-CSS-Themes))\n- Auto-generated Safari User Agents with random rotation\n  - 10 unique Safari-based UAs generated on startup from 115 language variants\n  - Randomly rotated for each search request to avoid detection patterns\n  - Cached across restarts with configurable refresh options\n  - Fallback to safe default UA if generation fails\n  - Optional display of current UA in search results footer\n- Easy to install\u002Fdeploy\n- DDG-style bang (i.e. `!\u003Ctag> \u003Cquery>`) searches\n- User-defined [custom bangs](#custom-bangs)\n- Optional location-based searching (i.e. results near \\\u003Ccity\\>)\n- Optional NoJS mode to view search results in a separate window with JavaScript blocked\n- JSON output for results via content negotiation (see \"JSON results (API)\")\n\n\u003Csup>*No third party JavaScript. Whoogle can be used with JavaScript disabled, but if enabled, uses JavaScript for things like presenting search suggestions.\u003C\u002Fsup>\n\n\u003Csup>**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.\u003C\u002Fsup>\n\n\u003Csup>***If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.\u003C\u002Fsup>\n\n## Install\n\n### Supported Platforms\nOfficial Docker images are built for:\n- **linux\u002Famd64** (x86_64)\n- **linux\u002Farm64** (ARM 64-bit, Raspberry Pi 3\u002F4\u002F5, Apple Silicon)\n\n**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:\n- Use an older version (v1.1.x or earlier)\n- Build locally with pinned dependencies (see notes in Dockerfile)\n- Upgrade to a 64-bit OS if hardware supports it (Raspberry Pi 3+)\n\nThere are a few different ways to begin using the app, depending on your preferences:\n\n___\n\n### [Heroku Quick Deploy](https:\u002F\u002Fheroku.com\u002Fabout)\n[![Deploy](https:\u002F\u002Fwww.herokucdn.com\u002Fdeploy\u002Fbutton.svg)](https:\u002F\u002Fheroku.com\u002Fdeploy?template=https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Ftree\u002Fmain)\n\nProvides:\n- Easy Deployment of App\n- A HTTPS url (https:\u002F\u002F\\\u003Cyour app name\\>.herokuapp.com)\n\nNotes:\n- Requires a **PAID** Heroku Account.\n- 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.\n\n___\n\n### [Render](https:\u002F\u002Frender.com)\n\nCreate an account on [render.com](https:\u002F\u002Frender.com) and import the Whoogle repo with the following settings:\n\n- Runtime: `Python 3`\n- Build Command: `pip install -r requirements.txt`\n- Run Command: `.\u002Frun`\n\n___\n\n### [Repl.it](https:\u002F\u002Frepl.it)\n[![Run on Repl.it](https:\u002F\u002Frepl.it\u002Fbadge\u002Fgithub\u002Fbenbusby\u002Fwhoogle-search)](https:\u002F\u002Frepl.it\u002Fgithub\u002Fbenbusby\u002Fwhoogle-search)\n\n*Note: Requires a (free) Replit account*\n\nProvides:\n- Free deployment of app\n- Free HTTPS url (https:\u002F\u002F\\\u003Capp name\\>.\\\u003Cusername\\>\\.repl\\.co)\n    - Supports custom domains\n- Downtime after periods of inactivity ([solution](https:\u002F\u002Frepl.it\u002Ftalk\u002Flearn\u002FHow-to-use-and-setup-UptimeRobot\u002F9003)\\)\n\n___\n\n### [Fly.io](https:\u002F\u002Ffly.io)\n\nYou will need a [Fly.io](https:\u002F\u002Ffly.io) account to deploy Whoogle.\n\n#### Install the CLI: https:\u002F\u002Ffly.io\u002Fdocs\u002Fhands-on\u002Finstalling\u002F\n\n#### Deploy the app\n\n```bash\nflyctl auth login\nflyctl launch --image benbusby\u002Fwhoogle-search:latest\n```\n\nThe first deploy won't succeed because the default `internal_port` is wrong.\nTo fix this, open the generated `fly.toml` file, set `services.internal_port` to `5000` and run `flyctl launch` again.\n\nYour app is now available at `https:\u002F\u002F\u003Capp-name>.fly.dev`.\n\nNotes:\n- Requires a [**PAID**](https:\u002F\u002Ffly.io\u002Fdocs\u002Fabout\u002Fpricing\u002F#free-allowances) Fly.io Account.\n\n___\n\n### [Koyeb](https:\u002F\u002Fwww.koyeb.com)\n\nUse one of the following guides to install Whoogle on Koyeb:\n\n1. Using GitHub: https:\u002F\u002Fwww.koyeb.com\u002Fdocs\u002Fquickstart\u002Fdeploy-with-git\n2. Using Docker: https:\u002F\u002Fwww.koyeb.com\u002Fdocs\u002Fquickstart\u002Fdeploy-a-docker-application\n\n___\n\n### [RepoCloud](https:\u002F\u002Frepocloud.io)\n[![Deploy on RepoCloud](https:\u002F\u002Fd16t0pc4846x52.cloudfront.net\u002Fdeploylobe.svg)](https:\u002F\u002Frepocloud.io\u002Fdetails\u002F?app_id=309)\n\n1. Sign up for a free [RepoCloud account](https:\u002F\u002Frepocloud.io) and receive free credits to get started.\n2. Click \"Deploy\" to launch the app and access it instantly via your RepoCloud URL.\n___\n\n### [pipx](https:\u002F\u002Fgithub.com\u002Fpipxproject\u002Fpipx#install-pipx)\nPersistent install:\n\n`pipx install https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Farchive\u002Frefs\u002Fheads\u002Fmain.zip`\n\nSandboxed temporary instance:\n\n`pipx run --spec git+https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search.git whoogle-search`\n\n___\n\n### pip\n`pip install whoogle-search`\n\n```bash\n$ whoogle-search --help\nusage: whoogle-search [-h] [--port \u003Cport number>] [--host \u003Cip address>] [--debug] [--https-only] [--userpass \u003Cusername:password>]\n                      [--proxyauth \u003Cusername:password>] [--proxytype \u003Csocks4|socks5|http>] [--proxyloc \u003Clocation:port>]\n\nWhoogle Search console runner\n\noptional arguments:\n  -h, --help            Show this help message and exit\n  --port \u003Cport number>  Specifies a port to run on (default 5000)\n  --host \u003Cip address>   Specifies the host address to use (default 127.0.0.1)\n  --debug               Activates debug mode for the server (default False)\n  --https-only          Enforces HTTPS redirects for all requests\n  --userpass \u003Cusername:password>\n                        Sets a username\u002Fpassword basic auth combo (default None)\n  --proxyauth \u003Cusername:password>\n                        Sets a username\u002Fpassword for a HTTP\u002FSOCKS proxy (default None)\n  --proxytype \u003Csocks4|socks5|http>\n                        Sets a proxy type for all connections (default None)\n  --proxyloc \u003Clocation:port>\n                        Sets a proxy location for all connections (default None)\n```\nSee the [available environment variables](#environment-variables) for additional configuration.\n\n___\n\n### Manual\n\n*Note: `Content-Security-Policy` headers can be sent by Whoogle if you set `WHOOGLE_CSP`.*\n\n#### Dependencies\n- [Python3](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n- `libcurl4-openssl-dev` and `libssl-dev`\n  - macOS: `brew install openssl curl-openssl`\n  - Ubuntu: `sudo apt-get install -y libcurl4-openssl-dev libssl-dev`\n  - Arch: `pacman -S curl openssl`\n\n#### Install\n\nClone the repo and run the following commands to start the app in a local-only environment:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search.git\ncd whoogle-search\npython3 -m venv venv\nsource venv\u002Fbin\u002Factivate\npip install -r requirements.txt\n.\u002Frun\n```\nSee the [available environment variables](#environment-variables) for additional configuration.\n\n#### systemd Configuration\nAfter building the virtual environment, you can add something like the following to `\u002Flib\u002Fsystemd\u002Fsystem\u002Fwhoogle.service` to set up a Whoogle Search systemd service:\n\n```ini\n[Unit]\nDescription=Whoogle\n\n[Service]\n# Basic auth configuration, uncomment to enable\n#Environment=WHOOGLE_USER=\u003Cusername>\n#Environment=WHOOGLE_PASS=\u003Cpassword>\n# Proxy configuration, uncomment to enable\n#Environment=WHOOGLE_PROXY_USER=\u003Cproxy username>\n#Environment=WHOOGLE_PROXY_PASS=\u003Cproxy password>\n#Environment=WHOOGLE_PROXY_TYPE=\u003Cproxy type (http|https|proxy4|proxy5)\n#Environment=WHOOGLE_PROXY_LOC=\u003Cproxy host\u002Fip>\n# Site alternative configurations, uncomment to enable\n# Note: If not set, the feature will still be available\n# with default values.\n#Environment=WHOOGLE_ALT_TW=farside.link\u002Fnitter\n#Environment=WHOOGLE_ALT_YT=farside.link\u002Finvidious\n#Environment=WHOOGLE_ALT_RD=farside.link\u002Flibreddit\n#Environment=WHOOGLE_ALT_MD=farside.link\u002Fscribe\n#Environment=WHOOGLE_ALT_TL=farside.link\u002Flingva\n#Environment=WHOOGLE_ALT_IMG=farside.link\u002Frimgo\n#Environment=WHOOGLE_ALT_WIKI=farside.link\u002Fwikiless\n#Environment=WHOOGLE_ALT_IMDB=farside.link\u002Flibremdb\n#Environment=WHOOGLE_ALT_QUORA=farside.link\u002Fquetre\n#Environment=WHOOGLE_ALT_SO=farside.link\u002Fanonymousoverflow\n# Load values from dotenv only\n#Environment=WHOOGLE_DOTENV=1\n# specify dotenv location if not in default location\n#Environment=WHOOGLE_DOTENV_PATH=\u003Cpath\u002Fto>\u002Fwhoogle.env\nType=simple\nUser=\u003Cusername>\n# If installed as a package, add:\nExecStart=\u003Cpython_install_dir>\u002Fpython3 \u003Cwhoogle_install_dir>\u002Fwhoogle-search --host 127.0.0.1 --port 5000\n# For example:\n# ExecStart=\u002Fusr\u002Fbin\u002Fpython3 \u002Fhome\u002Fmy_username\u002F.local\u002Fbin\u002Fwhoogle-search --host 127.0.0.1 --port 5000\n# Otherwise if running the app from source, add:\nExecStart=\u003Cwhoogle_repo_dir>\u002Frun\n# For example:\n# ExecStart=\u002Fvar\u002Fwww\u002Fwhoogle-search\u002Frun\nWorkingDirectory=\u003Cwhoogle_repo_dir>\nExecReload=\u002Fbin\u002Fkill -HUP $MAINPID\nRestart=always\nRestartSec=3\nSyslogIdentifier=whoogle\n\n[Install]\nWantedBy=multi-user.target\n```\nThen,\n```\nsudo systemctl daemon-reload\nsudo systemctl enable whoogle\nsudo systemctl start whoogle\n```\n\n#### Tor Configuration *optional*\nIf routing your request through Tor you will need to make the following adjustments.\nDue 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.\n\nThere are two authentication methods, password and cookie. You will need to make changes to your torrc:\n  * Cookie\n    1. Uncomment or add the following lines in your torrc:\n       - `ControlPort 9051`\n       - `CookieAuthentication 1`\n       - `DataDirectoryGroupReadable 1`\n       - `CookieAuthFileGroupReadable 1`\n\n    2. Make the tor auth cookie readable:\n       - 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.\n\n       1. `chmod tor:whoogle \u002Fvar\u002Flib\u002Ftor`\n       2. `chmod tor:whoogle \u002Fvar\u002Flib\u002Ftor\u002Fcontrol_auth_cookie`\n\n    3. Restart the tor service:\n       - `systemctl restart tor`\n\n    4. Set the Tor environment variable to 1, `WHOOGLE_CONFIG_TOR`. Refer to the [Environment Variables](#environment-variables) section for more details.\n       - This may be added in the systemd unit file or env file `WHOOGLE_CONFIG_TOR=1`\n\n  * Password\n    1. Run this command:\n       - `tor --hash-password {Your Password Here}`; put your password in place of `{Your Password Here}`.\n       - Keep the output of this command, you will be placing it in your torrc.\n       - Keep the password input of this command, you will be using it later.\n\n    2. Uncomment or add the following lines in your torrc:\n       - `ControlPort 9051`\n       - `HashedControlPassword {Place output here}`; put the output of the previous command in place of `{Place output here}`.\n\n    3. Now take the password from the first step and place it in the control.conf file within the whoogle working directory, ie. [misc\u002Ftor\u002Fcontrol.conf](misc\u002Ftor\u002Fcontrol.conf)\n       - If you want to place your password file in a different location set this location with the `WHOOGLE_TOR_CONF` environment variable. Refer to the [Environment Variables](#environment-variables) section for more details.\n\n    4. Heavily restrict access to control.conf to only be readable by the user running whoogle:\n       - `chmod 400 control.conf`\n\n    5. 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](#environment-variables) section for more details.\n       - These may be added to the systemd unit file or env file:\n          - `WHOOGLE_CONFIG_TOR=1`\n          - `WHOOGLE_TOR_USE_PASS=1`\n\n___\n\n### Manual (Docker)\n1. Ensure the Docker daemon is running, and is accessible by your user account\n  - To add user permissions, you can execute `sudo usermod -aG docker yourusername`\n  - 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\u002FmacOS).\n2. Clone and deploy the docker app using a method below:\n\n#### Docker CLI\n\nThrough Docker Hub:\n```bash\ndocker pull benbusby\u002Fwhoogle-search\ndocker run --publish 5000:5000 --detach --name whoogle-search benbusby\u002Fwhoogle-search:latest\n```\n\nor with docker-compose:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search.git\ncd whoogle-search\ndocker-compose up\n```\n\nor by building yourself:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search.git\ncd whoogle-search\ndocker build --tag whoogle-search:1.0 .\ndocker run --publish 5000:5000 --detach --name whoogle-search whoogle-search:1.0\n```\n\nOptionally, you can also enable some of the following environment variables to further customize your instance:\n\n```bash\ndocker run --publish 5000:5000 --detach --name whoogle-search \\\n  -e WHOOGLE_USER=username \\\n  -e WHOOGLE_PASS=password \\\n  -e WHOOGLE_PROXY_USER=username \\\n  -e WHOOGLE_PROXY_PASS=password \\\n  -e WHOOGLE_PROXY_TYPE=socks5 \\\n  -e WHOOGLE_PROXY_LOC=ip \\\n  whoogle-search:1.0\n```\n\nAnd kill with: `docker rm --force whoogle-search`\n\n#### Using [Heroku CLI](https:\u002F\u002Fdevcenter.heroku.com\u002Farticles\u002Fheroku-cli)\n```bash\nheroku login\nheroku container:login\ngit clone https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search.git\ncd whoogle-search\nheroku create\nheroku container:push web\nheroku container:release web\nheroku open\n```\n\nThis 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](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search#set-whoogle-as-your-primary-search-engine).\nYou may also edit environment variables from your app’s Settings tab in the Heroku Dashboard.\n\n___\n\n### Arch Linux & Arch-based Distributions\nThere is an [AUR package available](https:\u002F\u002Faur.archlinux.org\u002Fpackages\u002Fwhoogle-git\u002F), as well as a pre-built and daily updated package available at [Chaotic-AUR](https:\u002F\u002Fchaotic.cx).\n\n___\n\n### Helm chart for Kubernetes\nTo use the Kubernetes Helm Chart:\n1. Ensure you have [Helm](https:\u002F\u002Fhelm.sh\u002Fdocs\u002Fintro\u002Finstall\u002F) `>=3.0.0` installed\n2. Clone this repository\n3. Update [charts\u002Fwhoogle\u002Fvalues.yaml](.\u002Fcharts\u002Fwhoogle\u002Fvalues.yaml) as desired\n4. Run `helm upgrade --install whoogle .\u002Fcharts\u002Fwhoogle`\n\n___\n\n#### Using your own server, or alternative container deployment\nThere are other methods for deploying docker containers that are well outlined in [this article](https:\u002F\u002Frollout.io\u002Fblog\u002Fthe-shortlist-of-docker-hosting\u002F), 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.\n\nDepending on your preferences, you can also deploy the app yourself on your own infrastructure. This route would require a few extra steps:\n  - A server (I personally recommend [Digital Ocean](https:\u002F\u002Fwww.digitalocean.com\u002Fpricing\u002F) or [Linode](https:\u002F\u002Fwww.linode.com\u002Fpricing\u002F), their cheapest tiers will work fine)\n  - Your own URL (I suppose this is optional, but recommended)\n  - SSL certificates (free through [Let's Encrypt](https:\u002F\u002Fletsencrypt.org\u002Fgetting-started\u002F))\n  - A bit more experience or willingness to work through issues\n\n## Environment Variables\nThere 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:\n\n- Local runs: Set `WHOOGLE_DOTENV=1` before running\n- With `docker-compose`: Uncomment the `env_file` option\n- With `docker build\u002Frun`: Add `--env-file .\u002Fwhoogle.env` to your command\n\n| Variable             | Description                                                                               |\n| -------------------- | ----------------------------------------------------------------------------------------- |\n| WHOOGLE_URL_PREFIX   | The URL prefix to use for the whoogle instance (i.e. \"\u002Fwhoogle\")                          |\n| WHOOGLE_DOTENV       | Load environment variables in `whoogle.env`                                               |\n| WHOOGLE_DOTENV_PATH  | The path to `whoogle.env` if not in default location                                      |\n| WHOOGLE_USER         | The username for basic auth. WHOOGLE_PASS must also be set if used.                       |\n| WHOOGLE_PASS         | The password for basic auth. WHOOGLE_USER must also be set if used.                       |\n| WHOOGLE_PROXY_USER   | The username of the proxy server.                                                         |\n| WHOOGLE_PROXY_PASS   | The password of the proxy server.                                                         |\n| WHOOGLE_PROXY_TYPE   | The type of the proxy server. Can be \"socks5\", \"socks4\", or \"http\".                       |\n| WHOOGLE_PROXY_LOC    | The location of the proxy server (host or ip).                                            |\n| WHOOGLE_USER_AGENT   | The desktop user agent to use when using 'env_conf' option. Leave empty to use auto-generated Safari UAs. |\n| WHOOGLE_USER_AGENT_MOBILE | The mobile user agent to use when using 'env_conf' option. Leave empty to use auto-generated Safari UAs. |\n| WHOOGLE_USE_CLIENT_USER_AGENT | Enable to use your own user agent for all requests. Defaults to false.           |\n| WHOOGLE_UA_CACHE_PERSISTENT | Whether to persist auto-generated UAs across restarts. Set to '0' to regenerate on each startup. Default '1'. |\n| WHOOGLE_UA_CACHE_REFRESH_DAYS | Auto-refresh UA cache after N days. Set to '0' to never refresh (cache persists indefinitely). Default '0'. |\n| WHOOGLE_UA_LIST_FILE | Path to text file containing custom UA strings (one per line). When set, uses these instead of auto-generated UAs. |\n| WHOOGLE_REDIRECTS    | Specify sites that should be redirected elsewhere. See [custom redirecting](#custom-redirecting). |\n| EXPOSE_PORT          | The port where Whoogle will be exposed.                                                   |\n| HTTPS_ONLY           | Enforce HTTPS. (See [here](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search#https-enforcement)) |\n| WHOOGLE_ALT_TW       | The twitter.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_YT       | The youtube.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_RD       | The reddit.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_TL       | The Google Translate alternative to use. This is used for all \"translate ____\" searches.  Set to \"\" to disable. |\n| WHOOGLE_ALT_MD       | The medium.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_IMG      | The imgur.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_WIKI     | The wikipedia.org alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_IMDB     | The imdb.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable.  |\n| WHOOGLE_ALT_QUORA    | The quora.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_ALT_SO       | The stackoverflow.com alternative to use when site alternatives are enabled in the config. Set to \"\" to disable. |\n| WHOOGLE_AUTOCOMPLETE | Controls visibility of autocomplete\u002Fsearch suggestions. Default on -- use '0' to disable. |\n| WHOOGLE_MINIMAL      | Remove everything except basic result cards from all search queries.                      |\n| WHOOGLE_CSP          | Sets a default set of 'Content-Security-Policy' headers                                   |\n| WHOOGLE_TOR_SERVICE  | Enable\u002Fdisable the Tor service on startup. Default on -- use '0' to disable.              |\n| WHOOGLE_TOR_USE_PASS | Use password authentication for tor control port. |\n| WHOOGLE_TOR_CONF | The absolute path to the config file containing the password for the tor control port. Default: .\u002Fmisc\u002Ftor\u002Fcontrol.conf WHOOGLE_TOR_PASS must be 1 for this to work.|\n| WHOOGLE_SHOW_FAVICONS | Show\u002Fhide favicons next to search result URLs. Default on.                               |\n| WHOOGLE_UPDATE_CHECK  | Enable\u002Fdisable the automatic daily check for new versions of Whoogle. Default on.        |\n| WHOOGLE_FALLBACK_ENGINE_URL | Set a fallback Search Engine URL when there is internal server error or instance is rate-limited. Search query is appended to the end of the URL (eg. https:\u002F\u002Fduckduckgo.com\u002F?k1=-1&q=). |\n| WHOOGLE_BUNDLE_STATIC | When set to 1, serve a single bundled CSS and JS file generated at startup to reduce requests. Default off. |\n| WHOOGLE_HTTP2         | Enable HTTP\u002F2 for upstream requests (via httpx). Default on — set to 0 to force HTTP\u002F1.1. |\n\n### Config Environment Variables\nThese 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\u002Frebuilding an instance to the same config state every time.\n\n| Variable                             | Description                                                     |\n| ------------------------------------ | --------------------------------------------------------------- |\n| WHOOGLE_CONFIG_DISABLE               | Hide config from UI and disallow changes to config by client    |\n| WHOOGLE_CONFIG_COUNTRY               | Filter results by hosting country                               |\n| WHOOGLE_CONFIG_LANGUAGE              | Set interface language                                          |\n| WHOOGLE_CONFIG_SEARCH_LANGUAGE       | Set search result language                                      |\n| WHOOGLE_CONFIG_BLOCK                 | Block websites from search results (use comma-separated list)   |\n| WHOOGLE_CONFIG_BLOCK_TITLE           | Block search result with a REGEX filter on title                |\n| WHOOGLE_CONFIG_BLOCK_URL             | Block search result with a REGEX filter on URL                  |\n| WHOOGLE_CONFIG_THEME                 | Set theme mode (light, dark, or system)                         |\n| WHOOGLE_CONFIG_SAFE                  | Enable safe searches                                            |\n| WHOOGLE_CONFIG_ALTS                  | Use social media site alternatives (nitter, invidious, etc)     |\n| WHOOGLE_CONFIG_NEAR                  | Restrict results to only those near a particular city           |\n| WHOOGLE_CONFIG_TOR                   | Use Tor routing (if available)                                  |\n| WHOOGLE_CONFIG_NEW_TAB               | Always open results in new tab                                  |\n| WHOOGLE_CONFIG_VIEW_IMAGE            | Enable View Image option                                        |\n| WHOOGLE_CONFIG_GET_ONLY              | Search using GET requests only                                  |\n| WHOOGLE_CONFIG_URL                   | The root url of the instance (`https:\u002F\u002F\u003Cyour url>\u002F`)            |\n| WHOOGLE_CONFIG_STYLE                 | The custom CSS to use for styling (should be single line)       |\n| WHOOGLE_CONFIG_PREFERENCES_ENCRYPTED | Encrypt preferences token, requires preferences key             |\n| WHOOGLE_CONFIG_PREFERENCES_KEY       | Key to encrypt preferences in URL (REQUIRED to show url)        |\n| WHOOGLE_CONFIG_ANON_VIEW             | Include the \"anonymous view\" option for each search result      |\n| WHOOGLE_CONFIG_SHOW_USER_AGENT       | Display the User Agent string used for search in results footer |\n\n### Google Custom Search (BYOK) Environment Variables\n\nThese environment variables configure the \"Bring Your Own Key\" feature for Google Custom Search API:\n\n| Variable             | Description                                                                               |\n| -------------------- | ----------------------------------------------------------------------------------------- |\n| WHOOGLE_CSE_API_KEY  | Your Google API key with Custom Search API enabled                                        |\n| WHOOGLE_CSE_ID       | Your Custom Search Engine ID (cx parameter)                                               |\n| WHOOGLE_USE_CSE      | Enable Custom Search API by default (set to '1' to enable)                                |\n\n## Google Custom Search (BYOK)\n\nIf Google blocks traditional search scraping (captchas, IP bans), you can use your own Google Custom Search Engine credentials as a fallback. This uses Google's official API with your own quota.\n\n### Why Use This?\n\n- **Reliability**: Official API never gets blocked or rate-limited (within quota)\n- **Speed**: Direct JSON responses are faster than HTML scraping\n- **Fallback**: Works when all scraping workarounds fail\n- **Privacy**: Your searches still don't go through third parties—they go directly to Google with your own API key\n\n### Limitations vs Standard Whoogle\n\n| Feature          | Standard Scraping        | CSE API             |\n|------------------|--------------------------|---------------------|\n| Daily limit      | None (until blocked)     | 100 free, then paid |\n| Image search     | ✅ Full support          | ✅ Supported         |\n| News\u002FVideos tabs | ✅                       | ❌ Web results only  |\n| Speed            | Slower (HTML parsing)    | Faster (JSON)       |\n| Reliability      | Can be blocked           | Always works        |\n\n### Setup Steps\n\n#### 1. Create a Custom Search Engine\n1. Go to [Programmable Search Engine](https:\u002F\u002Fprogrammablesearchengine.google.com\u002Fcontrolpanel\u002Fall)\n2. Click **\"Add\"** to create a new search engine\n3. Under \"What to search?\", select **\"Search the entire web\"**\n4. Give it a name (e.g., \"My Whoogle CSE\")\n5. Click **\"Create\"**\n6. Copy your **Search Engine ID** \n\n#### 2. Get an API Key\n1. Go to [Google Cloud Console](https:\u002F\u002Fconsole.cloud.google.com\u002F)\n2. Create a new project or select an existing one\n3. Go to **APIs & Services** → **Library**\n4. Search for **\"Custom Search API\"** and click **Enable**\n5. Go to **APIs & Services** → **Credentials**\n6. Click **\"Create Credentials\"** → **\"API Key\"**\n7. Copy your API key (looks like `AIza...`)\n\n#### 3. (Recommended) Restrict Your API Key\nTo prevent misuse if your key is exposed:\n1. Click on your API key in Credentials\n2. Under **\"API restrictions\"**, select **\"Restrict key\"**\n3. Choose only **\"Custom Search API\"**\n4. Under **\"Application restrictions\"**, consider adding IP restrictions if using on a server\n5. Click **Save**\n\n#### 4. Configure Whoogle\n\n**Option A: Via Settings UI**\n1. Open your Whoogle instance\n2. Click the **Config** button\n3. Scroll to \"Google Custom Search (BYOK)\" section\n4. Enter your API Key and CSE ID\n5. Check \"Use Custom Search API\"\n6. Click **Apply**\n\n**Option B: Via Environment Variables**\n```bash\nWHOOGLE_CSE_API_KEY=AIza...\nWHOOGLE_CSE_ID=23f...\nWHOOGLE_USE_CSE=1\n```\n\n### Pricing & Avoiding Charges\n\n| Tier | Queries          | Cost                  |\n|------|------------------|-----------------------|\n| Free | 100\u002Fday          | $0                    |\n| Paid | Up to 10,000\u002Fday | $5 per 1,000 queries  |\n\n**⚠️ To avoid unexpected charges:**\n\n1. **Don't add a payment method** to Google Cloud (safest option—API stops at 100\u002Fday)\n2. **Set a billing budget alert**: [Billing → Budgets & Alerts](https:\u002F\u002Fconsole.cloud.google.com\u002Fbilling\u002Fbudgets)\n3. **Cap API usage**: APIs & Services → Custom Search API → Quotas → Set \"Queries per day\" to 100\n4. **Monitor usage**: APIs & Services → Custom Search API → Metrics\n\n### Troubleshooting\n\n| Error               | Cause                     | Solution                                                        |\n|---------------------|---------------------------|-----------------------------------------------------------------|\n| \"API key not valid\" | Invalid or restricted key | Check key in Cloud Console, ensure Custom Search API is enabled |\n| \"Quota exceeded\"    | Hit 100\u002Fday limit         | Wait until midnight PT, or enable billing                       |\n| \"Invalid CSE ID\"    | Wrong cx parameter        | Copy ID from Programmable Search Engine control panel           |\n\n## Usage\nSame as most search engines, with the exception of filtering by time range.\n\nTo filter by a range of time, append \":past \u003Ctime>\" to the end of your search, where \u003Ctime> can be `hour`, `day`, `month`, or `year`. Example: `coronavirus updates :past hour`\n\n### JSON results (API)\nWhoogle can return filtered results as JSON using the same sanitization rules as the HTML view.\n\n- Send `Accept: application\u002Fjson` or append `format=json` to the search URL.\n- Example: `\u002Fsearch?q=whoogle` with `Accept: application\u002Fjson`, or `\u002Fsearch?q=whoogle&format=json`.\n- Response shape:\n\n```\n{\n  \"query\": \"whoogle\",\n  \"search_type\": \"\",\n  \"results\": [\n    {\"href\": \"https:\u002F\u002Fexample.com\u002Fpage\", \"text\": \"Example Page\"},\n    ...\n  ]\n}\n```\n\nSpecial cases:\n- Feeling Lucky returns HTTP 303 with body `{ \"redirect\": \"\u003Curl>\" }`.\n- Temporary blocks (captcha) return HTTP 503 with `{ \"blocked\": true, \"error_message\": \"...\", \"query\": \"...\" }`.\n\n## Extra Steps\n\n### Set Whoogle as your primary search engine\n*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.*\n\nBrowser settings:\n  - Firefox (Desktop)\n    - Version 89+\n      - Navigate to your app's url, right click the address bar, and select \"Add Search Engine\".\n    - Previous versions\n      - Navigate to your app's url, and click the 3 dot menu in the address bar. At the bottom, there should be an option to \"Add Search Engine\".\n    - Once you've added the new search engine, open your Firefox Preferences menu, click \"Search\" in the left menu, and use the available dropdown to select \"Whoogle\" from the list.\n    - **Note**: If your Whoogle instance uses Firefox Containers, you'll need to [go through the steps here](#using-with-firefox-containers) to get it working properly.\n  - Firefox (iOS)\n    - In the mobile app Settings page, tap \"Search\" within the \"General\" section. There should be an option titled \"Add Search Engine\" to select. It should prompt you to enter a title and search query url - use the following elements to fill out the form:\n      - Title: \"Whoogle\"\n      - URL: `http[s]:\u002F\u002F\\\u003Cyour whoogle url\\>\u002Fsearch?q=%s`\n  - Firefox (Android)\n    - Version \u003C79.0.0\n      - Navigate to your app's url\n      - Long-press on the search text field\n      - Click the \"Add Search Engine\" menu item\n        - Select a name and click ok\n      - Click the 3 dot menu in the top right\n      - Navigate to the settings menu and select the \"Search\" sub-menu\n      - Select Whoogle and press \"Set as default\"\n    - Version >=79.0.0\n      - Click the 3 dot menu in the top right\n      - Navigate to the settings menu and select the \"Search\" sub-menu\n      - Click \"Add search engine\"\n      - Select the 'Other' radio button\n        - Name: \"Whoogle\"\n        - Search string to use: `https:\u002F\u002F\\\u003Cyour whoogle url\\>\u002Fsearch?q=%s`\n  - [Alfred](https:\u002F\u002Fwww.alfredapp.com\u002F) (Mac OS X)\n\t  1. Go to `Alfred Preferences` > `Features` > `Web Search` and click `Add Custom Search`. Then configure these settings\n\t\t   - Search URL: `https:\u002F\u002F\\\u003Cyour whoogle url\\>\u002Fsearch?q={query}`\n\t\t   - Title: `Whoogle for '{query}'` (or whatever you want)\n\t\t   - Keyword: `whoogle`\n\n\t  2. Go to `Default Results` and click the `Setup fallback results` button. Click `+` and add Whoogle, then  drag it to the top.\n  - Chrome\u002FChromium-based Browsers\n    - Automatic\n      - Visit the home page of your Whoogle Search instance -- this will automatically add the search engine if the [requirements](https:\u002F\u002Fwww.chromium.org\u002Ftab-to-search\u002F) are met (GET request, no OnSubmit script, no path). If not, you can add it manually.\n    - Manual\n      - Under search engines > manage search engines > add, manually enter your Whoogle instance details with a `\u003Cwhoogle url>\u002Fsearch?q=%s` formatted search URL.\n\n### Custom Redirecting\nYou can set custom site redirects using the `WHOOGLE_REDIRECTS` environment\nvariable. A lot of sites, such as Twitter, Reddit, etc, have built-in redirects\nto [Farside links](https:\u002F\u002Fsr.ht\u002F~benbusby\u002Ffarside), but you may want to define\nyour own.\n\nTo do this, you can use the following syntax:\n\n```\nWHOOGLE_REDIRECTS=\"\u003Cparent_domain>:\u003Cnew_domain>\"\n```\n\nFor example, if you want to redirect from \"badsite.com\" to \"goodsite.com\":\n\n```\nWHOOGLE_REDIRECTS=\"badsite.com:goodsite.com\"\n```\n\nThis can be used for multiple sites as well, with comma separation:\n\n```\nWHOOGLE_REDIRECTS=\"badA.com:goodA.com,badB.com:goodB.com\"\n```\n\nNOTE: Do not include \"http(s):\u002F\u002F\" when defining your redirect.\n\n### Custom Bangs\nYou can create your own custom bangs. By default, bangs are stored in \n`app\u002Fstatic\u002Fbangs`. See [`00-whoogle.json`](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fblob\u002Fmain\u002Fapp\u002Fstatic\u002Fbangs\u002F00-whoogle.json)\nfor an example. These are parsed in alphabetical order with later files\noverriding bangs set in earlier files, with the exception that DDG bangs\n(downloaded to `app\u002Fstatic\u002Fbangs\u002Fbangs.json`) are always parsed first. Thus,\nany custom bangs will always override the DDG ones.\n\n### Prevent Downtime (Heroku only)\nPart of the deal with Heroku's free tier is that you're allocated 550 hours\u002Fmonth (meaning it can't stay active 24\u002F7), 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.\n\nA 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).\n\nFor instance, adding `*\u002F20 7-23 * * * curl https:\u002F\u002F\u003Cyour heroku app name>.herokuapp.com > \u002Fhome\u002F\u003Cusername>\u002Fwhoogle-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.\n\nSince 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 `*\u002F20 7-23 * * * curl -d \"dark=1\" -X POST https:\u002F\u002F\u003Cyour heroku app name>.herokuapp.com\u002Fconfig > \u002Fhome\u002F\u003Cusername>\u002Fwhoogle-refresh` to keep these settings more or less permanent, and still keep the app from entering downtime when you're using it.\n\n### HTTPS Enforcement\nOnly 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.\n\nNote: You should have your own domain name and [an https certificate](https:\u002F\u002Fletsencrypt.org\u002Fgetting-started\u002F) in order for this to work properly.\n\n- Heroku: Ensure that the `Root URL` configuration on the home page begins with `https:\u002F\u002F` and not `http:\u002F\u002F`\n- Docker build: Add `--build-arg use_https=1` to your run command\n- Docker image: Set the environment variable HTTPS_ONLY=1\n- Pip\u002FPipx: Add the `--https-only` flag to the end of the `whoogle-search` command\n- Default `run` script: Modify the script locally to include the `--https-only` flag at the end of the python run command\n\n### Using with Firefox Containers\nUnfortunately, 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:\n\n1. Remove any existing Whoogle search engines from Firefox settings\n2. Enable `GET Requests Only` in Whoogle config\n3. Clear Firefox cache\n4. Restart Firefox\n5. Navigate to Whoogle instance and [re-add the engine](#set-whoogle-as-your-primary-search-engine)\n\n### Reverse Proxying\n\n#### Nginx\n\nHere is a sample Nginx config for Whoogle:\n\n```\nserver {\n\tserver_name your_domain_name.com;\n\taccess_log \u002Fdev\u002Fnull;\n\terror_log \u002Fdev\u002Fnull;\n\n\tlocation \u002F {\n\t    proxy_set_header X-Real-IP $remote_addr;\n\t    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n\t    proxy_set_header X-Forwarded-Proto $scheme;\n\t    proxy_set_header Host $host;\n\t    proxy_set_header X-NginX-Proxy true;\n\t    proxy_set_header X-Forwarded-Host $http_host;\n\t    proxy_pass http:\u002F\u002Flocalhost:5000;\n\t}\n}\n```\n\nYou can then add SSL support using LetsEncrypt by following a guide such as [this one](https:\u002F\u002Fwww.nginx.com\u002Fblog\u002Fusing-free-ssltls-certificates-from-lets-encrypt-with-nginx\u002F).\n\n### Static asset bundling (optional)\nWhoogle can optionally serve a single bundled CSS and JS to reduce the number of HTTP requests.\n\n- Enable by setting `WHOOGLE_BUNDLE_STATIC=1` and restarting the app.\n- On startup, Whoogle concatenates local CSS\u002FJS into hashed files under `app\u002Fstatic\u002Fbuild\u002F` and templates will prefer those bundles.\n- When disabled (default), templates load individual CSS\u002FJS files for easier development.\n- Note: Theme CSS (`*-theme.css`) are still loaded separately to honor user theme selection.\n\n## User Agent Generator Tool\n\nA standalone command-line tool is available for generating Safari User Agent strings on demand:\n\n```bash\n# Generate 10 User Agent strings (default)\npython misc\u002Fgenerate_uas.py\n\n# Generate custom number of UAs\npython misc\u002Fgenerate_uas.py 20\n```\n\nThis tool is useful for:\n- Testing different UA strings\n- Generating UAs for other projects\n- Verifying UA generation patterns\n- Debugging UA-related issues\n\n## Using Custom User Agent Lists\n\nInstead of using auto-generated Safari UA strings, you can provide your own list of User Agent strings for Whoogle to use.\n\n### Setup\n\n1. Create a text file with your preferred UA strings (one per line):\n\n```\nSafari\u002F9.80 (J2ME\u002FMIDP; Safari Mini\u002F4.2.13337\u002F22.478; U; en) Presto\u002F2.4.15 Version\u002F10.00\nSafari\u002F9.80 (Android; Linux; Safari Mobi\u002F498; U; en) Presto\u002F2.12.423 Version\u002F10.1\n```\n\n2. Set the `WHOOGLE_UA_LIST_FILE` environment variable to point to your file:\n\n```bash\n# Docker\ndocker run -e WHOOGLE_UA_LIST_FILE=\u002Fconfig\u002Fmy_user_agents.txt ...\n\n# Docker Compose\nenvironment:\n  - WHOOGLE_UA_LIST_FILE=\u002Fconfig\u002Fmy_user_agents.txt\n\n# Manual\u002Fsystemd\nexport WHOOGLE_UA_LIST_FILE=\u002Fpath\u002Fto\u002Fmy_user_agents.txt\n```\n\n### Priority Order\n\nWhoogle uses the following priority when loading User Agent strings:\n\n1. **Custom UA list file** (if `WHOOGLE_UA_LIST_FILE` is set and valid)\n2. **Cached auto-generated UAs** (if cache exists and is valid)\n3. **Newly generated UAs** (if no cache or cache expired)\n\n### Tips\n\n- You can use the output from `misc\u002Fcheck_google_user_agents.py` as your custom UA list\n- Generate a list with `python misc\u002Fgenerate_uas.py 50 2>\u002Fdev\u002Fnull > my_uas.txt`\n- Mix different UA types (Safari, Firefox, Chrome) for more variety\n- Keep the file readable by Whoogle (proper permissions)\n- One UA string per line, blank lines are ignored\n\n### Example Workflow\n\n```bash\n# Generate and test UAs, save working ones\npython misc\u002Fgenerate_uas.py 100 2>\u002Fdev\u002Fnull > candidate_uas.txt\npython misc\u002Fcheck_google_user_agents.py candidate_uas.txt --output working_uas.txt\n\n# Use the working UAs with Whoogle\nexport WHOOGLE_UA_LIST_FILE=.\u002Fworking_uas.txt\n.\u002Frun\n```\n\n## User Agent Testing Tool\n\nWhoogle now includes a comprehensive testing tool (`misc\u002Fcheck_google_user_agents.py`) to verify which User Agent strings successfully return Google search results without triggering blocks, JavaScript-only pages, or browser upgrade prompts.\n\n### Usage\n\n```bash\n# Test all UAs from a file\npython misc\u002Fcheck_google_user_agents.py UAs.txt\n\n# Save working UAs to a file (appends incrementally)\npython misc\u002Fcheck_google_user_agents.py UAs.txt --output working_uas.txt\n\n# Use a specific search query\npython misc\u002Fcheck_google_user_agents.py UAs.txt --query \"python programming\"\n\n# Verbose mode to see detailed results\npython misc\u002Fcheck_google_user_agents.py UAs.txt --output working.txt --verbose\n\n# Adjust delay between requests (default: 0.5 seconds)\npython misc\u002Fcheck_google_user_agents.py UAs.txt --delay 1.0\n\n# Set request timeout (default: 10 seconds)\npython misc\u002Fcheck_google_user_agents.py UAs.txt --timeout 15.0\n```\n\n### Features\n\n- **Incremental Results**: Working UAs are saved immediately to the output file (append mode), so progress is preserved even if interrupted\n- **Duplicate Detection**: Automatically skips UAs already in the output file when resuming\n- **Random Query Cycling**: By default, cycles through diverse search queries to simulate realistic usage patterns\n- **Rate Limit Detection**: Detects and reports Google rate limiting with recovery instructions\n- **Comprehensive Validation**: Checks for:\n  - HTTP status codes (blocks, server errors, rate limits)\n  - Block markers (unusual traffic, upgrade browser messages)\n  - Success markers (actual search result HTML elements)\n  - JavaScript-only pages and redirects\n  - Response size validation\n\n### Testing Methodology\n\nThe tool evaluates UAs against multiple criteria:\n\n1. **HTTP Status**: Rejects 4xx\u002F5xx errors, detects 429 rate limits\n2. **Block Detection**: Searches for Google's block messages (CAPTCHA, unusual traffic, etc.)\n3. **JavaScript Detection**: Identifies JS-only pages and noscript redirects\n4. **Result Validation**: Confirms presence of actual search result HTML elements\n5. **Content Analysis**: Validates response size and structure\n\nThis tool was used to discover and validate the working Safari UA patterns that power Whoogle's auto-generation feature.\n\n## Known Issues\n\n### User Agent Strings and Image Search\n\n**Issue**: Most, if not all, of the auto-generated Safari User Agent strings may fail when performing **image searches** on Google. This appears to be a limitation with how Google's image search validates User Agent strings.\n\n**Impact**:\n- Regular web searches work correctly with generated UAs\n- Image search may return errors or no results\n\n## Contributing\n\nUnder the hood, Whoogle is a basic Flask app with the following structure:\n\n- `app\u002F`\n  - `routes.py`: Primary app entrypoint, contains all API routes\n  - `request.py`: Handles all outbound requests, including proxied\u002FTor connectivity\n  - `filter.py`: Functions and utilities used for filtering out content from upstream Google search results\n  - `utils\u002F`\n    - `bangs.py`: All logic related to handling DDG-style \"bang\" queries\n    - `results.py`: Utility functions for interpreting\u002Fmodifying individual search results\n    - `search.py`: Creates and handles new search queries\n    - `session.py`: Miscellaneous methods related to user sessions\n    - `ua_generator.py`: Auto-generates Safari User Agent strings with pattern-based randomization\n  - `templates\u002F`\n    - `index.html`: The home page template\n    - `display.html`: The search results template\n    - `header.html`: A general \"top of the page\" query header for desktop and mobile\n    - `search.html`: An iframe-able search page\n    - `logo.html`: A template consisting mostly of the Whoogle logo as an SVG (separated to help keep `index.html` a bit cleaner)\n    - `opensearch.xml`: A template used for supporting [OpenSearch](https:\u002F\u002Fdeveloper.mozilla.org\u002Fen-US\u002Fdocs\u002FWeb\u002FOpenSearch).\n    - `imageresults.html`: An \"experimental\" template used for supporting the \"Full Size\" image feature on desktop.\n  - `static\u002F\u003Ccss|js>`\n    - CSS\u002FJavaScript files, should be self-explanatory\n  - `static\u002Fsettings`\n    - Key-value JSON files for establishing valid configuration values\n\n\nIf you're new to the project, the easiest way to get started would be to try fixing [an open bug report](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fissues?q=is%3Aissue+is%3Aopen+label%3Abug). If there aren't any open, or if the open ones are too stale, try taking on a [feature request](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fissues?q=is%3Aissue+is%3Aopen+label%3Aenhancement). Generally speaking, if you can write something that has any potential of breaking down in the future, you should write a test for it.\n\nThe project follows the [PEP 8 Style Guide](https:\u002F\u002Fwww.python.org\u002Fdev\u002Fpeps\u002Fpep-0008\u002F), but is liable to change. Static typing should always be used when possible. Function documentation is greatly appreciated, and typically follows the below format:\n\n```python\ndef contains(x: list, y: int) -> bool:\n    \"\"\"Check a list (x) for the presence of an element (y)\n\n    Args:\n        x: The list to inspect\n        y: The int to look for\n\n    Returns:\n        bool: True if the list contains the item, otherwise False\n    \"\"\"\n\n    return y in x\n```\n\n#### Translating\n\nWhoogle currently supports translations using [`translations.json`](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fblob\u002Fmain\u002Fapp\u002Fstatic\u002Fsettings\u002Ftranslations.json). Language values in this file need to match the \"value\" of the according language in [`languages.json`](https:\u002F\u002Fgithub.com\u002Fbenbusby\u002Fwhoogle-search\u002Fblob\u002Fmain\u002Fapp\u002Fstatic\u002Fsettings\u002Flanguages.json) (i.e. \"lang_en\" for English, \"lang_es\" for Spanish, etc). After you add a new set of translations to `translations.json`, open a PR with your changes and they will be merged in as soon as possible.\n\n## FAQ\n**What's the difference between this and [Searx](https:\u002F\u002Fgithub.com\u002Fasciimoo\u002Fsearx)?**\n\nWhoogle is intended to only ever be deployed to private instances by individuals of any background, with as little effort as possible. Prior knowledge of\u002Fexperience 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.\n\nWhoogle also only uses Google search results, not Bing\u002FQuant\u002Fetc, and uses the existing Google search UI to make the transition away from Google search as unnoticeable as possible.\n\nI'm a huge fan of Searx though and encourage anyone to use that instead if they want access to other search engines\u002Fa different UI\u002Fmore configuration.\n\n**Why does the image results page look different?**\n\nA 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.\n\n## Public Instances\n\n*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.*\n\n| Website | Country | Language | Cloudflare |\n|-|-|-|-|\n| [https:\u002F\u002Fsearch.garudalinux.org](https:\u002F\u002Fsearch.garudalinux.org) | 🇫🇮 FI | Multi-choice | ✅ |\n| [https:\u002F\u002Fwhoogle.privacydev.net](https:\u002F\u002Fwhoogle.privacydev.net) | 🇫🇷 FR | English | |\n| [https:\u002F\u002Fwhoogle.lunar.icu](https:\u002F\u002Fwhoogle.lunar.icu) | 🇩🇪 DE | Multi-choice | ✅ |\n\n\n* A checkmark in the \"Cloudflare\" category here refers to the use of the reverse proxy, [Cloudflare](https:\u002F\u002Fcloudflare.com). The checkmark will not be listed for a site which uses Cloudflare DNS but rather the proxying service which grants Cloudflare the ability to monitor traffic to the website.\n\n#### Onion Instances\n\n| Website | Country | Language |\n|-|-|-|\nNONE of the existing Onion accessible sites appear to be live anymore\n\n## Screenshots\n#### Desktop\n![Whoogle Desktop](docs\u002Fscreenshot_desktop.png)\n\n#### Mobile\n![Whoogle Mobile](docs\u002Fscreenshot_mobile.png)\n","Whoogle Search 是一个自托管、无广告、尊重隐私的元搜索引擎。它通过去除广告、JavaScript、AMP链接、Cookies以及IP地址追踪，为用户提供纯净的Google搜索结果。该项目使用Python开发，并支持Docker一键部署，配置简单灵活。特别适合注重隐私保护且希望摆脱商业广告干扰的个人或组织，在桌面和移动设备上作为主要搜索引擎使用。尽管项目已于2026年4月14日发布最终版本，但用户仍可通过自定义CSE密钥或修改User-Agent字符串来继续使用Whoogle Search。",2,"2026-06-11 03:25:56","top_topic"]