SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Route SearXNG engine requests via a proxy

Send SearXNG outgoing engine requests through a proxy or Tor: the outgoing settings.yml block, per engine networks, timeouts, and when it makes results worse.

What routing SearXNG engine requests through a proxy changes

Routing SearXNG engine requests through a proxy changes one thing: the IP address an engine sees when your instance queries it. Your users still reach your VPS directly. Your VPS still builds the results page. Only the outgoing hop moves, from your server's own address to whatever address the proxy exits from.

That is the right fix when engines are refusing your server. It is the wrong fix when the problem is traffic arriving at your instance. The two problems look different in the logs and they live in different config files, so the first job is telling them apart.

Which direction is your problem, inbound or outbound?

Your instance sits between two flows. Inbound is a browser asking your instance for a search page. Outbound is your instance asking Google, Brave or Startpage for results. A proxy in the outgoing: block touches the second flow only.

Outbound trouble looks like this: a search returns, but one engine is missing and the page shows an error for it. Visit /stats/errors and you see rows naming SearxEngineCaptchaException or SearxEngineTooManyRequestsException. The engine then vanishes from results for a while: an hour after a captcha and three minutes after a too-many-requests error, with the shipped defaults. That is an engine refusing your server's IP, and it is what this guide is about. If those errors are your symptom, read why individual engines return captcha errors first, because a proxy is one answer there and often not the cheapest one.

Inbound trouble looks different: your own users get 429 Too Many Requests from your instance. If the limiter generated that response, no outgoing proxy setting will change it. A 429 on /image can instead be an upstream server's response forwarded by SearXNG, so check which request failed before changing the limiter. For limiter errors, go to the inbound rate limit and 429 post instead, or straight to limiter.toml and the Valkey connection it needs if you already know the limiter is the cause.

Where the outgoing block lives in settings.yml

Everything below goes in your admin settings file, /etc/searxng/settings.yml. With the official container image that path is a bind mount, ./core-config/ on the host in the upstream compose file. The file starts with use_default_settings: true, which means SearXNG loads its own defaults and your file only overrides parts of them.

The upstream default block is short:

outgoing:
  # default timeout in seconds, can be override by engine
  request_timeout: 3.0
  # the maximum timeout in seconds
  # max_request_timeout: 10.0
  useragent_suffix: ""
  # The maximum number of concurrent connections that may be established.
  pool_connections: 100
  # Enables the use of HTTP2
  enable_http2: true

The other keys you can add, with the defaults SearXNG's settings schema in the source code gives them (checked October 27, 2026): proxies (unset), using_tor_proxy (false), extra_proxy_timeout (0), retries (0), max_redirects (30), source_ips (unset), verify (true), and networks (empty). The outgoing settings page in the official docs says less than the code does. It never mentions networks and gives no default for retries. It also still prints request_timeout: 2.0, while the shipped file and the schema both use 3.0. Older guides also mention pool_maxsize and keepalive_expiry. Those are gone. SearXNG's HTTP client is now curl_cffi (pinned at 0.17.0 as of November 3, 2026). Directly under outgoing:, keys that are not in the current schema simply do nothing. Inside a named network they are not ignored: they stop SearXNG at startup, as the section on per-engine networks explains.

One useful side effect of that client change: SOCKS proxy support comes from libcurl and is already installed. You do not need to add httpx[socks] or any other Python package.

Route every SearXNG engine request through one proxy

Test the proxy from the machine SearXNG runs on before you touch any config.

curl -sS --max-time 20 --proxy http://10.10.0.5:3128 https://check.torproject.org/api/ip

SearXNG uses this endpoint's IsTor field for its own Tor check. If curl cannot reach the proxy, SearXNG will not either, and you have saved yourself an hour of reading engine errors.

Now the config:

use_default_settings: true
outgoing:
  request_timeout: 3.0
  proxies:
    all://:
      - http://10.10.0.5:3128

The key under proxies is a URL scheme pattern. all:// covers every outgoing request. You can narrow it with http:// and https:// keys if you want them treated differently, which is rare. The value is a list, and more than one entry is distributed round robin across requests.

Proxy URLs may use http, https, socks4, socks5 or socks5h. The h in socks5h means the proxy resolves the hostname. Without it, SearXNG resolves the name locally and sends the proxy an IP address, so your DNS (domain name system) queries still leave from your VPS and still name every engine you talk to.

Restart SearXNG so it re-reads the file. With the upstream compose file the service is named core:

docker compose ps
docker compose restart core

Older compose files name that service searxng, which is why the ps line comes first. On a source install, restart the uwsgi service that loads SearXNG. Then run one search and open /stats/errors. An empty page is what a healthy instance looks like.

Send only some engines through the proxy

A global proxy is a blunt instrument. It slows down the engines that were working fine. Named networks are the better tool: define one under outgoing.networks, then point individual engines at it by name.

use_default_settings: true
outgoing:
  request_timeout: 3.0
  networks:
    viaproxy:
      proxies:
        all://:
          - http://10.10.0.5:3128
      retries: 1
engines:
  - name: brave
    network: viaproxy
    timeout: 6.0
  - name: startpage
    network: viaproxy
    timeout: 6.0

This works because of the merge rule. With use_default_settings: true, entries in your engines: list are merged into the shipped engine definitions by name, so the two blocks above change two engines and leave the other two hundred alone. Get the name wrong and you have quietly defined a new engine that does nothing.

The network: value can also be the name of another engine, which makes that engine share the same client and connection pool. Two presets exist, ipv4 and ipv6. They only set the local address (0.0.0.0 or ::) and inherit everything else from the outgoing: block, so if you configured a global proxy or Tor there, an engine on network: ipv4 still goes through it. On an instance without a global proxy they are worth trying before a proxy: some engines treat a v6 address from a hosting range worse than the v4 address on the same box, and network: ipv4 costs nothing to test.

One sharp edge: a network: name that does not exist is not caught by a friendly settings check. Copy the name from the networks: block rather than typing it twice.

A second one: every key inside a named network is passed straight to SearXNG's network constructor, and a key it does not know, extra_proxy_timeout included, stops the instance at startup with a TypeError. The same goes for leftovers from older guides such as pool_maxsize or keepalive_expiry. That is why the extra time in the example sits on each engine as timeout: rather than on the network.

Use Tor as the outgoing path

SearXNG has direct support for Tor, and it verifies the setup rather than trusting you. Install the daemon first:

sudo apt update && sudo apt install -y tor
sudo systemctl enable --now tor
ss -lnt | grep 9050

ss should print a listener on 127.0.0.1:9050. Confirm it is really Tor before SearXNG asks the same question:

curl -sS --max-time 30 -x socks5h://127.0.0.1:9050 https://check.torproject.org/api/ip

A healthy answer contains "IsTor":true. Then configure it:

use_default_settings: true
outgoing:
  using_tor_proxy: true
  extra_proxy_timeout: 10
  proxies:
    all://:
      - socks5h://127.0.0.1:9050

This is the one place extra_proxy_timeout does anything. SearXNG adds it to an engine's timeout only when Tor is in use and that engine has an onion address, so it gives the onion engines room for a slow circuit. Clearnet engines reached over Tor keep their normal timeout unless you give them their own timeout:.

When using_tor_proxy is true, SearXNG requests https://check.torproject.org/api/ip through your proxy and reads the IsTor field. If that comes back false during the startup network check, SearXNG logs:

Network configuration problem: not using Tor

There is a second way to trigger that message, and it surprises people. The check first tests the proxy URLs as text. It looks at the combination SearXNG has just picked from your lists, one URL per scheme pattern, and returns false unless every URL in that combination starts with socks5h://. Write socks5://127.0.0.1:9050 and SearXNG refuses to proceed, even though a real Tor daemon is listening on the other end. The scheme string is part of the contract. Startup calls searx.search.initialize(check_network=True, enable_metrics=metrics), which checks Tor networks and advances their proxy cycles before searches begin. A later socks5:// entry can therefore fail on the first search request, or during startup when networks are shared. Check every entry yourself rather than trusting a first successful search.

In Docker there is a third trap. On a bridge network, which is what the upstream compose file gives you, 127.0.0.1 inside the container is the container itself, not your VPS, so a Tor daemon listening on the host's loopback is unreachable. With using_tor_proxy enabled, the startup network check fails and raises RuntimeError("Invalid network configuration"), preventing the application from starting. Host networking is the exception: Docker documents that such a container shares the host's networking namespace, so 127.0.0.1:9050 then reaches the host's Tor. Otherwise, run Tor as a second compose service and use socks5h://tor:9050, or bind its SocksPort to an address the container can reach. The general setup is covered in sending a VPS's outbound traffic over Tor, including the part where the Tor daemon itself must be able to bootstrap.

Be clear about what Tor buys you here. Exit node addresses are published in a list that anyone can download, and traffic from users sharing an exit address triggers automated abuse checks. Expect more captchas on mainstream engines, not fewer. Tor is worth configuring when you want the onion engines, which cannot be reached any other way, or when hiding your instance's address from engines matters more than result coverage.

Timeouts and retries when a proxy is in the path

A proxy adds a hop, so a request that used to take 400 ms may now take 1.5 seconds. The default request_timeout is 3.0 seconds, which leaves very little room. Despite its name, extra_proxy_timeout does not widen that budget for proxied engines. SearXNG adds it only to onion engines when Tor is in use, so setting proxies: alone never raises any engine's timeout, whatever value you give it.

The tool that works is a per-engine timeout:, which wins over the global value, so a slow engine behind the proxy can get its own number without slowing everything down. max_request_timeout is unset by default, and it does not act on a preference, because SearXNG has no timeout preference. A user can only ask for a different deadline inside the search itself: a query prefix such as <3 (three seconds; values of 100 or more are read as milliseconds, so <850 means 850 ms) or a timeout_limit request parameter. When max_request_timeout is set, it caps that requested value.

retries defaults to 0. Set it to 1 and a request error gets one configured retry, taking the next proxy or source IP from your lists. The first connection error also gets a retry with a new HTTP client without consuming that allowance, allowing up to three attempts with retries: 1 or two with retries: 0. An HTTP error answer depends on the status. An ordinary error status, such as a plain 503, makes SearXNG raise curl_cffi's HTTPError, which the retry loop catches like any other request error, so with retries: 1 it is retried through the next proxy even though networks default to retry_on_http_error: False. A 429, a 402 or 403, or a page SearXNG recognises as a captcha raises one of SearXNG's own engine exceptions instead. The retry loop does not catch those, so the engine is suspended and no retry happens. To retry those statuses you need retry_on_http_error, which marks the response as failed before SearXNG raises anything, and which still needs retries above 0. That option can be set directly on an engine that has no network: key, or inside a named network under outgoing.networks, where it takes true for any status from 400 to 599, a list of status codes, or a single code. The outgoing settings page in the docs describes retries as a retry "in case of an HTTP error", which matches the code for ordinary error statuses but not for 429, 402, 403 or a detected captcha unless retry_on_http_error covers them. Listing more than one proxy pays off even without retries: SearXNG hands out the entries in a proxy list round robin on every request, so the list rotates even with retries: 0. Do not set retries higher. A search waits for its slowest engine, but only up to the search's own deadline. Without a query timeout, that deadline is the largest timeout: among the engines queried, capped by max_request_timeout when that is set. A query timeout without a global cap can only shorten that deadline; with both set, the deadline is the smaller of the query timeout and the global cap. Retries have to fit inside that deadline rather than adding to it. Giving one engine a 6 second timeout does not cap the search at 6 seconds: if another engine selected for the same search has a longer timeout:, the search waits up to that longer value unless a global cap or query timeout shortens the deadline. A global cap or query timeout can limit the search to 6 seconds or less even when selected engines have longer timeouts. An engine still busy retrying when time runs out is dropped from the page and listed as unresponsive with a timeout. A big retry budget buys you more of those, not slower pages.

Remember that the outgoing network carries more than engine queries. The image proxy and favicon fetches use it too, so a slow proxy shows up as thumbnails that appear late on a page that otherwise rendered fine.

How to tell whether the proxy actually helped

Do not trust a feeling that results look better. Use your instance's own error counters, and change one thing at a time.

The counters behind /stats/errors live in the SearXNG process, not in Valkey, and they need enable_metrics: true under general:, which is the default. Because they are in-process, restarting SearXNG resets them to zero. That is what makes a clean before-and-after possible.

  1. Restart SearXNG.
  2. Run the same fixed list of at least twenty queries, through the same engines, in one sitting.
  3. Open /stats/errors and write down the exception class name and the percentage for each engine.
  4. Change exactly one thing in outgoing:, restart, and run the identical query list again.
  5. Compare the same engine's rows against its own earlier rows.

The restart matters more than it looks. A captcha suspends the engine for 3600 seconds (one hour) by default, and a too-many-requests error suspends it for 180 seconds. Those are the values in the settings.yml that ships with SearXNG, which is the file use_default_settings: true loads (checked October 27, 2026). The search settings page in the docs, and the fallback built into the code, give 86400 seconds for captchas and 3600 for too-many-requests instead. Those larger values only take effect when the corresponding suspended_times entries are missing from the loaded settings, for example in a standalone settings.yml written without use_default_settings. Both are tunable under search.suspended_times. So the first captcha in a run removes that engine from every later query in the run, and your error percentage ends up measuring one failure rather than twenty. A restart clears the suspension along with the counters.

Ordinary failures behave differently again. Their suspension uses the smaller of ban_time_on_fail: 5 seconds and max_ban_time_on_fail: 120, without growing after repeated failures, so a flaky engine recovers on its own during a test run and a captcha-blocked one does not.

One detail about the numbers on that page: the percentage is rounded into five point steps against the number of searches sent to that engine. With six queries it tells you almost nothing. With twenty or more it becomes readable. And compare an engine only against itself, never against a different engine, because their captcha thresholds have nothing to do with each other.

What gets worse when you add a proxy

This change has real costs, and for some instances it is a downgrade.

  • Shared proxy pools carry other people's history. A commercial datacentre proxy has been seen by every engine thousands of times already, while your plain VPS address may be comparatively unknown. Moving can raise your captcha rate.
  • Trust moves rather than disappearing. The proxy operator sees which engines you query and when. TLS (transport layer security) keeps the query text private, but with socks5h the proxy also performs your DNS lookups, so the destination list is fully visible to it.
  • Every outbound fetch pays the latency, including image proxy requests that a user is waiting on.
  • Free proxy lists are not an option for this. An untrusted middle box that terminates or rewrites traffic is a worse position than the one you started in.

Before paying for any of this, prune. Half of a busy /stats/errors page is usually engines that were never going to work from a datacentre address, and deciding which engines to keep enabled removes the noise for free. A hardened instance also gets scraped less, which reduces the outbound volume that triggers blocks in the first place, so closing a public instance down to real users is worth doing first.

Failure modes, with the strings you will see

Every engine fails immediately after you add proxies. Not captchas, connection errors, and they arrive faster than a normal search. SearXNG cannot reach the proxy address. In a container on a bridge network, 127.0.0.1 is the container itself. With using_tor_proxy enabled, an unreachable proxy prevents startup instead. Test with curl --proxy from inside the same context SearXNG runs in.

Network configuration problem: not using Tor. A proxy URL in the combination picked for a startup check or request does not start with socks5h://, or the check request to check.torproject.org completed and reported that the proxy is not Tor. If the check request could not complete, SearXNG reports the underlying request error instead. A failed startup check ends with RuntimeError("Invalid network configuration").

An engine that used to work now times out. The proxy hop pushed it past request_timeout. Give that engine its own timeout:. Adding extra_proxy_timeout will not help, because SearXNG applies it only to onion engines under Tor. If the same engine was timing out before the proxy existed, the proxy is not your problem and engine timeouts and KeyError failures covers what is.

The captcha rate is unchanged. The exit address still triggers the engine's abuse checks, or the engine is identifying your instance by request headers, TLS fingerprint, or query patterns that do not look like a browser. Changing the exit IP cannot fix those other signals, and more proxies will not either.

Nothing changed at all after editing the file. Either SearXNG was not restarted, or your engines: entry has a name that does not match a shipped engine. Check /config, which lists the engines the running process actually loaded.

FAQ

Will a proxy stop SearXNG captcha errors?

Sometimes, and sometimes it makes them worse. A captcha means the engine decided your requests are automated, and the exit IP is only one of the signals behind that decision. Tor exit addresses are published, and traffic from other users sharing a proxy or Tor exit address also triggers abuse checks. Measure it on your own instance with /stats/errors before and after, using the same queries and a restart between runs, rather than assuming a direction.

What is the difference between socks5:// and socks5h:// in SearXNG?

With socks5h:// the proxy resolves hostnames. With socks5:// SearXNG resolves them locally and sends the proxy an IP, so your DNS queries still leave from your server and still reveal every engine you contact. There is a second reason to prefer the h form: when using_tor_proxy: true is set, SearXNG checks as text the proxy URLs it picks from your lists and refuses to send requests through any combination in which a URL does not start with socks5h://, which produces the error Network configuration problem: not using Tor even against a working Tor daemon.

Can I route only one engine through the proxy?

Yes. Define a named network under outgoing.networks, then add an entry to engines: with that engine's exact name and a network: key pointing at it. With use_default_settings: true, engine entries are merged into the defaults by name, so only the engines you list are affected. The network: value can also name another engine, which makes both share one client. The presets ipv4 and ipv6 only pick the local address family; they still use any proxy or Tor setting from the global outgoing: block.

My users get 429 from my own instance. Does a proxy help?

It depends on where the 429 comes from. The limiter controls requests arriving at SearXNG, and an outgoing proxy does not change its decisions. But SearXNG's image proxy also forwards upstream error statuses, including 429, to your users. Check the failed request: if /image is forwarding an upstream 429, the outgoing proxy affects that fetch, though changing the exit address does not guarantee the upstream server will accept it. If the limiter is the cause, fix the limiter configuration and its Valkey connection instead.

Was this article useful?