Installing SearXNG from Scratch on Debian

2025-10-23 10:10:29 - 7 Comments

First we ensure that our system is up to date.

sudo apt update
sudo apt upgrade

Next we will install a couple of required packages to create the python environment, read html, xml and communicate with the internet.

sudo -H apt-get install -y python3-dev python3-babel python3-venv python-is-python3 uwsgi uwsgi-plugin-python3 git build-essential libxslt-dev zlib1g-dev libffi-dev libssl-dev

We need a new user and home directory where we can put the code and script files.

sudo -H useradd --shell /bin/bash --system --home-dir "/usr/local/searxng" --comment 'Privacy-respecting metasearch engine' searxng
sudo -H mkdir -p "/usr/local/searxng"
sudo -H chown -R "searxng:searxng" "/usr/local/searxng"

We also need a configuration file that we will put under etc.

sudo -H mkdir -p "/etc/searxng"
sudo vi /etc/searxng/settings.yml

Configuration below is pretty standard with the least settings we need to get started, after this we can customize after need.

# SearXNG settings

use_default_settings: true

general:
  debug: true
  instance_name: "SearXNG"

search:
  safe_search: 2
  autocomplete: 'duckduckgo'
  formats:
    - html
    - json

server:
  # Is overwritten by ${SEARXNG_SECRET}
  secret_key: "ultrasecretkey"
  limiter: false
  image_proxy: true
  # public URL of the instance, to ensure correct inbound links. Is overwritten
  # by ${SEARXNG_BASE_URL}.
  # base_url: http://example.com/location
  port: 8888
  bind_address: "0.0.0.0"

valkey:
  # URL to connect valkey database. Is overwritten by ${SEARXNG_VALKEY_URL}.
  url: false

Generate a unique key

sudo sed -i "s|ultrasecretkey|$(openssl rand -hex 32)|g" /etc/searxng/settings.yml

Now we will sudo into our searxng account.

sudo -H -u searxng -i

Next we need to fetch the code.

git clone "https://github.com/searxng/searxng" "/usr/local/searxng/searxng-src"

Creating a python environment creates an wrapper that makes it possible for us to install packages that aren't system native.

python3 -m venv "/usr/local/searxng/searx-pyenv"
source /usr/local/searxng/searx-pyenv/bin/activate

Next we enter the code directory, install some extra dependencies and also the dependencies defined by the project.

cd "/usr/local/searxng/searxng-src"
pip install -U pip setuptools wheel pyyaml msgspec
pip install --use-pep517 --no-build-isolation -e .

Now we test the application by setting an environment variable for the settings file and then starting the application.

export SEARXNG_SETTINGS_PATH="/etc/searxng/settings.yml"
python searx/webapp.py

After ensuring the application runs correctly we will exit the searxng user account and return to our logged in user with sudo access. We need now to create a start script.

sudo vi /usr/local/searxng/searxng.sh

The script does pretty much exactly the steps we did earlier to test our application.

#!/bin/bash
source /usr/local/searxng/searx-pyenv/bin/activate
cd /usr/local/searxng/searxng-src
python searx/webapp.py 2>&1 

Make the script executable and give the user and group permissions to searxng.

sudo chmod +x /usr/local/searxng/searxng.sh
sudo chown searxng:searxng /usr/local/searxng/searxng.sh

Lastly we will create a service by editing:

sudo vi /etc/systemd/system/searxng.service

The service definition below is pretty simple, setting environment variable, pid file and script to run to start the application.

[Unit]
Description=SearXNG service
Wants=network-online.target

[Install]
WantedBy=multi-user.target

[Service]
Environment="SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml"
RuntimeDirectory=searxng
Type=simple
User=searxng
Group=searxng
TimeoutStartSec=0
Restart=always
RestartSec=10s
PIDFile=/run/searxng/searxng.pid
ExecStart=/usr/local/searxng/searxng.sh

Reload the daemon configuration, start and enable the service and check status to see that all started correctly.

sudo systemctl daemon-reload
sudo systemctl start searxng
sudo systemctl enable searxng
sudo systemctl status searxng

Your searxng service should now be available on port 8888 on the newly installed machine.