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, 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.

Registries

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:

Compose instancing

This is the recommended way to deploy SearXNG in a containerized environment. Compose templates allow you to define container configurations in a declarative manner.

Setup

  1. Create the environment:

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

# Fetch the latest compose template
$ curl -fsSLO \
    https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
    https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

  1. Rename the .env.example file to .env and edit the values as needed.

  2. Start & stop the services:

$ docker compose up -d
$ docker compose down

  1. Setup your settings in core-config/settings.yml according to your preferences.

Management

Important

Remember to review the new templates for any changes that may affect your deployment, and update the .env file accordingly.

To update the templates to their latest versions:

$ docker compose down
$ curl -fsSLO \
    https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
    https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example
$ docker compose up -d

To update the services to their latest versions:

$ docker compose down
$ docker compose pull
$ docker compose up -d

List running services:

$ docker compose ps
NAME            IMAGE  ...  CREATED        STATUS        PORTS
searxng-core    ...    ...  3 minutes ago  Up 3 minutes  0.0.0.0:8080->8080/tcp
searxng-valkey  ...    ...  3 minutes ago  Up 3 minutes  6379/tcp

Print a service container logs:

$ docker compose logs -f core

Access a service container shell (troubleshooting):

$ docker compose exec -it --user root core /bin/sh -l
/usr/local/searxng #

Stop and remove the services:

$ docker compose down

Manual instancing

This section is intended for advanced users who need custom deployments. We recommend using Container compose instancing, 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 -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
1af574997e63  ...    ...  3 minutes ago  0.0.0.0:8888->8080/tcp  searxng

Print the container logs:

$ docker container logs -f searxng

Access the container shell (troubleshooting):

$ docker container exec -it --user root searxng /bin/sh -l
/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:

Custom certificates

You can mount /usr/local/share/ca-certificates/ folder to add/remove additional certificates as needed.

They will be available on container (re)start or when running update-ca-certificates in the container shell.

This requires the container to be running with root privileges.

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  2025.8.1-3d96414    ...       About a minute ago  183 MB
localhost/searxng/searxng  latest              ...       About a minute ago  183 MB
localhost/searxng/searxng  builder             ...       About a minute ago  524 MB
ghcr.io/searxng/base       searxng-builder     ...       2 days ago          378 MB
ghcr.io/searxng/base       searxng             ...       2 days ago          42.2 MB

Migrate from searxng-docker

We expect the following source directory structure:

.
└── searxng-docker
    ├── searxng
    │   ├── favicons.toml
    │   ├── limiter.toml
    │   ├── settings.yml
    │   └── ...
    ├── .env
    ├── Caddyfile
    ├── docker-compose.yml
    └── ...

Create a brand new environment outside searxng-docker directory, following Container compose instancing setup.

Once up and running, stop the services and move the configuration files from the old mount to the new one:

$ mv ./searxng-docker/searxng/* ./searxng/core-config/

If you have any custom environment variables in the old .env file, make sure to add them manually to the new one.

Consider setting up a reverse proxy if exposing the instance to the public.

You should end with the following directory structure:

.
├── searxng
│   ├── core-config
│   │   ├── favicons.toml
│   │   ├── limiter.toml
│   │   ├── settings.yml
│   │   └── ...
│   ├── .env.example
│   ├── .env
│   └── docker-compose.yml
└── searxng-docker
    └── ...

If everything is working on the new environment, you can remove the old searxng-docker directory and its contents.