Installation container

Important

Understanding container architecture basics is essential for properly maintaining your SearXNG instance. This guide assumes familiarity with container concepts and provides deployment steps at a high level.

If you’re new to containers, we recommend learning the fundamentals at Docker 101 before proceeding.

Container images are the basis for deployments in containerized environments, Docker compose, Kubernetes and more.

Installation

Prerequisites

You need a working Docker or Podman installation on your system. Choose the option that works best for your environment:

In the case of Docker, you need to add the user running the container to the docker group and restart the session:

$ sudo usermod -aG docker $USER

In the case of Podman, no additional steps are generally required, but there are some considerations when running Podman rootless containers.

Pulling images

Note

DockerHub now applies rate limits to unauthenticated image pulls. If you are affected by this, you can use the GHCR mirror instead.

The official images are mirrored at:

Pull the latest image:

$ docker pull docker.io/searxng/searxng:latest

.. or if you want to lock in to a specific version:

$ docker pull docker.io/searxng/searxng:2025.6.3-b73ac81

Instancing

This section is intended for advanced users who need custom deployments. We recommend using Docker compose, which provides a preconfigured environment with sensible defaults.

Basic container instancing example:

# Create directories for configuration and persistent data
$ mkdir -p ./searxng/config/ ./searxng/data/
$ cd ./searxng/

# Run the container
$ docker run --name searxng --replace -d \
    -p 8888:8080 \
    -v "./config/:/etc/searxng/" \
    -v "./data/:/var/cache/searxng/" \
    docker.io/searxng/searxng:latest

This will start SearXNG in the background, accessible at http://localhost:8888

Management

List running containers:

$ docker container list
CONTAINER ID  IMAGE  ...  CREATED        PORTS                   NAMES
37f6487c8703  ...    ...  3 minutes ago  0.0.0.0:8888->8080/tcp  searxng

Access the container shell (troubleshooting):

$ docker container exec -it --user root searxng /bin/sh -l
37f6487c8703:/usr/local/searxng#

Stop and remove the container:

$ docker container stop searxng
$ docker container rm searxng

Volumes

Two volumes are exposed that should be mounted to preserve its contents:

  • /etc/searxng: Configuration files (settings.yml, etc.)

  • /var/cache/searxng: Persistent data (faviconcache.db, etc.)

Environment variables

The following environment variables can be configured:

  • $SEARXNG_*: Controls the SearXNG configuration options, look out for environment $SEARXNG_* in server: and general:.

  • $GRANIAN_*: Controls the Granian server options.

  • $FORCE_OWNERSHIP: Ensures mounted volumes/files are owned by the searxng:searxng user (default: true)

Container internal paths (don’t modify unless you know what you’re doing):

  • $CONFIG_PATH: Path to the SearXNG configuration directory (default: /etc/searxng)

  • $SEARXNG_SETTINGS_PATH: Path to the SearXNG settings file (default: $CONFIG_PATH/settings.yml)

  • $DATA_PATH: Path to the SearXNG data directory (default: /var/cache/searxng)

Custom images

To build your own SearXNG container image from source (please note, custom container images are not officially supported):

$ git clone https://github.com/searxng/searxng.git
$ cd ./searxng/

# Run the container build script
$ make container

$ docker images
REPOSITORY                 TAG                       IMAGE ID      CREATED         SIZE
localhost/searxng/searxng  latest                    b14e256bfc36  14 seconds ago  201 MB
localhost/searxng/searxng  2025.5.1-b653119ab-dirty  b14e256bfc36  14 seconds ago  201 MB
localhost/searxng/searxng  builder                   7f334c752b41  20 seconds ago  765 MB
ghcr.io/searxng/base       searxng-builder           7d6b8a1bed4a  20 hours ago    625 MB
ghcr.io/searxng/base       searxng                   29baf9ef13ef  20 hours ago    62.5 MB