searxng Documentation

File: docs/build-templates/searxng.rst Copy Chapter

.. template evaluated by: ./utils/searxng.sh searxng.doc.rst
.. hint: all dollar-names are variables, dollar sign itself is quoted by: \$

.. START distro-packages

.. tabs::

.. group-tab:: Ubuntu / debian

.. code-block:: sh

  $ sudo -H apt-get install -y \\

${debian}

.. group-tab:: Arch Linux

.. code-block:: sh

  $ sudo -H pacman -S --noconfirm \\

${arch}

.. group-tab:: Fedora / RHEL

.. code-block:: sh

  $ sudo -H dnf install -y \\

${fedora}

.. END distro-packages

.. START build-packages

.. tabs::

.. group-tab:: Ubuntu / debian

.. code-block:: sh

  $ sudo -H apt-get install -y \\

${debian_build}

.. group-tab:: Arch Linux

.. code-block:: sh

  $ sudo -H pacman -S --noconfirm \\

${arch_build}

.. group-tab:: Fedora / RHEL

.. code-block:: sh

  $ sudo -H dnf install -y \\

${fedora_build}

.. END build-packages

.. START create user

.. tabs::

.. group-tab:: bash

.. code-block:: sh

  $ sudo -H useradd --shell /bin/bash --system \\
      --home-dir \"$SERVICE_HOME\" \\
      --comment 'Privacy-respecting metasearch engine' \\
      $SERVICE_USER

  $ sudo -H mkdir \"$SERVICE_HOME\"
  $ sudo -H chown -R \"$SERVICE_GROUP:$SERVICE_GROUP\" \"$SERVICE_HOME\"

.. END create user

.. START clone searxng

.. tabs::

.. group-tab:: bash

.. code-block:: sh

   $ sudo -H -u ${SERVICE_USER} -i
   (${SERVICE_USER})$ git clone \"$GIT_URL\" \\
                      \"$SEARXNG_SRC\"

.. END clone searxng

.. START create virtualenv

.. tabs::

.. group-tab:: bash

.. code-block:: sh

   (${SERVICE_USER})$ python3 -m venv \"${SEARXNG_PYENV}\"
   (${SERVICE_USER})$ echo \". ${SEARXNG_PYENV}/bin/activate\" \\
                      >>  \"$SERVICE_HOME/.profile\"

.. END create virtualenv

.. START manage.sh update_packages

.. tabs::

.. group-tab:: bash

.. code-block:: sh

   $ sudo -H -u ${SERVICE_USER} -i

   (${SERVICE_USER})$ command -v python && python --version
   $SEARXNG_PYENV/bin/python
   Python 3.11.10

   # update pip's boilerplate ..
   pip install -U pip
   pip install -U setuptools
   pip install -U wheel

   # additional packages required for installation
   pip install -U pyyaml
   pip install -U msgspec
   pip install -U typing-extensions
   pip install -U pybind11

   # jump to SearXNG's working tree and install SearXNG into virtualenv
   (${SERVICE_USER})$ cd \"$SEARXNG_SRC\"
   (${SERVICE_USER})$ pip install --use-pep517 --no-build-isolation -e .

.. END manage.sh update_packages

.. START searxng config

.. tabs::

.. group-tab:: Use default settings

.. code-block:: sh

   $ sudo -H mkdir -p \"$(dirname ${SEARXNG_SETTINGS_PATH})\"
   $ sudo -H cp \"$SEARXNG_SRC/utils/templates/etc/searxng/settings.yml\" \\
                \"${SEARXNG_SETTINGS_PATH}\"

.. group-tab:: minimal setup

.. code-block:: sh

   $ sudo -H sed -i -e \"s/ultrasecretkey/\$(openssl rand -hex 16)/g\" \\
                 \"$SEARXNG_SETTINGS_PATH\"

.. END searxng config

.. START check searxng installation

.. tabs::

.. group-tab:: bash

.. code-block:: sh

   # enable debug ..
   $ sudo -H sed -i -e \"s/debug : False/debug : True/g\" \"$SEARXNG_SETTINGS_PATH\"

   # start webapp
   $ sudo -H -u ${SERVICE_USER} -i
   (${SERVICE_USER})$ cd ${SEARXNG_SRC}
   (${SERVICE_USER})$ export SEARXNG_SETTINGS_PATH=\"${SEARXNG_SETTINGS_PATH}\"
   (${SERVICE_USER})$ python -m searx.webapp

   # disable debug
   $ sudo -H sed -i -e \"s/debug : True/debug : False/g\" \"$SEARXNG_SETTINGS_PATH\"

Open WEB browser and visit http://$SEARXNG_INTERNAL_HTTP . If you are inside a
container or in a script, test with curl:

.. tabs::

.. group-tab:: WEB browser

.. code-block:: sh

   $ xdg-open http://$SEARXNG_INTERNAL_HTTP

.. group-tab:: curl

.. code-block:: none

   $ curl --location --verbose --head --insecure $SEARXNG_INTERNAL_HTTP

   *   Trying 127.0.0.1:8888...
   * TCP_NODELAY set
   * Connected to 127.0.0.1 (127.0.0.1) port 8888 (#0)
   > HEAD / HTTP/1.1
   > Host: 127.0.0.1:8888
   > User-Agent: curl/7.68.0
   > Accept: */*
   >
   * Mark bundle as not supporting multiuse
   * HTTP 1.0, assume close after body
   < HTTP/1.0 200 OK
   HTTP/1.0 200 OK
   ...

.. END check searxng installation

File: docs/admin/settings/index.rst Copy Chapter

.. _searxng settings.yml:

======== Settings

.. sidebar:: Further reading ..

• :ref:engine settings
• :ref:engine file

.. toctree::
:maxdepth: 2

settings
settings_engines
settings_brand
settings_general
settings_search
settings_server
settings_ui
settings_preferences
settings_redis
settings_valkey
settings_outgoing
settings_categories_as_tabs
settings_plugins

File: docs/admin/settings/settings.rst Copy Chapter

.. _settings.yml:

================ ``settings.yml``

This page describe the options possibilities of the :origin:searx/settings.yml
file.

.. sidebar:: Further reading ..

• :ref:use_default_settings.yml
• :ref:search API

.. _settings location:

settings.yml location

The initial settings.yml we be load from these locations:

1. the full path specified in the SEARXNG_SETTINGS_PATH environment variable.
2. /etc/searxng/settings.yml

If these files don't exist (or are empty or can't be read), SearXNG uses the
:origin:searx/settings.yml file. Read :ref:settings use_default_settings to
see how you can simplify your user defined settings.yml.

.. _settings use_default_settings:

use_default_settings

.. sidebar:: use_default_settings: true

• :ref:settings location
• :ref:use_default_settings.yml
• :origin:/etc/searxng/settings.yml

The user defined settings.yml is loaded from the :ref:settings location
and can relied on the default configuration :origin:searx/settings.yml using:

use_default_settings: true

server:
In the following example, the actual settings are the default settings defined
in :origin:searx/settings.yml with the exception of the secret_key and
the bind_address:

.. code:: yaml

use_default_settings: true
server:
    secret_key: "ultrasecretkey"   # change this!
    bind_address: "[::]"

engines:
With use_default_settings: true, each settings can be override in a
similar way, the engines section is merged according to the engine
name. In this example, SearXNG will load all the default engines, will
enable the bing engine and define a :ref:token for
the arch linux engine:

.. code:: yaml

use_default_settings: true
server:
  secret_key: "ultrasecretkey"   # change this!
engines:
  - name: arch linux wiki
    tokens: ['$ecretValue']
  - name: bing
    disabled: false

engines: / remove:
It is possible to remove some engines from the default settings. The following
example is similar to the above one, but SearXNG doesn't load the the google
engine:

.. code:: yaml

use_default_settings:
  engines:
    remove:
      - google
server:
  secret_key: "ultrasecretkey"   # change this!
engines:
  - name: arch linux wiki
    tokens: ['$ecretValue']

engines: / keep_only:
As an alternative, it is possible to specify the engines to keep. In the
following example, SearXNG has only two engines:

.. code:: yaml

use_default_settings:
  engines:
    keep_only:
      - google
      - duckduckgo
server:
  secret_key: "ultrasecretkey"   # change this!
engines:
  - name: google
    tokens: ['$ecretValue']
  - name: duckduckgo
    tokens: ['$ecretValue']

File: docs/admin/settings/settings_brand.rst Copy Chapter

.. _settings brand:

========== ``brand:``

.. autoclass:: searx.brand.SettingsBrand
:members:

File: docs/admin/settings/settings_categories_as_tabs.rst Copy Chapter

.. _settings categories_as_tabs:

======================= ``categories_as_tabs:``

A list of the categories that are displayed as tabs in the user interface.
Categories not listed here can still be searched with the :ref:search-syntax.

.. code:: yaml

categories_as_tabs:
general:
images:
videos:
news:
map:
music:
it:
science:
files:
social media:

Engines are added to categories: (compare :ref:engine categories), the
categories listed in categories_as_tabs are shown as tabs in the UI. If
there are no active engines in a category, the tab is not displayed (e.g. if a
user disables all engines in a category).

On the preferences page (/preferences) -- under engines -- there is an
additional tab, called other. In this tab are all engines listed that are not
in one of the UI tabs (not included in categories_as_tabs).

File: docs/admin/settings/settings_engines.rst Copy Chapter

.. _settings engines:

============ ``engines:``

.. sidebar:: Further reading ..

• :ref:configured engines
• :ref:engines-dev

In the section engines: is a list of the engines that are to be made
available in the instance. Each list entry is in turn a key/value mapping.

.. code:: yaml

engines:

- name: dummy.online
   engine: dummy
   ..
 - name: dummy.offline
   engine: dummy-offline
   ..
 ..

In the code example below a full fledged example of a YAML setup from a dummy
engine is shown. Most of the options have a default value or even are optional.

.. hint::

A few more options are possible, but they are pretty specific to some
engines (:ref:engine implementations).

.. code:: yaml

• name: example
  engine: example
  shortcut: demo
  base_url: 'https://{language}.example.com/'
  send_accept_language_header: false
  categories: general
  timeout: 3.0
  api_key: 'apikey'
  disabled: false
  language: en_US
  tokens: [ 'my-secret-token' ]
  weight: 1
  display_error_messages: true
  about:
  website: https://example.com
  wikidata_id: Q306656
  official_api_documentation: https://example.com/api-doc
  use_official_api: true
  require_api_key: true
  results: HTML

  overwrite values from section 'outgoing:'

  enable_http2: false
  retries: 1
  max_connections: 100
  max_keepalive_connections: 10
  keepalive_expiry: 5.0
  using_tor_proxy: false
  proxies:
  http:
  - http://proxy1:8080
  - http://proxy2:8080
  
  https:
  - http://proxy1:8080
  - http://proxy2:8080
  - socks5://user:password@proxy3:1080
  - socks5h://user:password@proxy4:1080

  other network settings

  enable_http: false
  retry_on_http_error: true # or 403 or [404, 429]

name :
Name that will be used across SearXNG to define this engine. In settings, on
the result page...

engine :
Name of the python file used to handle requests and responses to and from this
search engine.

shortcut :
Code used to execute bang requests (in this case using !bi)

base_url : optional
Part of the URL that should be stable across every request. Can be useful to
use multiple sites using only one engine, or updating the site URL without
touching at the code.

send_accept_language_header :
Several engines that support languages (or regions) deal with the HTTP header
Accept-Language to build a response that fits to the locale. When this
option is activated, the language (locale) that is selected by the user is used
to build and send a Accept-Language header in the request to the origin
search engine.

.. _engine categories:

categories : optional
Specifies to which categories the engine should be added. Engines can be
assigned to multiple categories.

Categories can be shown as tabs (:ref:settings categories_as_tabs) in the
UI. A search in a tab (in the UI) will query all engines that are active in
this tab. In the preferences page (/preferences) -- under engines --
users can select what engine should be active when querying in this tab.

Alternatively, :ref:\!bang <search-syntax> can be used to search all engines
in a category, regardless of whether they are active or not, or whether they
are in a tab of the UI or not. For example, !dictionaries can be used to
query all search engines in that category (group).

timeout : optional
Timeout of the search with the current search engine. Overwrites
request_timeout from :ref:settings outgoing. Be careful, it will
modify the global timeout of SearXNG.

api_key : optional
In a few cases, using an API needs the use of a secret key. How to obtain them
is described in the file. Engines that require an API key are set to
inactive: true by default. To enable such an engine, provide the API key
and set inactive: false.

disabled : optional
To disable by default the engine, but not deleting it. It will allow the user
to manually activate it in the settings.

inactive: optional
Remove the engine from the settings (disabled & removed). This defaults to true for engines
that require an API key, please see the api_key section if you want to enable such an engine.

language : optional
If you want to use another language for a specific engine, you can define it
by using the ISO code of language (and region), like fr, en-US,
de-DE.

tokens : optional
A list of secret tokens to make this engine private, more details see
:ref:private engines.

weight : default 1
Weighting of the results of this engine.

display_error_messages : default true
When an engine returns an error, the message is displayed on the user interface.

.. _engine network:

network : optional
Use the network configuration from another engine.
In addition, there are two default networks:

• ipv4 set local_addresses to 0.0.0.0 (use only IPv4 local addresses)
• ipv6 set local_addresses to :: (use only IPv6 local addresses)

enable_http : optional
Enable HTTP for this engine (by default only HTTPS is enabled).

retry_on_http_error : optional
Retry request on some HTTP status code.

Example:

• true : on HTTP status code between 400 and 599.
• 403 : on HTTP status code 403.
• [403, 429]: on HTTP status code 403 and 429.

proxies :
Overwrites proxy settings from :ref:settings outgoing.

using_tor_proxy :
Using tor proxy (true) or not (false) for this engine. The default is
taken from using_tor_proxy of the :ref:settings outgoing.

.. _Pool limit configuration: https://www.python-httpx.org/advanced/#pool-limit-configuration

max_keepalive_connection#s :
Pool limit configuration_, overwrites value pool_maxsize from
:ref:settings outgoing for this engine.

max_connections :
Pool limit configuration_, overwrites value pool_connections from
:ref:settings outgoing for this engine.

keepalive_expiry :
Pool limit configuration_, overwrites value keepalive_expiry from
:ref:settings outgoing for this engine.

.. _private engines:

Private Engines (``tokens``)

Administrators might find themselves wanting to limit access to some of the
enabled engines on their instances. It might be because they do not want to
expose some private information through :ref:offline engines. Or they would
rather share engines only with their trusted friends or colleagues.

.. sidebar:: info

Initial sponsored by Search and Discovery Fund <https://nlnet.nl/discovery>_ of NLnet Foundation <https://nlnet.nl/>_.

To solve this issue the concept of private engines exists.

A new option was added to engines named tokens. It expects a list of strings.
If the user making a request presents one of the tokens of an engine, they can
access information about the engine and make search requests.

Example configuration to restrict access to the Arch Linux Wiki engine:

.. code:: yaml

• name: arch linux wiki
  engine: archlinux
  shortcut: al
  tokens: [ 'my-secret-token' ]

Unless a user has configured the right token, the engine is going to be hidden
from them. It is not going to be included in the list of engines on the
Preferences page and in the output of /config REST API call.

Tokens can be added to one's configuration on the Preferences page under "Engine
tokens". The input expects a comma separated list of strings.

The distribution of the tokens from the administrator to the users is not carved
in stone. As providing access to such engines implies that the admin knows and
trusts the user, we do not see necessary to come up with a strict process.
Instead, we would like to add guidelines to the documentation of the feature.

Example: Multilingual Search

SearXNG does not support true multilingual search. You have to use the language
prefix in your search query when searching in a different language.

But there is a workaround: By adding a new search engine with a different
language, SearXNG will search in your default and other language.

Example configuration in settings.yml for a German and English speaker:

.. code-block:: yaml

search:
    default_lang : "de"
    ...

engines:
  - name : google english
    engine : google
    language : en
    ...

When searching, the default google engine will return German results and
"google english" will return English results.

File: docs/admin/settings/settings_general.rst Copy Chapter

.. _settings general:

============ ``general:``

.. code:: yaml

general:
debug: false
instance_name: "SearXNG"
privacypolicy_url: false
donation_url: false
contact_url: false
enable_metrics: true
open_metrics: ''

debug : $SEARXNG_DEBUG
In debug mode, the server provides an interactive debugger, will reload when
code is changed and activates a verbose logging.

.. attention::

The debug setting is intended for local development server.  Don't
 activate debug (don't use a development server) when deploying to
 production.

donation_url :
Set value to true to use your own donation page written in the
:ref:searx/info/en/donate.md <searx.infopage> and use false to disable
the donation link altogether.

privacypolicy_url:
Link to privacy policy.

contact_url:
Contact mailto: address or WEB form.

enable_metrics:
Enabled by default. Record various anonymous metrics available at /stats,
/stats/errors and /preferences.

open_metrics:
Disabled by default. Set to a secret password to expose an
OpenMetrics API <https://github.com/prometheus/OpenMetrics>_ at /metrics,
e.g. for usage with Prometheus. The /metrics endpoint is using HTTP Basic Auth,
where the password is the value of open_metrics set above. The username used for
Basic Auth can be randomly chosen as only the password is being validated.

File: docs/admin/settings/settings_plugins.rst Copy Chapter

.. _settings plugins:

============ ``plugins:``

.. attention::

The enabled_plugins: section in SearXNG's settings no longer exists.
There is no longer a distinction between built-in and external plugin, all
plugins are registered via the settings in the plugins: section.

.. sidebar:: Further reading ..

• :ref:plugins admin
• :ref:dev plugin

In SearXNG, plugins can be registered in the :py:obj:PluginStore <searx.plugins.PluginStorage> via a fully qualified class name.

A configuration (:py:obj:PluginCfg <searx.plugins.PluginCfg>) can be
transferred to the plugin, e.g. to activate it by default / opt-in or
opt-out from user's point of view.

Please note that some plugins, such as the :ref:hostnames plugin plugin,
require further configuration before they can be made available for selection.

By default the :ref:settings built in plugins are loaded. To change the list
of plugins to be loaded, the value for plugins: in
/etc/searxng/settings.yml must be overwritten.

Following is an example that uses :ref:settings use_default_settings and only
two plugins are registered: the calculator can be activated by the user and the
unit converter is active by default.

.. code:: yaml

use_default_settings: true

plugins:

  searx.plugins.calculator.SXNGPlugin:
    active: false

  searx.plugins.unit_converter.SXNGPlugin:
    active: true

To prevent any plugins from loading, the following setting can be used:

.. code:: yaml

use_default_settings: true

plugins: {}

.. _settings built in plugins:

built-in plugins

The built-in plugins are all located in the namespace searx.plugins.

.. code:: yaml

plugins:

  searx.plugins.calculator.SXNGPlugin:
    active: true

  searx.plugins.infinite_scroll.SXNGPlugin:
    active: false

  searx.plugins.hash_plugin.SXNGPlugin:
    active: true

  searx.plugins.self_info.SXNGPlugin:
    active: true

  searx.plugins.tracker_url_remover.SXNGPlugin:
    active: true

  searx.plugins.unit_converter.SXNGPlugin:
    active: true

  searx.plugins.ahmia_filter.SXNGPlugin:
    active: true

  searx.plugins.hostnames.SXNGPlugin:
    active: true

  searx.plugins.oa_doi_rewrite.SXNGPlugin:
    active: false

  searx.plugins.tor_check.SXNGPlugin:
    active: false

.. _settings external_plugins:

external plugins

SearXNG supports :ref:external plugins <dev plugin> / there is no need to
install one, SearXNG runs out of the box.

Only show green hosted results_:
SearXNG plugin to check if a domain is part of the Green WEB.

SearXNG BM25 Reranker_:
SearXNG plugin that reranks search results using BM25 text relevance scoring
to improve search quality.

.. _Only show green hosted results:
https://github.com/return42/tgwf-searx-plugins/

.. _SearXNG BM25 Reranker:
https://github.com/Oaklight/searxng-bm25-reranker