SearXNG

https://docs.searxng.org
Admin
SearXNG is a free and open-source metasearch engine that aggregates results from multiple search...
Tokens:392,793
Snippets:3,152
Trust Score:8.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install SearXNG reference setup with uWSGI

Source: https://docs.searxng.org/admin/installation-scripts.html

Run the installation script to install a SearXNG reference setup including uWSGI. Use a sudoer login; if installing from root, the script creates a 'searxng' user that needs read access to the cloned repository, which is not available if cloned under /root.

```bash
$ sudo -H ./utils/searxng.sh install all

```

--------------------------------

### Install and start NGINX on Fedora/RHEL

Source: https://docs.searxng.org/admin/installation-nginx.html

Install NGINX on Fedora or RHEL using dnf and enable/start the service.

```bash
sudo -H dnf install nginx
sudo -H systemctl enable nginx
sudo -H systemctl start nginx

```

--------------------------------

### Install and start NGINX on Arch Linux

Source: https://docs.searxng.org/admin/installation-nginx.html

Install NGINX mainline on Arch Linux and enable/start the service.

```bash
sudo -H pacman -S nginx-mainline
sudo -H systemctl enable nginx
sudo -H systemctl start nginx

```

--------------------------------

### Install Apache on Fedora/RHEL

Source: https://docs.searxng.org/admin/installation-apache.html

Install Apache on Fedora/RHEL using dnf, then enable and start the httpd service.

```bash
sudo -H dnf install httpd
sudo -H systemctl enable httpd
sudo -H systemctl start httpd

```

--------------------------------

### Create tabbed installation instructions with sphinx-tabs group-tabs

Source: https://docs.searxng.org//dev/reST.html

Shows how to create tabbed installation instructions using the sphinx-tabs group-tabs directive. Each group-tab contains a code-block with the shell command for a specific distribution. The example is taken from the Build docs.

```reST
.. tabs::

   .. group-tab:: Ubuntu / debian

      .. code-block:: sh

         $ sudo apt install shellcheck

   .. group-tab:: Arch Linux

      .. code-block:: sh

         $ sudo pacman -S shellcheck

   .. group-tab::  Fedora / RHEL

      .. code-block:: sh

         $ sudo dnf install ShellCheck

```

--------------------------------

### Install Valkey with searxng.sh

Source: https://docs.searxng.org/admin/settings/settings_valkey.html

Command to install a local Valkey DB using the SearXNG utility script. After installation, restart the SearXNG instance.

```bash
$ ./utils/searxng.sh install valkey
# restart your SearXNG instance
```

--------------------------------

### Install SearXNG site using searxng.sh

Source: https://docs.searxng.org/admin/installation-nginx.html

Use the installation script to install the SearXNG site for NGINX. This is the recommended approach if you have no special preferences.

```bash
$ sudo -H ./utils/searxng.sh install nginx

```

--------------------------------

### Warnings when graphviz or LaTeX are missing

Source: https://docs.searxng.org/admin/buildhosts.html

Example warnings shown during `make docs.html` when graphviz or LaTeX are missing. Install the buildhost packages to get better HTML output.

```text
WARNING: dot(1) not found, for better output quality install \
         graphviz from https://www.graphviz.org
..
WARNING: LaTeX command 'latex' cannot be run (needed for math \
         display), check the imgmath_latex setting

```

--------------------------------

### Live documentation build with make docs.live

Source: https://docs.searxng.org/dev/contribution_guide.html

Builds the docs, opens the URL in a browser, and rebuilds on every reST file change. Serves on http://0.0.0.0:8000 and watches for changes.

```bash
$ make docs.live
...
The HTML pages are in dist/docs.
... Serving on http://0.0.0.0:8000
... Start watching changes

```

--------------------------------

### make run - start developer instance

Source: https://docs.searxng.org/dev/makefile.html

Starts a developer instance with debug enabled in git://searx/settings.yml, launches ./searx/webapp.py, and opens the URL in the default browser via xdg-open.

```shell
$ make run

```

--------------------------------

### Install SearXNG with utils/searxng.sh

Source: https://docs.searxng.org/utils/searxng.sh.html

Run this command to perform a complete installation of SearXNG using the utils/searxng.sh script. The -H option sets HOME to the target user's home directory, and 'all' installs every component.

```bash
sudo -H ./utils/searxng.sh install all

```

--------------------------------

### Install Apache on Arch Linux

Source: https://docs.searxng.org/admin/installation-apache.html

Install Apache on Arch Linux using pacman, then enable and start the httpd service.

```bash
sudo -H pacman -S apache
sudo -H systemctl enable httpd
sudo -H systemctl start http

```

--------------------------------

### Set up SearXNG with Docker Compose

Source: https://docs.searxng.org/admin/installation-docker.html

Sets up a SearXNG instance with Docker Compose: creates the environment and configuration directories, fetches the compose template and .env.example, copies and edits the .env file, then starts and stops the services. After this, configure settings in core-config/settings.yml.

```bash
# Create the environment and configuration directories
$ mkdir -p ./searxng/core-config/
$ cd ./searxng/

# Fetch the latest compose template
$ 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

```

```bash
$ cp -i .env.example .env

# nano or your preferred text editor...
$ nano .env

```

```bash
$ docker compose up -d
$ docker compose down

```

--------------------------------

### PostgreSQL engine example

Source: https://docs.searxng.org/dev/engines/offline/sql-engines.html

Example PostgreSQL engine configuration. Requires installing the psycopg2-binary dependency. The query_str uses %(query)s as the parameter placeholder.

```yaml
- name: my_database
  engine: postgresql
  database: my_database
  username: searxng
  password: password
  query_str: 'SELECT * from my_table WHERE my_column = %(query)s'

```

--------------------------------

### Create the SearXNG virtual environment and activate it on login

Source: https://docs.searxng.org/admin/installation-searxng.html

Create a Python virtual environment at /usr/local/searxng/searx-pyenv and add its activation line to the searxng user's .profile so it is sourced on login.

```bash
(searxng)$ python3 -m venv "/usr/local/searxng/searx-pyenv"
(searxng)$ echo ". /usr/local/searxng/searx-pyenv/bin/activate" \
                   >>  "/usr/local/searxng/.profile"

```

--------------------------------

### make install: Rebuild when requirements.sha256 fails

Source: https://docs.searxng.org/dev/makefile.html

Shows the output when running make install again after the initial setup. The rebuild only occurs if the sha256 sum of the requirement files fails, which happens when you edit requirements-dev.txt or requirements.txt.

```bash
$ make install
PYENV     OK
PYENV     [virtualenv] requirements.sha256 failed
          [virtualenv] - 6cea6eb6def9e14a18bf32f8a3e...  ./requirements-dev.txt
          [virtualenv] - 471efef6c73558e391c3adb35f4...  ./requirements.txt
...
PYENV     [virtualenv] installing ./requirements*.txt into local/py3
...
PYENV     [install] pip install --use-pep517 --no-build-isolation -e 'searx[test]'
...
Successfully installed searxng-2023.7.19+a446dea1b

```

--------------------------------

### Valkey Server engine configuration example

Source: https://docs.searxng.org/dev/engines/offline/nosql-engines.html

Example configuration for the `valkey_server` engine. Requires the `valkey` dependency. Set `db` to select the database and `exact_match_only` to control exact vs partial matching.

```yaml
# Required dependency: valkey

- name: myvalkey
  shortcut : rds
  engine: valkey_server
  exact_match_only: false
  host: '127.0.0.1'
  port: 6379
  enable_http: true
  password: ''
  db: 0

```

--------------------------------

### Install SearXNG dependencies and install SearXNG into the virtualenv

Source: https://docs.searxng.org/admin/installation-searxng.html

Exit the previous SearXNG bash session, start a new one, and verify the virtualenv is active. Then update pip, setuptools, and wheel, install additional required packages (pyyaml, msgspec, typing-extensions, pybind11), and install SearXNG into the virtualenv using pip with --use-pep517 --no-build-isolation.

```bash
$ sudo -H -u searxng -i

(searxng)$ command -v python && python --version
/usr/local/searxng/searx-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
(searxng)$ cd "/usr/local/searxng/searxng-src"
(searxng)$ pip install --use-pep517 --no-build-isolation -e .

```

--------------------------------

### Run live theme builds with LIVE_THEME=simple make run

Source: https://docs.searxng.org/dev/makefile.html

Run make with LIVE_THEME=simple to get live builds while modifying CSS and JS.

```shell
$ LIVE_THEME=simple make run

```

--------------------------------

### Example cURL calls for the Search API

Source: https://docs.searxng.org/dev/search_api.html

Shows three example cURL commands: a GET request returning JSON, a POST request returning CSV, and a POST request with redirect following returning JSON.

```bash
curl 'https://searx.example.org/search?q=searxng&format=json'
curl -X POST 'https://searx.example.org/search' -d 'q=searxng&format=csv'
curl -L -X POST -d 'q=searxng&format=json' 'https://searx.example.org/'
```

--------------------------------

### Install packages for better HTML docs output per distribution

Source: https://docs.searxng.org/admin/buildhosts.html

Install additional packages on the build host to get better HTML output when building docs. These commands are alternatives for Ubuntu/Debian, Arch Linux, and Fedora/RHEL.

```bash
$ sudo apt install graphviz imagemagick texlive-xetex librsvg2-bin

```

```bash
$ sudo pacman -S graphviz imagemagick texlive-bin extra/librsvg

```

```bash
$ sudo dnf install graphviz graphviz-gd ImageMagick texlive-xetex-bin librsvg2-tools

```

--------------------------------

### Output of ./manage go.help

Source: https://docs.searxng.org/dev/makefile.html

Output of the `./manage go.help` command, showing the sourced NVM environment, the GOROOT path, and the description of the `install` subcommand.

```text
INFO:  sourced NVM environment from /home/runner/.nvm
go:           GOROOT=/home/runner/work/searxng/searxng/.govm/go1.24.5
  install   : compiles and installs packages

```

--------------------------------

### Full engine configuration example

Source: https://docs.searxng.org/admin/settings/settings_engines.html

Full-fledged YAML example for a dummy engine. Most options have defaults or are optional; some options are engine-specific. The example includes about metadata, outgoing overrides, proxy lists, and network settings.

```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
  enable_http3: false
  retries: 1
  max_connections: 100
  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]

```

--------------------------------

### Open SearXNG webapp in browser

Source: https://docs.searxng.org/admin/installation-searxng.html

Opens the SearXNG webapp in the default browser. Use this after starting the webapp to verify the setup.

```bash
$ xdg-open http://127.0.0.1:8888
```

--------------------------------

### Map magnet link from multiple sources

Source: https://docs.searxng.org/_modules/searx/engines/torznab.html

Returns the first magnet URI from magneturl, guid, enclosure_url, or link, in that order. Returns None if none start with 'magnet'.

```python
def _map_magnet_link(
    magneturl: str | None,
    guid: str | None,
    enclosure_url: str | None,
    link: str | None,
) -> str | None:
    if magneturl and magneturl.startswith('magnet'):
        return magneturl
    if guid and guid.startswith('magnet'):
        return guid
    if enclosure_url and enclosure_url.startswith('magnet'):
        return enclosure_url
    if link and link.startswith('magnet'):
        return link
    return None
```

--------------------------------

### Create /etc/searxng and copy default settings.yml

Source: https://docs.searxng.org/admin/installation-searxng.html

Creates the /etc/searxng directory and copies the default settings.yml template to it. This is part of the minimal setup for SearXNG.

```bash
$ sudo -H mkdir -p "/etc/searxng"
$ sudo -H cp "/usr/local/searxng/searxng-src/utils/templates/etc/searxng/settings.yml" \
             "/etc/searxng/settings.yml"
```

--------------------------------

### MRS engine configuration YAML example

Source: https://docs.searxng.org/_modules/searx/engines/mrs.html

Mandatory configuration for the MRS engine: set the engine name, engine type, and base_url. The base_url must be set or a ValueError is raised during setup.

```yaml
- name: MRS
  engine: mrs
  base_url: https://mrs-host
  ...
```

--------------------------------

### Install buildhost packages with utils/searxng.sh

Source: https://docs.searxng.org/admin/buildhosts.html

Installs all packages needed by SearXNG's build and development tasks on the build host. Run this command from the SearXNG project root.

```bash
$ sudo -H ./utils/searxng.sh install buildhost

```

--------------------------------

### make nvm.status: Show Node.js and nvm status

Source: https://docs.searxng.org/dev/makefile.html

Displays the current Node.js and nvm status. The example output is typical for a Ubuntu 20.04 system with an outdated Node.js v10.19.0 and no NVM installed.

```bash
$ make nvm.status
INFO:  Node.js is installed at /usr/bin/node
INFO:  Node.js is version v10.19.0
WARN:  minimal Node.js version is 16.13.0
INFO:  npm is installed at /usr/bin/npm
INFO:  npm is version 6.14.4
WARN:  NVM is not installed

```
Tokens:
Raw