Installation

Sublarr ships as a single Docker image. Spin it up, point it at your media directory, and the onboarding wizard handles the rest.

Goal

Get a Sublarr instance running and reachable on port 5765.

Prerequisites

• Docker (or Docker Compose — Compose v2 is bundled with modern Docker)
• A media directory accessible on the host filesystem
• (Optional) a long random string for SUBLARR_API_KEY if you want to require an X-Api-Key header on every API request — empty disables auth. Provider keys (OpenSubtitles, SubDL, …) are configured later through the UI, not as env vars.

System requirements

Sublarr runs anywhere Docker runs — linux/amd64 and linux/arm64 (Raspberry Pi 4/5, Synology/QNAP, Unraid, any x86 mini-PC or NAS). The :latest and :stable tags are multi-arch, so Docker pulls the correct image for your host automatically.

Core subtitle management — search, download, scoring, library scan — is lightweight. The AI translation is offloaded to a separate Ollama host or a cloud API (configured under Settings → Translation), so the Sublarr host itself never runs the heavy model.

Tier	Hardware	Database	Best for
Minimum	Raspberry Pi 4 (2 GB) or any arm64/x86 host	SQLite on SSD	Small libraries, home use
Recommended	x86 mini-PC / NAS / Unraid, 4 GB+ RAM	SQLite on SSD	Most users
Large / busy	Recommended + PostgreSQL + Redis	PostgreSQL	Hundreds of wanted items, multiple users

Put /config on an SSD

The /config volume holds the SQLite database, and SQLite is very sensitive to disk-commit latency. A microSD card or a network share (NFS/SMB) makes every request slow — this is the single most common cause of “Sublarr feels sluggish”. Use an SSD (or a USB-SSD), or switch to PostgreSQL. Sublarr logs a warning at startup when it detects slow storage.

Heavy work runs elsewhere or on demand

LLM translation is done by an external backend, not the Sublarr container. CPU-heavy features such as Whisper transcription and automatic subtitle sync are optional and off unless you enable them — leave them off on low-power hosts like a Raspberry Pi.

Install

Docker (one-liner)

docker run -d \
  --name sublarr \
  -p 5765:5765 \
  -v <CONFIG_PATH>:/config \
  -v <MEDIA_PATH>:/media \
  -e PUID=1000 \
  -e PGID=1000 \
  ghcr.io/abrechen2/sublarr:latest

• /config — stores the database, logs, and application state; persists across container restarts.
• /media — mount your media library here; Sublarr treats this as the root path for subtitle operations.
• PUID / PGID — run as a specific user/group so file permissions match your host (use id to find your values).

For the full list of environment variables accepted at boot, see Environment Variables.

Docker Compose

Create a docker-compose.yml:

services:
  sublarr:
    image: ghcr.io/abrechen2/sublarr:latest
    container_name: sublarr
    ports:
      - "5765:5765"
    volumes:
      - ./config:/config
      - <MEDIA_PATH>:/media:rw
    environment:
      - PUID=1000
      - PGID=1000
    restart: unless-stopped

Start the stack:

docker compose up -d

Unraid

1. Open the Apps tab and search for Sublarr in Community Applications.
2. Click Install and configure the template:
   • Config Path: /mnt/user/appdata/sublarr
   • Media Path: your media share (e.g., /mnt/user/media)
3. Click Apply — the container starts automatically.

All further configuration is done through the web UI at http://<HOST_IP>:5765.

Opening Sublarr from another machine

Since 1.17.4 the live connection of the web UI (/socket.io/) accepts the address you open Sublarr on, whether that is http://<HOST_IP>:5765 or a domain. On 1.17.3 and older, SUBLARR_CORS_ORIGINS defaulted to localhost only; set it to exactly your origin there, for example SUBLARR_CORS_ORIGINS=http://192.168.1.20:5765. See Environment Variables.

Prefer to let an AI coding agent do this? See Install with an AI agent.

Behind a reverse proxy

If Sublarr lives behind nginx, Caddy, or NPM, see Reverse Proxy Guide.

Verify

curl http://<HOST_IP>:5765/api/v1/health

Expected response: a JSON object with "status":"healthy" and the running version, plus a services block listing what is not configured yet. Then open http://<HOST_IP>:5765/ in a browser — the onboarding wizard takes over.