Skip to content
Back to top
View this page
Edit this page

# 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:

- Docker (recommended for most users)

- Podman

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:

- DockerHub mirror

- GHCR mirror (GitHub Container Registry)

## 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 -fsSL \
        -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
        -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

2. Copy the `.env.example` file and edit the values as needed:

    $ cp -i .env.example .env

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

3. Start & stop the services:

    $ docker compose up -d
    $ docker compose down

4. 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:

- `$SEARXNG_*`: Controls the SearXNG configuration options, look out for environment `$SEARXNG_*` in server:, general: and the git://container/.env.example template.

- `$GRANIAN_*`: Controls the Granian server options.

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

## 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 using Valkey features like bot protection (limiter), you will need to update the URL hostname in git://searx/settings.yml file to `valkey` or `searxng-valkey`.

If you have any environment variables in the old `.env` file, make sure to add them 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.