Whoogle Search

Whoogle was designed as a privacy-focused Google search proxy. Its primary goal was to provide Google search results without ads, tracking, or JavaScript-heavy interference.

Key historical features included:

• Privacy: No ads, no third-party cookies, no tracking of personal IP addresses (when using proxies/Tor), and no URL tracking tags (e.g., utm=%s).
• Clean Results: No AMP links and no referrer headers.
• Search Capabilities: Autocomplete/suggestions, DDG-style 'bangs' (e.g., !<tag> <query>), and user-defined custom bangs.
• User Experience: Light/Dark/System themes, support for Tor and HTTP/SOCKS proxies, and JSON output for results via content negotiation.
• Advanced User-Agent Management: Auto-generated Safari User-Agents with random rotation to avoid detection patterns.
• Mobile Features: Full-resolution image viewing without site redirects (mobile only).

You can provide a custom list of User Agent (UA) strings for Whoogle to use instead of its auto-generated Safari strings.

Setup

1. Create a text file with one UA string per line:

Safari/9.80 (J2ME/MIDP; Safari Mini/4.2.13337/22.478; U; en) Presto/2.4.15 Version/10.00
Safari/9.80 (Android; Linux; Safari Mobi/498; U; en) Presto/2.12.423 Version/10.1

2. Set the WHOOGLE_UA_LIST_FILE environment variable to the path of your file.

Environment Variable Examples:

• Docker: docker run -e WHOOGLE_UA_LIST_FILE=/config/my_user_agents.txt ...
• Docker Compose:

  environment:
    - WHOOGLE_UA_LIST_FILE=/config/my_user_agents.txt

• Manual/systemd: export WHOOGLE_UA_LIST_FILE=/path/to/my_user_agents.txt

Priority Order

Whoogle loads UAs in this order:

1. Custom UA list file (if WHOOGLE_UA_LIST_FILE is set and valid)
2. Cached auto-generated UAs (if cache exists and is valid)
3. Newly generated UAs (if no cache or cache expired)

Recommended Workflow

To generate a high-quality list of working User Agents:

# 1. Generate 100 UAs and discard stderr
python misc/generate_uas.py 100 2>/dev/null > candidate_uas.txt

# 2. Filter for working UAs
python misc/check_google_user_agents.py candidate_uas.txt --output working_uas.txt

# 3. Use the working UAs
export WHOOGLE_UA_LIST_FILE=./working_uas.txt
./run

# Generate and test UAs, save working ones
python misc/generate_uas.py 100 2>/dev/null > candidate_uas.txt
python misc/check_google_user_agents.py candidate_uas.txt --output working_uas.txt

# Use the working UAs with Whoogle
export WHOOGLE_UA_LIST_FILE=./working_uas.txt
./run

To use Whoogle directly from your browser's address bar, you must add it as a search engine.

Important: If using a reverse proxy, ensure the Root URL config option on the Whoogle home page is set to your public URL before proceeding.

Browser-specific instructions:

• Firefox (Desktop):

  • Version 89+: Navigate to your Whoogle URL, right-click the address bar, and select "Add Search Engine".
  • Older versions: Navigate to your URL, click the 3-dot menu in the address bar, and select "Add Search Engine".
  • After adding, go to Firefox Preferences > Search and select "Whoogle" from the dropdown.
  • Note: If using Firefox Containers, follow the Firefox Containers guide.

• Firefox (iOS):

  • Go to Settings > Search. Tap "Add Search Engine".
  • Title: Whoogle
  • URL: http[s]://<your whoogle url>/search?q=%s

• Firefox (Android):

  • Version < 79.0.0: Navigate to your URL, long-press the search field, select "Add Search Engine", name it, then set it as default in Settings > Search.
  • Version >= 79.0.0: Go to Settings > Search > Add search engine. Select 'Other'.
    • Name: Whoogle
    • Search string: https://<your whoogle url>/search?q=%s

• Alfred (macOS):

  • Go to Alfred Preferences > Features > Web Search > Add Custom Search.
  • Search URL: https://<your whoogle url>/search?q={query}
  • Title: Whoogle for '{query}'
  • Keyword: whoogle
  • In Default Results, click Setup fallback results, add Whoogle, and drag it to the top.

• Chrome/Chromium-based Browsers:

  • Automatic: Visit your Whoogle home page; it may add itself automatically if requirements are met.
  • Manual: Go to Search engines > Manage search engines > Add. Use the format <whoogle url>/search?q=%s.

To route Whoogle requests through Tor, you must configure Tor to allow control connections and then configure Whoogle to use them. You can use either Cookie or Password authentication.

Method 1: Cookie Authentication

1. Update your torrc with:

   ControlPort 9051
   CookieAuthentication 1
   DataDirectoryGroupReadable 1
   CookieAuthFileGroupReadable 1

2. Set permissions so the Whoogle user can read the Tor directory:

   chmod tor:whoogle /var/lib/tor
   chmod tor:whoogle /var/lib/tor/control_auth_cookie

3. Restart Tor: systemctl restart tor.
4. Set the environment variable WHOOGLE_CONFIG_TOR=1.

Method 2: Password Authentication

1. Generate a hashed password:

   tor --hash-password {Your Password Here}

2. Update your torrc with:

   ControlPort 9051
   HashedControlPassword {Output from previous step}

3. Place your plain-text password in misc/tor/control.conf within the Whoogle directory.
4. Restrict access to the password file: chmod 400 control.conf.
5. Set environment variables: WHOOGLE_CONFIG_TOR=1 and WHOOGLE_TOR_USE_PASS=1.

The misc/check_google_user_agents.py tool verifies which User Agent (UA) strings successfully return Google search results without triggering blocks, JavaScript-only pages, or browser upgrade prompts. It supports incremental saving, duplicate detection, and random query cycling to simulate realistic usage.

CLI Options

• --output <file>: Save working UAs to a file (appends incrementally).
• --query <string>: Use a specific search query instead of random cycling.
• --verbose: Show detailed results.
• --delay <seconds>: Adjust delay between requests (default: 0.5).
• --timeout <seconds>: Set request timeout (default: 10).

# Test all UAs from a file
python misc/check_google_user_agents.py UAs.txt

# Save working UAs to a file (appends incrementally)
python misc/check_google_user_agents.py UAs.txt --output working_uas.txt

# Use a specific search query
python misc/check_google_user_agents.py UAs.txt --query "python programming"

# Verbose mode to see detailed results
python misc/check_google_user_agents.py UAs.txt --output working.txt --verbose

# Adjust delay between requests (default: 0.5 seconds)
python misc/check_google_user_agents.py UAs.txt --delay 1.0

# Set request timeout (default: 10 seconds)
python misc/check_google_user_agents.py UAs.txt --timeout 15.0