How to Use SearXNG: The Beginner's Guide (First Search, First Self-Host, Engines, and the Stay-Private Rule)

CodexFuse Team · 2026-10-31T05:58:55.739Z · 15 min read

Learn how to use SearXNG: try a public instance, self-host a private metasearch engine with Docker, tune engines, set it as your browser default, and wire it into Open WebUI.

How to Use SearXNG: The Beginner's Guide (First Search, First Self-Host, Engines, and the Stay-Private Rule)

Learning how to use SearXNG is the simplest way to stop handing your search history to a big search engine. SearXNG is a privacy-respecting metasearch engine: it has no index of its own, so it sends your query to dozens of public search engines — Google, Bing, DuckDuckGo, Wikipedia, and over 70 others — then merges the results and strips the tracking before anything reaches you. Your IP address and your query history never land in any commercial profile, because the upstream engines only ever see your server, not you.

This beginner's guide runs the full arc in one page: try SearXNG on a public instance in sixty seconds, then self-host it properly with Docker, generate the secret key the right way, tune the engines, set it as your browser's default search, and wire it into a private AI chat stack. If you are building the fully private setup, pair this with the Open WebUI self-host guide — Open WebUI uses a SearXNG backend for live web search inside your chats.

What Is the Fastest Way to Use SearXNG?

Try a public instance first — you can run your first search within a minute and decide whether self-hosting is worth your time. Public instances are volunteer-run and listed on searx.space, the community directory. Use one for testing; self-host for daily use.

1. Open the public-instance directory. Visit searx.space and pick an instance near your region with a green status — a closer instance means faster searches and fewer blocked engines.
2. Run your first search. Type a normal query, something you would type into Google. Notice there is no login, no cookie banner, and no ad slots at the top — that is the entire business model difference.
3. Open Preferences and look at the Engines tab. This shows which engines answered your query and which returned errors. Engines with warnings are usually being rate-limited on the shared server IP — this is normal on public instances and is one of the reasons to self-host.
4. Test the category tabs. Switch between general, images, news, and videos. Each category fans out to different engine sets, so image search and news search behave like separate tools.
5. Decide whether to self-host. If you like the results, your next step is your own instance: you control the engines, the settings, and the privacy guarantees, and nobody's rate limits are yours.
6. Make the browser-default decision. Even on a public instance you can add SearXNG as a browser search engine right now (covered below) — and point it at your own instance the moment it exists.

What Do You Need Before Self-Hosting SearXNG?

Self-hosting SearXNG needs less hardware than almost anything else you will run on your server. The official documentation and independent guides agree on the requirements: Docker and Docker Compose, 256 MB of RAM as an absolute minimum (512 MB recommended, plus another 50–100 MB when the Valkey cache is running), a single CPU core, and about 1 GB of disk. A small what is VPS hosting server handles it with room to spare — SearXNG is I/O-bound, waiting on upstream engines, not CPU-bound.

You should already be comfortable with the command line and with Docker basics. If the Compose file below feels unfamiliar, read our Docker beginner guide first and come back — every step here assumes you can run docker compose up -d without supervision.

How Do You Self-Host SearXNG with Docker?

The official install method changed in 2026: the old searxng-docker repository is being retired, and the compose template now ships inside the main SearXNG repository. Fetch it from there, not from old tutorials that still clone the legacy repo.

Step 1. Fetch the official compose template. Create a directory and download the compose file and environment template from the project's current documentation source:

mkdir -p ~/searxng/core-config/
cd ~/searxng/
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
cp -i .env.example .env

The compose file defines two services. The core service runs docker.io/searxng/searxng:${SEARXNG_VERSION:-latest} and mounts your configuration at ./core-config/:/etc/searxng/. The valkey service runs the Valkey key-value store, which powers caching and the rate limiter.

Step 2. Generate a secret key before first launch. The settings template warns you to change the default secret — a shared default key means anyone can forge sessions. Generate a real one:

openssl rand -hex 32

Put the output in your core-config/settings.yml as server.secret_key. This is the single most important line in the whole setup, and it must happen before the instance is reachable by anyone but you.

Step 3. Set your base URL. The server.base_url in settings.yml must be the URL you will actually reach the instance at — the documentation's example http://example.org/location is a placeholder, not a value. For a local test, http://localhost:8080/ works.

Step 4. Start the stack.

docker compose up -d

Step 5. Confirm it answers. Open http://your-server-ip:8080 — no setup wizard, no account. Search and go. The /healthz endpoint is there if you want a health check.

SearXNG uses rolling releases with dated image tags like 2026.10.17-*, and unlike most projects, :latest is the intended deployment tag here — pin a dated tag when you want reproducibility. If Docker Hub rate-limits your pulls, the official images are mirrored on the GitHub Container Registry.

Which Settings Matter Most in settings.yml?

Your settings.yml starts from the defaults with use_default_settings: true, and you override only what you need. These are the settings a beginner should understand first — each one is a real privacy or behavior lever, not decoration:

Restart the container after any settings change — SearXNG reads settings.yml at startup, and edits do nothing until docker compose restart runs.

How Do You Enable and Disable Search Engines?

Engine tuning is where your instance stops being generic and starts being yours. The use_default_settings: true line loads all default engines; you then selectively switch individual engines on or off in the same file. A beginner override block looks like this:

use_default_settings: true
engines:
  # Disable Bing
  - name: bing
    disabled: true
  # Disable Yahoo
  - name: yahoo
    disabled: true
  # Enable an engine that ships off by default
  - name: brave
    disabled: false

Engines are grouped by category — general, images, videos, news, maps, music, IT, science, files, and social media — and the full engine list lives in the official documentation. A few useful defaults to know: google is enabled by default and usually gives the best general results; duckduckgo and wikipedia are enabled by default; brave is privacy-focused but ships disabled; reddit is the community-answers lane; arxiv covers academic papers; github covers code and repository search.

Users can also toggle engines per-search from the Preferences page in the web UI — but those toggles live in a browser cookie, not in settings.yml, so they follow the browser, not the server. The Preferences Engines tab is also your diagnostic screen: if searches work but some engines always return errors, the tab shows which ones, and it usually means those engines are rate-limiting your server's IP — Google is the usual suspect on cloud-provider addresses. Enabling a mobile user-agent for that engine, or leaning on Brave and DuckDuckGo, is the standard fix.

How Do You Set SearXNG as Your Browser's Default Search?

Replace your browser's default engine so every address-bar query goes through your instance. Add a custom search engine with this search URL, swapping in your server's address:

http://your-server-ip:8080/search?q=%s

In Firefox you can skip the manual entry: visit your instance, right-click the search bar, and add it as a search engine directly, then promote it to default in Settings. The %s placeholder is what the browser replaces with your query — without it, the browser sends nothing and the instance just loads its homepage.

How Do You Use the SearXNG API?

SearXNG doubles as a search API for your own scripts and apps, which is how the private-AI-stack integrations consume it. First make sure json is in search.formats in settings.yml — the instance only serves HTML by default, and requests for other formats fail until you allow them. Then query it like this:

curl "http://localhost:8080/search?q=best+vps+2026&format=json" | head -c 600

The response is a JSON blob with titles, URLs, content snippets, and engine names for every result. The same endpoint also serves csv and rss formats once you enable them. Keep the API on the private network: an open SearXNG endpoint is an anonymous scraping proxy for anyone who finds it, so bind it to localhost or your internal Docker network and reach it through a reverse proxy only when you have a reason.

How Do You Wire SearXNG into Open WebUI?

This is the integration that turns a private chatbot into a private AI search assistant: Open WebUI sends the model's searches to your SearXNG instance instead of a commercial API. The wiring has exactly one gotcha, and it is the one most setups miss — the JSON format from the previous section.

Step 1. Enable JSON output in SearXNG. In core-config/settings.yml, add json to search.formats and restart. Without this step, Open WebUI's requests are rejected with a 403 Forbidden error.

Step 2. Point Open WebUI at SearXNG. In Open WebUI's environment (or its admin settings under Settings > Admin > Tools > Web Search), set these:

ENABLE_WEB_SEARCH=True
WEB_SEARCH_ENGINE=searxng
WEB_SEARCH_RESULT_COUNT=5
SEARXNG_QUERY_URL=http://searxng:8080/search?q=<query>

The query URL must contain ?q=<query> exactly — Open WebUI substitutes <query> with the actual search terms, and a URL missing that placeholder returns empty results.

Step 3. Verify the containers can talk. From inside the Open WebUI container, confirm it can reach SearXNG over the internal network:

docker exec -it open-webui curl "http://searxng:8080/search?q=test&format=json"

A JSON blob full of results means the connection works; a 403 means the JSON format is still off; a connection-refused means the containers are on different Docker networks.

Step 4. Test it in a chat. Open a new chat, toggle Web Search on for that conversation, and ask something time-sensitive — a recent release, a current event. The web-search toggle is per-session and resets when you reload, so re-enable it each time you want live sources.

This same wiring pattern works with other private-stack apps — our AnythingLLM beginner guide covers the document-chat side of the stack, where local models answer from your own files instead of the web.

What Is the Stay-Private Rule?

The stay-private rule is simple: keep your instance off the public internet unless you have a specific reason and the hardening to match. SearXNG has no built-in authentication — an open instance is an anonymous search proxy for the whole internet, and heavy public use gets your server IP rate-limited or CAPTCHA'd by upstream engines, which degrades your own searches. Run it on localhost or an internal Docker network, and put a reverse proxy with HTTPS in front only when remote access is genuinely needed.

Three settings choices carry the rest of the privacy load. Enable image_proxy so result thumbnails load through your server instead of making your browser connect to upstream image hosts. Consider server.method: POST so queries never appear in upstream URL logs — at the cost of some browser conveniences like reliable back-button behavior. And keep server.limiter on whenever the instance is reachable beyond your own machines, with limiter.toml configured, because the limiter is what stands between your server IP's reputation and the internet's bots.

SearXNG vs Whoogle: Which Private Search Should You Use?

Whoogle is the other self-hosted search tool beginners encounter — a Google-only proxy, while SearXNG is a true multi-engine metasearch. The comparison decides itself once you see the shape of each tool:

The practical answer: use SearXNG. Multi-engine aggregation is what makes private search reliable — when one engine blocks your server IP, the other seventy keep working, and that redundancy is the entire point of the metasearch design.

What Mistakes Do SearXNG Beginners Make?

These are the errors that show up in every community thread about first-time installs — each one is avoidable in under a minute once you know it exists:

Sources

• SearXNG official documentation — container installation (docs.searxng.org, build 2026.10.30, crawled 2026-10-31): compose template now fetched from searxng/searxng master container/, services searxng-core + searxng-valkey (valkey:9-alpine), ./core-config/:/etc/searxng/:Z mount, migration guide retiring searxng-docker, GHCR mirror, custom image ~271 MB.
• SearXNG official docker-compose.yml and .env.example (raw.githubusercontent.com/searxng/searxng/master/container/, crawled 2026-10-31): docker.io/searxng/searxng:${SEARXNG_VERSION:-latest}, dated tags like 2026.10.17-*, $SEARXNG_* environment variables.
• SearXNG official settings documentation — server: and search: (docs.searxng.org, crawled 2026-10-31): secret_key and base_url must be changed; limiter requires Valkey; public_instance activates bot-detection link_token and image_proxy; formats html/csv/json/rss; safe_search 0/1/2; ban_time_on_fail: 5 and engine suspension times.
• GTZHost — "How to Self-Host an AI Search Engine with Open WebUI + SearXNG" (crawled 2026-10-31): JSON format requirement and the 403 gotcha, SEARXNG_QUERY_URL=http://searxng:8080/search?q=<query>, ENABLE_WEB_SEARCH=True / WEB_SEARCH_ENGINE=searxng, in-container curl test, never expose publicly, per-session web-search toggle.
• selfhosting.sh — "How to Self-Host SearXNG with Docker Compose" (updated March 2026, crawled 2026-10-31): openssl rand -hex 32 secret generation, 70+ engines, engine enable/disable blocks with use_default_settings: true, browser default URL http://your-server-ip:8080/search?q=%s, Firefox right-click add, UI Preferences stored in cookie, method: POST privacy note, resources (256 MB min / 512 MB recommended, 1 GB disk), rolling-release tag note, Google IP rate-limit troubleshooting.

Frequently Asked Questions

Is SearXNG free to use and self-host?

Yes. SearXNG is free open-source software with no license fees and no search API costs — the upstream engines are queried the same way a browser would. Your only cost is the server it runs on, and it needs so little (256 MB RAM, 1 GB disk) that the cheapest VPS tier is overkill.

Does SearXNG really not track me?

Your SearXNG instance never profiles you — there are no accounts, no analytics, and no advertising. The upstream engines see queries coming from your server's IP, not from you, and with image_proxy on, your browser never touches them directly. It is not invisibility — it is the removal of the tracking profile.

Why do some engines return errors on my instance?

Search engines rate-limit or block known server IPs, especially on cloud providers — Google is the usual one. Check the Engines tab in Preferences to see which engines are failing. Enable a mobile user-agent for that engine in settings.yml, or lean on the other 70+ engines; the metasearch design exists precisely so one blocked engine does not matter.

Can I use SearXNG on my phone?

Yes — add your instance as a custom search engine in your mobile browser, or simply bookmark its URL. The web UI works fine on mobile. The catch is network reachability: your phone must reach the server, so a localhost-only instance will not work from your phone without a VPN or tunnel.

Is a public SearXNG instance as private as self-hosting?

No. Public instances hide you from the search engines, but the instance operator could theoretically see your queries — you are trusting a volunteer instead of Google. Public instances are for testing; daily use belongs on your own instance, where the only person who could see your queries is you.