Adding web search to Open WebUI with a self-hosted SearXNG instance
A team that wants chat answers grounded in current web results can avoid sending every query to a paid search API by pointing Open WebUI's built-in web search engine setting at a SearXNG search endpoint that the team runs itself. SearXNG is an open-source metasearch engine. It sends a query to a set of upstream search engines and returns aggregated results, so the search layer sits on infrastructure you control. Open WebUI's features documentation describes the web search capability, and the connection is configured in its admin settings. Confirm the exact setting names, the endpoint format and the output format that SearXNG must return against the current Open WebUI features documentation and the SearXNG settings reference before you publish or hand the steps to a client.
Several decisions shape the build before anyone edits a setting. First, decide where SearXNG runs. It must be reachable from the Open WebUI service over the internal network, and it should not be published to the internet unless you have a reason and controls for that. Second, check that the instance is configured to return results in the machine-readable format Open WebUI expects, because a default HTML-only setup will not work. Third, choose which upstream engines are enabled, since each has its own terms, rate limits and result quality. Fourth, plan for the fact that Open WebUI sends search requests on behalf of many users, so the SearXNG instance needs rate limiting, bot detection settings and logging sized to that load.
The main risks are data handling, access and reliability. Queries leave your environment through SearXNG to the upstream engines, so the security and privacy review must treat those engines as recipients of user prompts that were turned into search terms. Access also needs a deliberate policy. Open WebUI supports role-based access control with groups and per-resource permissions, so you can decide which groups may use web search in chat, and you should test that a user outside those groups cannot trigger it. Reliability depends on upstream engines that can slow down, block traffic or change behavior, so set timeouts and monitor response times from the first day.
Compared with hosted providers such as Brave or Tavily, a self-hosted SearXNG setup shifts cost from per-query fees to labor and infrastructure. Your team, or a partner you engage, pays for installation, configuration, patching, engine tuning and monitoring, and those costs recur. Hosted APIs usually bill per query and return structured results with vendor support. When you request a quote for a SearXNG build, ask for the written scope to cover the server and network design, the Open WebUI configuration, access testing, logging, and the upgrade process for both applications. Verify the result by running known queries, confirming that cited sources in answers match the results returned, and reviewing logs for failed requests.
What a SearXNG search backend needs before you connect it
Web search with SearXNG adds a service that Open WebUI depends on, so the platform team needs these inputs settled before any configuration begins. The six items below cover the Open WebUI release, network reachability, outbound access, transport security, ownership and multi-replica consistency. Confirm each one with the owner named in your change process.
Supported Open WebUI release
Confirm that the Open WebUI release you plan to run supports the web search feature before you change any configuration. The project publishes releases on its GitHub releases page, and the most recent entry there at the time of your check is v0.12.3, published October 16, 2026. Read the release notes for search-related changes, and record the exact version in your change ticket so upgrades and rollbacks can be traced later.
SearXNG reachable from every process
Every Open WebUI process that performs a search must open a connection to the SearXNG instance over the internal network. Open WebUI runs its searches on the server side, so user browsers do not need direct access to SearXNG. Test the path from each host or pod where Open WebUI runs, not only from an administrator workstation, and confirm that the JSON output format is enabled in the SearXNG settings, because Open WebUI needs machine-readable results.
Upstream engine path and egress
Decide how SearXNG reaches the upstream search engines it queries, and whether your network policy allows that outbound traffic. Common options include direct egress from the SearXNG host, an approved proxy, or a restricted set of engines. Ask your network team to confirm the permitted destinations and ports, and review which engines are enabled, since engine availability and blocking behavior change over time and affect result quality.
TLS for internal endpoints
Decide how traffic between Open WebUI and SearXNG is encrypted if it crosses a network segment you do not fully control. Plan the certificates, including who issues them, whether the chain includes your internal root certificate, and how each Open WebUI container or host trusts that root. Confirm the endpoint URL format Open WebUI expects, and test certificate renewal before go-live so connection errors do not appear for the first time in production.
Named owner for SearXNG configuration
Name one team and one accountable person for the SearXNG settings file, the engine list, rate limits, secrets and the container image. Without a named owner, changes to engines or upstream access tend to happen informally, and nobody can explain why results changed. Agree who approves configuration changes, how each change is tested against Open WebUI, and who responds when searches fail during business hours.
Matching search settings on every replica
Multi-replica Open WebUI deployments need the same web search configuration on every replica, so that users get consistent results no matter which replica serves a request. Set the search variables in your deployment manifests or shared environment so every replica reads identical values. The Redis and shared storage requirements in the scaling guide belong to the Open WebUI platform, so plan them as platform work items and keep the SearXNG setup in its own track.
Connecting Open WebUI to SearXNG, step by step
This sequence takes a self-hosted SearXNG instance from a reachable search endpoint to a tested web search feature in Open WebUI, with access limited to the groups you approve. Each step ends with a check you can record, so the rollout can be repeated and audited.
Deploy or confirm the SearXNG instance
Start or confirm a SearXNG instance that the Open WebUI host can reach over the network. Your platform or infrastructure team usually owns this, and the instance should run in infrastructure you control. Record its internal base URL, the version you run, and which upstream engines are enabled, because those choices shape result quality. Open the search page in a browser from a machine on the Open WebUI network segment. Done when the page loads there.
Enable the JSON output format
Open WebUI reads SearXNG results in JSON, so the instance must allow that output format in its search settings. Check the list of enabled formats in the SearXNG settings file or container configuration, add JSON if it is missing, and restart the service so the change takes effect. Confirm the exact setting name and file location in the current SearXNG documentation, since both can change between releases. Done when a search request asking for JSON returns structured results rather than an error or an HTML page.
Test the search endpoint from the host
Query the search endpoint from the same place Open WebUI runs, typically inside its container, so DNS names, proxies and firewall rules match what the application will see. Use a neutral query, request JSON, and inspect the response for result titles, URLs and snippets. Confirm the endpoint path and query parameter names in the current SearXNG documentation before you write them into any configuration. Done when the container receives a list of results that each include a URL. If the request fails, fix networking before changing Open WebUI settings.
Set the engine and endpoint in Open WebUI
Point Open WebUI at the SearXNG instance. Depending on how you installed it, this happens in the web search section of the admin settings or through environment variables passed at startup. Select SearXNG as the search engine, enter the internal endpoint URL in the format the current Open WebUI documentation specifies, and set any result count or timeout values your team agrees on. If you use environment variables, confirm their names in the features documentation and restart so they load. Done when the configuration saves without error and still holds after a restart.
Choose which groups may search
Decide which user groups may use web search before you open the feature to staff. Open WebUI's role-based access control lets administrators grant or limit features through groups, so create or select the group that will have access. Common choices include all staff, a pilot group, or only the teams with a clear need for public lookups. Record who approved the decision, because queries sent through SearXNG reach public search engines outside your network. Done when a test group has the permission and a group outside it cannot see the feature.
Run a test query and check citations
Sign in with an account from a permitted group and run a test query. Use an administrator account only as a control, since administrator accounts can see settings and features that regular users cannot. Ask a question that needs current public information and watch for the search step in the chat response. Confirm in the current version's documentation how citations appear. Done when results appear and the answer cites source URLs you can open. Record the account, query and time in your test log so the rollout can be repeated.
Which settings and data move between Open WebUI and SearXNG
This table maps each setting and data item that passes between Open WebUI and SearXNG, and which side holds it. Read the Open WebUI column for what you configure in the admin console or environment, and the SearXNG column for what the search instance must expose or keep. Confirm variable names and JSON output support against the release you deploy.
| Element | Open WebUI side | SearXNG side |
|---|---|---|
| Search engine selection | Admin web search setting set to SearXNG. Plain configuration. | Nothing to select. SearXNG serves whichever upstream engines its own settings enable. |
| Base URL and search path | Query URL template containing the query placeholder, usually an internal address. Plain configuration. | Listens on its own host and port and serves the search endpoint. Keep it reachable only from the Open WebUI host. |
| Query parameter sent | The user's search text, or a query the model rewrites, placed in the query parameter with JSON format requested. | Must have JSON output enabled in its settings, or requests from Open WebUI fail. Confirm for your version. |
| Result fields returned | Title, URL and snippet per result, converted into numbered sources that the answer cites. | Returns results from its enabled engines. Result count and engine mix depend on SearXNG configuration. |
| Access gate | Web search must be enabled globally and granted to the user's group. Role-based configuration. | No user identity. It sees requests only from the Open WebUI server address. |
| Secrets and credentials | Open WebUI needs no search API key for SearXNG. Treat any proxy or basic-auth credential as a secret. | The instance secret key is a secret. Any reverse proxy credential in front of search is also a secret. |
| Logs kept | Chat history stores answers and cited sources under your retention settings. Confirm what it records per search. | Access logs record request paths and may include query strings. Confirm logging level and retention in SearXNG. |
Hardening the SearXNG endpoint and controlling who can search
Web search adds a second network path and a second place where user prompts travel, so SearXNG needs the same scrutiny as the rest of the stack. The cards below cover placement, exposure, logging, egress, image maintenance and permissions, in the order most teams work through them during the build.
Keep SearXNG internal and limit callers
Run the SearXNG endpoint on the internal network with no public DNS record, load balancer or ingress route. Allow connections only from the Open WebUI service addresses, enforced at the network layer through security groups, firewall rules or Kubernetes network policies. Confirm that the Open WebUI replicas are the only permitted source, and test the rule from an unrelated host on the same network segment to make sure it fails as expected.
Avoid shared or public SearXNG instances
Public SearXNG instances are run by third parties, and their operators can see every query, the source address and timing. Using one for company work moves that visibility outside your control and may be rate limited or blocked without notice. Run your own instance for the company, and treat any instance that others can reach as a shared service that needs its own access, logging and data-handling decisions.
Decide what SearXNG logs and for how long
Set the logging level, log destination and retention period before go-live, and write them down. Access logs can reveal which users searched for what, so decide whether query text is recorded at all, who may read the logs, and when they are deleted. Align the choice with your privacy notice and records policy. Check that the settings still apply after an image update, because defaults can change between releases.
Control egress and the upstream data decision
SearXNG sends queries to upstream search engines, so search terms leave your organization even though the SearXNG host stays internal. Restrict outbound traffic from that host to the engines you approve and to the proxy or DNS services you run, and block everything else. Record which engines are enabled, what they receive, and whether your data-handling policy and contracts permit that transfer before users are onboarded.
Pin and patch the SearXNG image
Deploy a specific image tag or digest rather than a floating tag, so each change is deliberate and can be tested in staging first. Track security advisories for SearXNG and its base image, and set a documented schedule for applying patches. Scan the image before promotion, keep the previous known-good version available for rollback, and record which tag or digest is running in each environment.
Gate web search through roles and groups
Open WebUI uses role-based access control with groups and per-resource permissions, so web search can be granted to specific groups instead of every signed-in user. Map groups from your identity provider where SSO or SCIM provisioning is in place, and review who holds the permission after each group change. Confirm in a test account that users outside the approved groups cannot trigger web search from chat or through the API.
Verifying search results before users rely on them
The test plan should prove that web search works at three layers before any user relies on an answer: the SearXNG instance itself, the connection from Open WebUI, and the answers the model produces from search results. Start with direct requests to SearXNG, sent outside Open WebUI, using the same query format the integration uses. Confirm that the JSON output format is enabled, that the engines you chose return results, and that response times are acceptable from the network segment where Open WebUI runs. If these checks fail, later tests tell you little, so run them first and repeat them after any change to SearXNG settings, the engine list or the reverse proxy.
Next, build a fixed set of queries and record what each should return. Include current events, where results change daily, so expected results describe the shape of a good answer, for example recent reputable sources, rather than exact URLs. Include niche topics, such as a narrow technical subject your staff ask about, where results depend heavily on which engines are enabled. Include queries that should return nothing, such as an invented product name, and confirm that the model says it found no reliable source and does not invent one. For every query, record the expected categories of results and the upstream engines that answered. When an engine changes its behavior, these records make the change visible and let the team trace why answers shifted.
Citations need their own check, because a response can look sourced while pointing at pages the search step never returned. For each test query, open the saved chat and compare every citation with the search results stored for that turn. Confirm that each link leads to a source that was actually retrieved and that the claim beside it matches the snippet or page content. Then test access control. Sign in as a user outside the group allowed to use web search, and confirm that the search control is unavailable or refused by the server, not only hidden in the interface. Check the group and per-resource permissions in the admin settings for the version you run, and repeat the check through an API key if your deployment allows keys for chat.
Load testing should use several concurrent chat sessions that each trigger searches, and it should run on the same topology planned for production. If you plan multiple Open WebUI replicas, the shared state services and external database must be in place during the test, because a single-process setup hides the problems you are trying to find. Measure SearXNG response times, errors, any rate limiting from upstream engines, and end-to-end answer latency at the session count your expected peak requires. Finally, run the full fixed set and the permission and citation checks after every Open WebUI or SearXNG upgrade, compare results with the recorded expectations, and label each run with the versions tested. Ask any implementation partner to deliver this plan as a written, repeatable test suite.
Common failures when SearXNG search does not return results
This table lists the failure points that most often stop Open WebUI from getting results from SearXNG, with the likely cause and a check the team can run to confirm it. Work through the rows in order, because the first two failures block every query and the later ones only show up once requests reach SearXNG. Each fix should be confirmed in your own environment before you move to the next row.
| Failure | Likely cause | Fix and how to verify |
|---|---|---|
| Endpoint returns HTML instead of structured output | The JSON output format is not enabled in SearXNG's search formats, so requests with format=json fall back to or are refused as HTML pages. | Add json to the search formats in settings.yml, restart SearXNG, then request the search endpoint with format=json and confirm a JSON body. |
| Open WebUI cannot reach the SearXNG URL | The URL uses localhost or a host name that resolves only on the host, not inside the Open WebUI container network. | Use the SearXNG service name or a address reachable from the Open WebUI container. Run a request from inside that container with curl to confirm. |
| Empty results from upstream engines | Upstream search engines block or rate-limit the egress IP address of the SearXNG host, so each engine returns an error instead of hits. | Check engine error messages in the SearXNG instance, then reduce the enabled engines or route outbound requests through an approved egress path. Confirm results return for a test query. |
| Requests time out under load | Slow or failing engines hold each query open, and the Open WebUI timeout is shorter than the time SearXNG needs to gather results. | Disable slow engines, review the SearXNG worker and timeout settings, and align the Open WebUI timeout with them. Repeat a load test with concurrent queries to confirm. |
| Web search option missing for some users | The web search feature is enabled for a group the user is not in, or the user's role lacks the permission in Open WebUI's group settings. | In the Open WebUI admin settings, check the web search toggle and the permissions on the user's group. Sign in as a test user from that group to confirm the option appears. |
| Results are stale or off-topic | Engine selection, language, category or time-range settings do not match the questions users ask, or a cache serves older responses. | Review enabled engines, default language and categories in SearXNG, and adjust the cache lifetime if your SearXNG build exposes one. Compare results for a fixed set of test queries. |
| Replicas return different results after a partial change | A configuration change reached some SearXNG instances or Open WebUI replicas but not others, so each one runs different engine or format settings. | Keep SearXNG configuration in one versioned source and deploy it to every instance together. Send the same test query to each replica and compare the responses. |
What teams ask before connecting SearXNG to Open WebUI
What drives the cost of connecting SearXNG to Open WebUI?
Most of the cost is people time and the infrastructure around the search service, and the final amount depends on your environment. The main components are:
- Internal staff time for planning, reviews, testing and cutover.
- Hosting for SearXNG, including the network path between Open WebUI and the search service.
- Outbound network traffic, which depends on your egress policy.
- Upstream engine behavior, since engines can change how reliably they return results and may need tuning.
- Testing and ongoing maintenance, such as updates and monitoring.
Setup work is largely one-time, while hosting, maintenance and retesting recur. Ask any quote to list each line separately and to state who pays for each one, including what your team must supply.
How long does a SearXNG web search integration take to deliver?
The timeline depends on how much infrastructure already exists and how long approvals take, so no single duration applies to every environment. Teams with an approved host, a working Open WebUI instance and open network paths move faster than teams that must request servers, firewall changes, security review or change windows. Multi-replica Open WebUI deployments add dependencies. Open WebUI's scaling guide calls for PostgreSQL, Redis for shared state and shared file storage across replicas. Ask for a written schedule that lists approval steps separately, the dates each step depends on, and the points where your team must act.
What must our team provide before the work starts?
Four things: a target environment, network rules, a named owner and admin access to Open WebUI. The target environment is the server, virtual machine, container platform or Kubernetes cluster where SearXNG will run, inside your cloud account or data center. Network rules must allow Open WebUI to reach SearXNG and SearXNG to reach the search engines you enable, and they should be written down and approved by the owning team. The owner makes decisions on scope, search engines and acceptance. Admin access to Open WebUI lets the engineer change web search settings and test them. Confirm all four in the written scope so no step depends on an unagreed task.
Can one internal engineer set up SearXNG for Open WebUI alone?
Often yes for a single-instance test, but a production setup usually needs more than one person's time. One engineer can typically deploy SearXNG, connect it to Open WebUI and run tests in a single-replica environment, provided they have access to hosting, network changes and Open WebUI admin settings. Difficulties appear when the work crosses teams, such as firewall approvals, identity or secrets handling, or a multi-replica Open WebUI setup that needs PostgreSQL, Redis and shared storage according to the scaling guide. Before starting, confirm who reviews changes, who covers the engineer during leave and who maintains the setup after go-live.
How does a fixed-scope engagement differ from ongoing support?
A fixed-scope engagement covers defined work, with scope, deliverables and timeline agreed in writing before the work starts. It ends when the agreed deliverables are handed over. Ongoing support is a retainer that covers continuing work such as updates, upgrades and continuous testing, so it does not end at a single handover. For this integration, a fixed scope might cover the SearXNG deployment, the Open WebUI connection and a verification run. A retainer would cover patching SearXNG, retesting after Open WebUI upgrades and responding to changes in upstream engine behavior. Request both options in writing so each recurring task has a named owner.
Will search queries leave our network, and how do search engines affect results?
When SearXNG queries upstream search engines, the outbound requests leave your network through your normal egress path unless you route them through an approved proxy. The engines you enable determine where queries go and how reliably they return results. Engines can block requests, apply rate limits or change their responses without notice, so result quality may vary over time. Ask the team to document which engines are enabled, the outbound destinations your firewall must allow, the logging policy for queries and how failures appear to users in Open WebUI. Your security and privacy teams should review that list before go-live.
Does the Open WebUI license matter when adding web search for more users?
It can. The Open WebUI License forbids altering or removing its branding in deployments that exceed 50 users in any rolling 30-day period, unless you hold an enterprise license or written contributor permission. Adding web search does not change that threshold, but it can change how staff see the interface. Open WebUI's enterprise licenses allow white-labeling and custom branding. Pricing is not published, so you contact Open WebUI enterprise sales with an expected seat count to get a quote. Confirm the license position with your legal or procurement team before rollout.
What should we check after an Open WebUI upgrade?
Check that web search is still enabled, that Open WebUI can still reach SearXNG and that results appear as your settings expect. Open WebUI publishes releases on GitHub, including v0.12.3 on October 16, 2026, which followed v0.12.0 on October 10 and v0.11.0 in July. Read the release notes for every version between your current and target versions, because settings and integrations can change. Run a small set of test queries, confirm that the enabled engines still return results and check logs for errors from the search connection. Record the outcome so the next upgrade has a baseline, and treat this check as part of ongoing maintenance.
How DeployOpen scopes and delivers this integration
DeployOpen plans and implements Open WebUI web search with SearXNG inside infrastructure you control, so the search service, Open WebUI and any supporting services stay under your governance. Each engagement starts from a written scope that names the Open WebUI version, the search path and the systems it touches.
How we scope
- A written scope names the Open WebUI version, the SearXNG instance and the users who can reach web search.
- We confirm which SearXNG engines, output formats and rate limits your team needs before any build work begins.
- Engagements are fixed-scope, and ongoing support is available as a retainer after handover.
How we build
- We deploy SearXNG in your infrastructure and place it behind network controls that limit which services can call it.
- We connect Open WebUI to SearXNG and test queries, timeouts and empty results for each user group.
- For multiple replicas, we add PostgreSQL, Redis and an external vector database, as the scaling guide requires.
How we hand over
- Handover includes a configuration record, network diagram, admin runbook and the test cases used during acceptance.
- Your team receives documented steps for rotating SearXNG credentials and updating Open WebUI settings.
- We walk through sign-out and token behavior so administrators know what Redis changes in multi-replica setups.
How we support
- Retainers can cover SearXNG and Open WebUI updates, dependency checks and patching in infrastructure you control.
- Upgrades follow Open WebUI release notes, including the license terms that apply to newer releases.
- Search settings and logging are reviewed on a schedule agreed with your security team.
