[ { "path": ".dockerignore", "content": ".git/\nvenv/\ntest/\n" }, { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\ngithub: benbusby\nko_fi: benbusby\ntidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel\ncommunity_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry\nliberapay: # Replace with a single Liberapay username\nissuehunt: # Replace with a single IssueHunt username\notechie: # Replace with a single Otechie username\ncustom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.md", "content": "---\nname: Bug report\nabout: Create a bug report to help fix an issue with Whoogle\ntitle: \"[BUG] \"\nlabels: bug\nassignees: ''\n\n---\n\n**Describe the bug**\nA clear and concise description of what the bug is.\n\n**To Reproduce**\nSteps to reproduce the behavior:\n1. Go to '...'\n2. Click on '....'\n3. Scroll down to '....'\n4. See error\n\n**Deployment Method**\n- [ ] Heroku (one-click deploy)\n- [ ] Docker\n- [ ] `run` executable\n- [ ] pip/pipx\n- [ ] Other: [describe setup]\n\n**Version of Whoogle Search**\n- [ ] Latest build from [source] (i.e. GitHub, Docker Hub, pip, etc)\n- [ ] Version [version number]\n- [ ] Not sure\n\n\n**Desktop (please complete the following information):**\n - OS: [e.g. iOS]\n - Browser [e.g. chrome, safari]\n - Version [e.g. 22]\n\n**Smartphone (please complete the following information):**\n - Device: [e.g. iPhone6]\n - OS: [e.g. iOS8.1]\n - Browser [e.g. stock browser, safari]\n - Version [e.g. 22]\n\n**Additional context**\nAdd any other context about the problem here.\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.md", "content": "---\nname: Feature request\nabout: Suggest a feature that would improve Whoogle\ntitle: \"[FEATURE] \"\nlabels: enhancement\nassignees: ''\n\n---\n\n\n\n**Describe the feature you'd like to see added**\nA short description of the feature, and what it would accomplish.\n\n**Additional context**\nAdd any other context or screenshots about the feature request here.\n" }, { "path": ".github/ISSUE_TEMPLATE/new-theme.md", "content": "---\nname: New theme\nabout: Create a new theme for Whoogle\ntitle: \"[THEME] \"\nlabels: theme\nassignees: benbusby\n\n---\n\nUse the following template to design your theme, replacing the blank spaces with the colors of your choice.\n\n```css\n:root {\n /* LIGHT THEME COLORS */\n --whoogle-logo: #______;\n --whoogle-page-bg: #______;\n --whoogle-element-bg: #______;\n --whoogle-text: #______;\n --whoogle-contrast-text: #______;\n --whoogle-secondary-text: #______;\n --whoogle-result-bg: #______;\n --whoogle-result-title: #______;\n --whoogle-result-url: #______;\n --whoogle-result-visited: #______;\n\n /* DARK THEME COLORS */\n --whoogle-dark-logo: #______;\n --whoogle-dark-page-bg: #______;\n --whoogle-dark-element-bg: #______;\n --whoogle-dark-text: #______;\n --whoogle-dark-contrast-text: #______;\n --whoogle-dark-secondary-text: #______;\n --whoogle-dark-result-bg: #______;\n --whoogle-dark-result-title: #______;\n --whoogle-dark-result-url: #______;\n --whoogle-dark-result-visited: #______;\n}\n```\n" }, { "path": ".github/ISSUE_TEMPLATE/question.md", "content": "---\nname: Question\nabout: Ask a (simple) question about Whoogle\ntitle: \"[QUESTION] \"\nlabels: question\nassignees: ''\n\n---\n\nType out your question here. Please make sure that this is a topic that isn't already covered in the README.\n" }, { "path": ".github/workflows/buildx.yml", "content": "name: buildx\n\non:\n workflow_run:\n workflows: [\"docker_main\"]\n branches: [main, updates]\n types:\n - completed\n push:\n tags:\n - '*'\n release:\n types:\n - published\n\njobs:\n on-success:\n runs-on: ubuntu-latest\n steps:\n - name: Wait for tests to succeed\n if: ${{ github.event.workflow_run.conclusion != 'success' && startsWith(github.ref, 'refs/tags') != true }}\n run: exit 1\n - name: Debug workflow context\n run: |\n echo \"Event name: ${{ github.event_name }}\"\n echo \"Ref: ${{ github.ref }}\"\n echo \"Actor: ${{ github.actor }}\"\n echo \"Branch: ${{ github.event.workflow_run.head_branch }}\"\n echo \"Conclusion: ${{ github.event.workflow_run.conclusion }}\"\n - name: checkout code\n uses: actions/checkout@v4\n - name: Set up QEMU\n uses: docker/setup-qemu-action@v3\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n - name: Login to Docker Hub\n uses: docker/login-action@v3\n with:\n username: ${{ secrets.DOCKER_USERNAME }}\n password: ${{ secrets.DOCKER_PASSWORD }}\n - name: Login to ghcr.io\n uses: docker/login-action@v3\n with:\n registry: ghcr.io\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n # Disabled: only build on release events now\n # - name: build and push the image\n # if: startsWith(github.ref, 'refs/heads/main') && (github.actor == 'benbusby' || github.actor == 'Don-Swanson')\n # run: |\n # docker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n # docker buildx ls\n # docker buildx build --push \\\n # --tag benbusby/whoogle-search:latest \\\n # --platform linux/amd64,linux/arm64 .\n # docker buildx build --push \\\n # --tag ghcr.io/benbusby/whoogle-search:latest \\\n # --platform linux/amd64,linux/arm64 .\n - name: build and push updates branch (update-testing tag)\n if: github.event_name == 'workflow_run' && github.event.workflow_run.head_branch == 'updates' && github.event.workflow_run.conclusion == 'success' && (github.event.workflow_run.actor.login == 'benbusby' || github.event.workflow_run.actor.login == 'Don-Swanson')\n run: |\n docker buildx build --push \\\n --tag benbusby/whoogle-search:update-testing \\\n --tag ghcr.io/benbusby/whoogle-search:update-testing \\\n --platform linux/amd64,linux/arm64 .\n - name: build and push release (version + latest)\n if: github.event_name == 'release' && github.event.release.prerelease == false && (github.actor == 'benbusby' || github.actor == 'Don-Swanson')\n run: |\n TAG=\"${{ github.event.release.tag_name }}\"\n VERSION=\"${TAG#v}\"\n docker buildx build --push \\\n --tag benbusby/whoogle-search:${VERSION} \\\n --tag benbusby/whoogle-search:latest \\\n --tag ghcr.io/benbusby/whoogle-search:${VERSION} \\\n --tag ghcr.io/benbusby/whoogle-search:latest \\\n --platform linux/amd64,linux/arm64 .\n - name: build and push pre-release (version only)\n if: github.event_name == 'release' && github.event.release.prerelease == true && (github.actor == 'benbusby' || github.actor == 'Don-Swanson')\n run: |\n TAG=\"${{ github.event.release.tag_name }}\"\n VERSION=\"${TAG#v}\"\n docker buildx build --push \\\n --tag benbusby/whoogle-search:${VERSION} \\\n --tag ghcr.io/benbusby/whoogle-search:${VERSION} \\\n --platform linux/amd64,linux/arm64 .\n - name: build and push tag\n if: startsWith(github.ref, 'refs/tags')\n run: |\n docker buildx build --push \\\n --tag benbusby/whoogle-search:${GITHUB_REF#refs/*/v} \\\n --tag ghcr.io/benbusby/whoogle-search:${GITHUB_REF#refs/*/v} \\\n --platform linux/amd64,linux/arm64 .\n" }, { "path": ".github/workflows/docker_main.yml", "content": "name: docker_main\n\non:\n workflow_run:\n workflows: [\"tests\"]\n branches: [main, updates]\n types:\n - completed\n\n# TODO: Needs refactoring to use reusable workflows and share w/ docker_tests\njobs:\n on-success:\n runs-on: ubuntu-latest\n if: ${{ github.event.workflow_run.conclusion == 'success' }}\n steps:\n - name: checkout code\n uses: actions/checkout@v4\n - name: build and test (docker)\n run: |\n docker build --tag whoogle-search:test .\n docker run --publish 5000:5000 --detach --name whoogle-search-nocompose whoogle-search:test\n sleep 15\n docker exec whoogle-search-nocompose curl -f http://localhost:5000/healthz || exit 1\n - name: build and test (docker-compose)\n run: |\n docker rm -f whoogle-search-nocompose\n WHOOGLE_IMAGE=\"whoogle-search:test\" docker compose up --detach\n sleep 15\n docker exec whoogle-search curl -f http://localhost:5000/healthz || exit 1\n" }, { "path": ".github/workflows/docker_tests.yml", "content": "name: docker_tests\n\non:\n push:\n branches: main\n pull_request:\n branches: main\n\njobs:\n docker:\n runs-on: ubuntu-latest\n steps:\n - name: checkout code\n uses: actions/checkout@v2\n - name: build and test (docker)\n run: |\n docker build --tag whoogle-search:test .\n docker run --publish 5000:5000 --detach --name whoogle-search-nocompose whoogle-search:test\n sleep 15\n docker exec whoogle-search-nocompose curl -f http://localhost:5000/healthz || exit 1\n - name: build and test (docker compose)\n run: |\n docker rm -f whoogle-search-nocompose\n WHOOGLE_IMAGE=\"whoogle-search:test\" docker compose up --detach\n sleep 15\n docker exec whoogle-search curl -f http://localhost:5000/healthz || exit 1\n" }, { "path": ".github/workflows/pypi.yml", "content": "name: pypi\n\non:\n push:\n branches: main\n tags: v*\n\njobs:\n publish-test:\n name: Build and publish to TestPyPI\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Set up Python 3.9\n uses: actions/setup-python@v5\n with:\n python-version: 3.9\n - name: Install pypa/build\n run: >-\n python -m\n pip install\n build\n setuptools\n --user\n - name: Set dev timestamp\n run: echo \"DEV_BUILD=$(date +%s)\" >> $GITHUB_ENV\n - name: Build binary wheel and source tarball\n run: >-\n python -m\n build\n --sdist\n --wheel\n --outdir dist/\n .\n - name: Publish distribution to TestPyPI\n uses: pypa/gh-action-pypi-publish@master\n with:\n password: ${{ secrets.TEST_PYPI_API_TOKEN }}\n repository_url: https://test.pypi.org/legacy/\n publish:\n # Gate real PyPI publishing to stable SemVer tags only\n if: startsWith(github.ref, 'refs/tags/')\n name: Build and publish to PyPI\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Check if stable release\n id: check_tag\n run: |\n TAG=\"${{ github.ref_name }}\"\n if echo \"$TAG\" | grep -qE '^v?[0-9]+\\.[0-9]+\\.[0-9]+$'; then\n echo \"is_stable=true\" >> $GITHUB_OUTPUT\n echo \"Tag '$TAG' is a stable release. Will publish to PyPI.\"\n else\n echo \"is_stable=false\" >> $GITHUB_OUTPUT\n echo \"Tag '$TAG' is not a stable release (contains pre-release suffix). Skipping PyPI publish.\"\n fi\n - name: Set up Python 3.9\n if: steps.check_tag.outputs.is_stable == 'true'\n uses: actions/setup-python@v5\n with:\n python-version: 3.9\n - name: Install pypa/build\n if: steps.check_tag.outputs.is_stable == 'true'\n run: >-\n python -m\n pip install\n build\n --user\n - name: Build binary wheel and source tarball\n if: steps.check_tag.outputs.is_stable == 'true'\n run: >-\n python -m\n build\n --sdist\n --wheel\n --outdir dist/\n .\n - name: Publish distribution to PyPI\n if: steps.check_tag.outputs.is_stable == 'true'\n uses: pypa/gh-action-pypi-publish@master\n with:\n password: ${{ secrets.PYPI_API_TOKEN }}" }, { "path": ".github/workflows/scan.yml", "content": "name: scan\n\non:\n schedule:\n - cron: '0 0 * * *'\n\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n - name: Build the container image\n run: |\n docker build --tag whoogle-search:test .\n - name: Initiate grype scan\n run: |\n curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b .\n chmod +x ./grype\n ./grype whoogle-search:test --only-fixed\n" }, { "path": ".github/workflows/stale.yml", "content": "# This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time.\n#\n# You can adjust the behavior by modifying this file.\n# For more information, see:\n# https://github.com/actions/stale\nname: Mark stale issues and pull requests\n\non:\n schedule:\n - cron: '35 10 * * *'\n\njobs:\n stale:\n\n runs-on: ubuntu-latest\n permissions:\n issues: write\n pull-requests: write\n\n steps:\n - uses: actions/stale@v10\n with:\n days-before-stale: 90\n days-before-close: 7\n stale-issue-message: 'This issue has been automatically marked as stale due to inactivity. If it is still valid please comment within 7 days or it will be auto-closed.'\n close-issue-message: 'Closing this issue due to prolonged inactivity.'\n # Disabled PR Closing for now, but pre-staged the settings\n days-before-pr-stale: -1\n days-before-pr-close: -1\n operations-per-run: 100\n stale-pr-message: \"This PR appears to be stale. If it is still valid please comment within 14 days or it will be auto-closed.\"\n close-pr-message: \"This PR was closed as stale.\"\n exempt-issue-labels: 'keep-open,enhancement,critical,dependencies,documentation'\n" }, { "path": ".github/workflows/tests.yml", "content": "name: tests\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.x'\n - name: Install dependencies\n run: pip install --upgrade pip && pip install -r requirements.txt\n - name: Run tests\n run: ./run test\n" }, { "path": ".gitignore", "content": "venv/\n.venv/\n.idea/\n__pycache__/\n*.pyc\n*.pem\n*.conf\n*.key\nconfig.json\ntest/static\nflask_session/\napp/static/config\napp/static/custom_config\napp/static/bangs/*\n!app/static/bangs/00-whoogle.json\n\n# pip stuff\n/build/\ndist/\n*.egg-info/\n\n# env\nwhoogle.env\n\n# vim\n*~\n*.swp\n" }, { "path": ".pre-commit-config.yaml", "content": "repos:\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.6.9\n hooks:\n - id: ruff\n args: [--fix]\n - id: ruff-format\n - repo: https://github.com/psf/black\n rev: 24.8.0\n hooks:\n - id: black\n args: [--quiet]\n\n" }, { "path": ".replit", "content": "entrypoint = \"misc/replit.py\"\n" }, { "path": "Dockerfile", "content": "# NOTE: ARMv7 support has been dropped due to lack of pre-built cryptography wheels for Alpine/musl.\n# To restore ARMv7 support for local builds:\n# 1. Change requirements.txt:\n# cryptography==3.3.2; platform_machine == 'armv7l'\n# cryptography==46.0.1; platform_machine != 'armv7l'\n# pyOpenSSL==19.1.0; platform_machine == 'armv7l'\n# pyOpenSSL==25.3.0; platform_machine != 'armv7l'\n# 2. Add linux/arm/v7 to --platform flag when building:\n# docker buildx build --platform linux/amd64,linux/arm/v7,linux/arm64 .\n\nFROM python:3.12-alpine3.22 AS builder\n\nRUN apk --no-cache add \\\n build-base \\\n libxml2-dev \\\n libxslt-dev \\\n openssl-dev \\\n libffi-dev\n\nCOPY requirements.txt .\n\nRUN pip install --upgrade pip\nRUN pip install --prefix /install --no-warn-script-location --no-cache-dir -r requirements.txt\n\nFROM python:3.12-alpine3.22\n\n# Remove bridge package to avoid CVEs (not needed for Docker containers)\nRUN apk add --no-cache --no-scripts tor curl openrc libstdc++ && \\\n apk del --no-cache bridge || true\n# git go //for obfs4proxy\n# libcurl4-openssl-dev\nRUN pip install --upgrade pip\nRUN apk --no-cache upgrade && \\\n apk del --no-cache --rdepends bridge || true\n\n# uncomment to build obfs4proxy\n# RUN git clone https://gitlab.com/yawning/obfs4.git\n# WORKDIR /obfs4\n# RUN go build -o obfs4proxy/obfs4proxy ./obfs4proxy\n# RUN cp ./obfs4proxy/obfs4proxy /usr/bin/obfs4proxy\n\nARG DOCKER_USER=whoogle\nARG DOCKER_USERID=927\nARG config_dir=/config\nRUN mkdir -p $config_dir\nRUN chmod a+w $config_dir\nVOLUME $config_dir\n\nARG url_prefix=''\nARG username=''\nARG password=''\nARG proxyuser=''\nARG proxypass=''\nARG proxytype=''\nARG proxyloc=''\nARG whoogle_dotenv=''\nARG use_https=''\nARG whoogle_port=5000\nARG twitter_alt='farside.link/nitter'\nARG youtube_alt='farside.link/invidious'\nARG reddit_alt='farside.link/libreddit'\nARG medium_alt='farside.link/scribe'\nARG translate_alt='farside.link/lingva'\nARG imgur_alt='farside.link/rimgo'\nARG wikipedia_alt='farside.link/wikiless'\nARG imdb_alt='farside.link/libremdb'\nARG quora_alt='farside.link/quetre'\nARG so_alt='farside.link/anonymousoverflow'\n\nENV CONFIG_VOLUME=$config_dir \\\n WHOOGLE_URL_PREFIX=$url_prefix \\\n WHOOGLE_USER=$username \\\n WHOOGLE_PASS=$password \\\n WHOOGLE_PROXY_USER=$proxyuser \\\n WHOOGLE_PROXY_PASS=$proxypass \\\n WHOOGLE_PROXY_TYPE=$proxytype \\\n WHOOGLE_PROXY_LOC=$proxyloc \\\n WHOOGLE_DOTENV=$whoogle_dotenv \\\n HTTPS_ONLY=$use_https \\\n EXPOSE_PORT=$whoogle_port \\\n WHOOGLE_ALT_TW=$twitter_alt \\\n WHOOGLE_ALT_YT=$youtube_alt \\\n WHOOGLE_ALT_RD=$reddit_alt \\\n WHOOGLE_ALT_MD=$medium_alt \\\n WHOOGLE_ALT_TL=$translate_alt \\\n WHOOGLE_ALT_IMG=$imgur_alt \\\n WHOOGLE_ALT_WIKI=$wikipedia_alt \\\n WHOOGLE_ALT_IMDB=$imdb_alt \\\n WHOOGLE_ALT_QUORA=$quora_alt \\\n WHOOGLE_ALT_SO=$so_alt\n\nWORKDIR /whoogle\n\nCOPY --from=builder /install /usr/local\nCOPY misc/tor/torrc /etc/tor/torrc\nCOPY misc/tor/start-tor.sh misc/tor/start-tor.sh\nCOPY app/ app/\nCOPY run whoogle.env* ./\n\n# Create user/group to run as\nRUN adduser -D -g $DOCKER_USERID -u $DOCKER_USERID $DOCKER_USER\n\n# Fix ownership / permissions\nRUN chown -R ${DOCKER_USER}:${DOCKER_USER} /whoogle /var/lib/tor\n\n# Allow writing symlinks to build dir\nRUN chown $DOCKER_USERID:$DOCKER_USERID app/static/build\n\nUSER $DOCKER_USER:$DOCKER_USER\n\nEXPOSE $EXPOSE_PORT\n\nHEALTHCHECK --interval=30s --timeout=5s \\\n CMD curl -f http://localhost:${EXPOSE_PORT}/healthz || exit 1\n\nCMD [\"/bin/sh\", \"-c\", \"misc/tor/start-tor.sh & ./run\"]\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2020 Ben Busby\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "MANIFEST.in", "content": "graft app/static\ngraft app/templates\ngraft app/misc\ninclude requirements.txt\nrecursive-include test\nglobal-exclude *.pyc\n" }, { "path": "README.md", "content": ">[!WARNING]\n>\n>Since 16 January, 2025, Google has been attacking the ability to perform search queries without JavaScript enabled. This is a fundamental part of how Whoogle\n>works -- Whoogle requests the JavaScript-free search results, then filters out garbage from the results page and proxies all external content for the user.\n>\n>This is possibly a breaking change that may mean the end for Whoogle. We'll continue fighting back and releasing workarounds until all workarounds are \n>exhausted or a better method is found. If you know of a better way, please review and comment in our Way Forward Discussion\n\n___\n\n![Whoogle Search](docs/banner.png)\n\n[![Latest Release](https://img.shields.io/github/v/release/benbusby/whoogle-search)](https://github.com/benbusby/shoogle/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![tests](https://github.com/benbusby/whoogle-search/actions/workflows/tests.yml/badge.svg)](https://github.com/benbusby/whoogle-search/actions/workflows/tests.yml)\n[![buildx](https://github.com/benbusby/whoogle-search/actions/workflows/buildx.yml/badge.svg)](https://github.com/benbusby/whoogle-search/actions/workflows/buildx.yml)\n[![Docker Pulls](https://img.shields.io/docker/pulls/benbusby/whoogle-search)](https://hub.docker.com/r/benbusby/whoogle-search)\n\n\n \n \n \n \n
SourceHutGitHub
\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/Deploy 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/AUR](#arch-linux--arch-based-distributions)\n 1. [Helm/Kubernetes](#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/linking 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/SOCKS proxy support\n- Autocomplete/search suggestions\n- POST request search and suggestion queries (when possible)\n- View images at full res without site redirect (currently mobile only)\n- Light/Dark/System theme modes (with support for [custom CSS theming](https://github.com/benbusby/whoogle-search/wiki/User-Contributed-CSS-Themes))\n- Auto-generated Opera User Agents with random rotation\n - 10 unique Opera-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/deploy\n- DDG-style bang (i.e. `! `) searches\n- User-defined [custom bangs](#custom-bangs)\n- Optional location-based searching (i.e. results near \\)\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*No third party JavaScript. Whoogle can be used with JavaScript disabled, but if enabled, uses JavaScript for things like presenting search suggestions.\n\n**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.\n\n***If deployed to a remote server, or configured to send requests through a VPN, Tor, proxy, etc.\n\n## Install\n\n### Supported Platforms\nOfficial Docker images are built for:\n- **linux/amd64** (x86_64)\n- **linux/arm64** (ARM 64-bit, Raspberry Pi 3/4/5, 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://heroku.com/about)\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/benbusby/whoogle-search/tree/main)\n\nProvides:\n- Easy Deployment of App\n- A HTTPS url (https://\\.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://render.com)\n\nCreate an account on [render.com](https://render.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: `./run`\n\n___\n\n### [Repl.it](https://repl.it)\n[![Run on Repl.it](https://repl.it/badge/github/benbusby/whoogle-search)](https://repl.it/github/benbusby/whoogle-search)\n\n*Note: Requires a (free) Replit account*\n\nProvides:\n- Free deployment of app\n- Free HTTPS url (https://\\.\\\\.repl\\.co)\n - Supports custom domains\n- Downtime after periods of inactivity ([solution](https://repl.it/talk/learn/How-to-use-and-setup-UptimeRobot/9003)\\)\n\n___\n\n### [Fly.io](https://fly.io)\n\nYou will need a [Fly.io](https://fly.io) account to deploy Whoogle.\n\n#### Install the CLI: https://fly.io/docs/hands-on/installing/\n\n#### Deploy the app\n\n```bash\nflyctl auth login\nflyctl launch --image benbusby/whoogle-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://.fly.dev`.\n\nNotes:\n- Requires a [**PAID**](https://fly.io/docs/about/pricing/#free-allowances) Fly.io Account.\n\n___\n\n### [Koyeb](https://www.koyeb.com)\n\nUse one of the following guides to install Whoogle on Koyeb:\n\n1. Using GitHub: https://www.koyeb.com/docs/quickstart/deploy-with-git\n2. Using Docker: https://www.koyeb.com/docs/quickstart/deploy-a-docker-application\n\n___\n\n### [RepoCloud](https://repocloud.io)\n[![Deploy on RepoCloud](https://d16t0pc4846x52.cloudfront.net/deploylobe.svg)](https://repocloud.io/details/?app_id=309)\n\n1. Sign up for a free [RepoCloud account](https://repocloud.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://github.com/pipxproject/pipx#install-pipx)\nPersistent install:\n\n`pipx install https://github.com/benbusby/whoogle-search/archive/refs/heads/main.zip`\n\nSandboxed temporary instance:\n\n`pipx run --spec git+https://github.com/benbusby/whoogle-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 ] [--host ] [--debug] [--https-only] [--userpass ]\n [--proxyauth ] [--proxytype ] [--proxyloc ]\n\nWhoogle Search console runner\n\noptional arguments:\n -h, --help Show this help message and exit\n --port Specifies a port to run on (default 5000)\n --host 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 \n Sets a username/password basic auth combo (default None)\n --proxyauth \n Sets a username/password for a HTTP/SOCKS proxy (default None)\n --proxytype \n Sets a proxy type for all connections (default None)\n --proxyloc \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://www.python.org/downloads/)\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://github.com/benbusby/whoogle-search.git\ncd whoogle-search\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n./run\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 `/lib/systemd/system/whoogle.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=\n#Environment=WHOOGLE_PASS=\n# Proxy configuration, uncomment to enable\n#Environment=WHOOGLE_PROXY_USER=\n#Environment=WHOOGLE_PROXY_PASS=\n#Environment=WHOOGLE_PROXY_TYPE=\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/nitter\n#Environment=WHOOGLE_ALT_YT=farside.link/invidious\n#Environment=WHOOGLE_ALT_RD=farside.link/libreddit\n#Environment=WHOOGLE_ALT_MD=farside.link/scribe\n#Environment=WHOOGLE_ALT_TL=farside.link/lingva\n#Environment=WHOOGLE_ALT_IMG=farside.link/rimgo\n#Environment=WHOOGLE_ALT_WIKI=farside.link/wikiless\n#Environment=WHOOGLE_ALT_IMDB=farside.link/libremdb\n#Environment=WHOOGLE_ALT_QUORA=farside.link/quetre\n#Environment=WHOOGLE_ALT_SO=farside.link/anonymousoverflow\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=/whoogle.env\nType=simple\nUser=\n# If installed as a package, add:\nExecStart=/python3 /whoogle-search --host 127.0.0.1 --port 5000\n# For example:\n# ExecStart=/usr/bin/python3 /home/my_username/.local/bin/whoogle-search --host 127.0.0.1 --port 5000\n# Otherwise if running the app from source, add:\nExecStart=/run\n# For example:\n# ExecStart=/var/www/whoogle-search/run\nWorkingDirectory=\nExecReload=/bin/kill -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 /var/lib/tor`\n 2. `chmod tor:whoogle /var/lib/tor/control_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/tor/control.conf](misc/tor/control.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/macOS).\n2. Clone and deploy the docker app using a method below:\n\n#### Docker CLI\n\nThrough Docker Hub:\n```bash\ndocker pull benbusby/whoogle-search\ndocker run --publish 5000:5000 --detach --name whoogle-search benbusby/whoogle-search:latest\n```\n\nor with docker-compose:\n\n```bash\ngit clone https://github.com/benbusby/whoogle-search.git\ncd whoogle-search\ndocker-compose up\n```\n\nor by building yourself:\n\n```bash\ngit clone https://github.com/benbusby/whoogle-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://devcenter.heroku.com/articles/heroku-cli)\n```bash\nheroku login\nheroku container:login\ngit clone https://github.com/benbusby/whoogle-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://github.com/benbusby/whoogle-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://aur.archlinux.org/packages/whoogle-git/), as well as a pre-built and daily updated package available at [Chaotic-AUR](https://chaotic.cx).\n\n___\n\n### Helm chart for Kubernetes\nTo use the Kubernetes Helm Chart:\n1. Ensure you have [Helm](https://helm.sh/docs/intro/install/) `>=3.0.0` installed\n2. Clone this repository\n3. Update [charts/whoogle/values.yaml](./charts/whoogle/values.yaml) as desired\n4. Run `helm upgrade --install whoogle ./charts/whoogle`\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://rollout.io/blog/the-shortlist-of-docker-hosting/), 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://www.digitalocean.com/pricing/) or [Linode](https://www.linode.com/pricing/), 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://letsencrypt.org/getting-started/))\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/run`: Add `--env-file ./whoogle.env` to your command\n\n| Variable | Description |\n| -------------------- | ----------------------------------------------------------------------------------------- |\n| WHOOGLE_URL_PREFIX | The URL prefix to use for the whoogle instance (i.e. \"/whoogle\") |\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 Opera UAs. |\n| WHOOGLE_USER_AGENT_MOBILE | The mobile user agent to use when using 'env_conf' option. Leave empty to use auto-generated Opera 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://github.com/benbusby/whoogle-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/search 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/disable 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: ./misc/tor/control.conf WHOOGLE_TOR_PASS must be 1 for this to work.|\n| WHOOGLE_SHOW_FAVICONS | Show/hide favicons next to search result URLs. Default on. |\n| WHOOGLE_UPDATE_CHECK | Enable/disable 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://duckduckgo.com/?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/2 for upstream requests (via httpx). Default on — set to 0 to force HTTP/1.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/rebuilding 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:///`) |\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/Videos 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://programmablesearchengine.google.com/controlpanel/all)\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://console.cloud.google.com/)\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/day | $0 |\n| Paid | Up to 10,000/day | $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/day)\n2. **Set a billing budget alert**: [Billing → Budgets & Alerts](https://console.cloud.google.com/billing/budgets)\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/day 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