Install

Three ways to run Subtitlarr, depending on your setup. No media folder is ever mounted — only a small SQLite database.

Docker (published image) Docker Compose Unraid Configuration

Docker (published image)

The fastest path if you already run other containers by hand:

docker run -d \
  --name subtitlarr \
  -p 7777:7777 \
  -v ./data:/data \
  ghcr.io/gerardumbert/subtitlarr:latest

Open http://localhost:7777, then set your Bazarr connection from Settings and add at least one engine instance from the Translation Engine page before running a translation.

Docker Compose

Good for local dev, or if you don't already run Ollama:

cp .env.example .env   # fill in scheduling defaults, PUID/PGID, etc.
docker compose up -d

The example compose file also starts an Ollama container — add an Ollama engine instance pointing at http://ollama:11434.

Unraid

Community Applications — Subtitlarr is published in the CA store. Search "Subtitlarr" from the Apps tab, or install directly from ca.unraid.net/apps/subtitlarr-0ejd54j1xpuckv. It points at the published ghcr.io/gerardumbert/subtitlarr image and only exposes the fields that genuinely can't be configured from the web UI afterward: WebUI Port, Data path, and PUID/PGID. Everything else — Bazarr connection, engines, scheduling — is set from the app's own UI once it's running, not from the container form.

Not using CA? The template source lives at unraid/subtitlarr.xml — add it as a template in Unraid's Docker tab (Add Container → Template → paste the raw file URL).

Manual container setup:

Port: container listens on 7777 — map to whatever host port you like
Volume: a host path (e.g. /mnt/user/appdata/subtitlarr) → /data — this is Subtitlarr's own database, not a media path
PUID/PGID: match whatever owns your data folder (Unraid's default nobody:users is 99:100) — the container starts as root, chowns /data, then drops to that user
Network type: bridge works for most setups
Everything else (Bazarr URL/key, engines, scheduling) — set it from the web UI after first start

Using Unraid's built-in Tailscale integration? Keep the host port mapping identical to the container's internal port (e.g. 7777:7777, not 7777:8000) — Unraid's Tailscale Serve hook proxies to the host-mapped port number, so a mismatch silently breaks the Tailscale hostname URL even though LAN access still works fine.

Configuration

None of this needs to be touched at container start — click through the form doing nothing and configure every one of these from the web UI afterward instead. This table is a reference for what each setting does and its default, not a setup requirement.

Variable	Purpose	Default
`BAZARR_BASE_URL`	Bazarr root URL	set from the UI
`BAZARR_API_KEY`	Bazarr API key	set from the UI
`SCHEDULE_CRON`	Cron expression for the main translation job	`10 3 * * *`
`AGE_THRESHOLD_DAYS`	Days missing before a scheduled run translates it	`14`
`DAILY_TRANSLATION_LIMIT`	Max items/day for scheduled runs (0 = unlimited)	`100`
`PAUSE_BETWEEN_ITEMS_SECONDS`	Rest between translations	`30`
`QUEUE_UPLOADS_ENABLED`	Hold uploads for a manual batch push instead of immediate	`false`
`BACKUP_CRON`	Daily database snapshot to `/data/backups/`; blank disables it	`30 2 * * *`

See the full README or the full Docs reference for the complete list.