Installation

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.

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.

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: {"status":"ok"}. Then open http://<HOST_IP>:5765/ in a browser — the onboarding wizard takes over.