Sublarr

Sublarr

Docker app from Abrechen2's Repository

Self-hosted subtitle manager for anime and media libraries — a *arr-style companion (and Bazarr alternative) that automatically searches, scores and downloads the best subtitle,…

Overview

Self-hosted subtitle manager for anime and media libraries — a *arr-style companion (and Bazarr alternative) that automatically searches, scores and downloads the best subtitle, then gives you tools to edit, sync and convert it. Runs entirely on your LAN; no cloud required.

What it does:

  • Searches 21 subtitle providers in parallel (AnimeTosho, Jimaku, OpenSubtitles, SubDL, Subscene, Subf2m, Subsource, SubsDump, Addic7ed, BetaSeries, Titlovi, Titrari, TVSubtitles, Gestdown, Kitsunekko, Napisy24, Podnapisi, YIFY, Zimuku, LegendasDivX, TurkceAltyazi) plus embedded subtitle extraction.
  • ASS-first scoring with format, dialect, sync-quality and uploader-trust weighting; smart de-duplication; per-provider circuit breakers.
  • Sonarr/Radarr webhook integration (multi-instance), Jellyfin/Emby/Plex/Kodi library refresh, AniDB absolute-episode-order handling.
  • Standalone mode (no *arr required): watches a folder and reads .nfo metadata.
  • Subtitle toolbox: Aegisub-class waveform editor, ffsubsync/alass sync, format conversion, an 18-step post-processing pipeline, batch OCR and Whisper fallback.
  • Optional LLM translation (Ollama / DeepL / Google / LibreTranslate / OpenAI-compatible) — experimental; quality varies.

Setup:

Sublarr is self-contained — it stores everything in an embedded SQLite database, so no separate database container is required. After the container is healthy, open http://[IP]:[PORT:5765] and the first-run onboarding wizard walks you through language selection, provider keys and automation. Sonarr/Radarr are optional.

Map the Media Path to the same library root your Sonarr/Radarr/Jellyfin see, so subtitle files land next to your videos.

Configuration is UI-first. This template only exposes the handful of boot-level settings (ports, paths, IDs, optional API key / database / log level). Everything else — Sonarr/Radarr connections, provider API keys, language profiles, translation backends, path mapping, automation — is configured in the web UI under Settings and stored in the database. There is no need to set those as environment variables.

Optional backends: PostgreSQL and Redis are supported for larger setups via the SUBLARR_DATABASE_URL / SUBLARR_REDIS_URL variables (advanced) — point them at your own containers. Not needed for normal use.

Optional translation (experimental): install the Ollama Community App and pull a general model (e.g. qwen2.5:14b-instruct), then point Sublarr at it under Settings → Translation in the web UI (e.g. http://host.docker.internal:11434). Disabled by default.

Full documentation: https://sublarr.de/docs/ · Source: https://github.com/Abrechen2/sublarr

Sublarr

Sublarr Logo

Subtitle Manager & Downloader for Anime and Media

*arr-compatible · Self-hosted · Open Source · Anime-first scoring

Version CI security License: GPL-3.0 Python 3.12+ React 19 Docker


Quick Start · Is it for you? · Configuration · Limitations · Integrations · Website · Docs

Community: Discord · Reddit r/Sublarr · GitHub Issues


Sublarr is a self-hosted subtitle manager for anime and media libraries. It searches subtitle providers, scores the results (ASS-first), downloads the best match and gives you tools to edit, sync and convert subtitles — all on your LAN.

Connect it to Sonarr/Radarr and it reacts to imports via webhooks, or run it standalone: it watches your media folders and reads .nfo metadata, no *arr required.

What sets it apart:

  • Right-episode check and repair — every search result whose name states a different season or episode is dropped before scoring, for every provider. Subtitles saved earlier for the wrong episode can be found and re-searched under Settings → System → Subtitle repair.
  • Encoding repair — subtitles delivered in legacy encodings (Windows-125x, Greek, Cyrillic, GBK, …) are read in their language's encoding and saved as UTF-8; files damaged by older builds can be restored provably from the original.
  • Anime-aware matching — AniDB absolute episode order, optional Shoko Server mapping, anime season-collapse handling, ASS/signs track handling and dubtitle detection.

Sublarr tour: dashboard, library, series detail and wanted list


🚀 Quick Start

Create a docker-compose.yml:

services:
  sublarr:
    image: ghcr.io/abrechen2/sublarr:latest
    container_name: sublarr
    ports:
      - "5765:5765"
    volumes:
      - ./config:/config        # database, backups, logs
      - /path/to/media:/media   # your media library (same path your media server sees)
    environment:
      - PUID=1000
      - PGID=1000
    restart: unless-stopped
docker compose up -d

Open http://localhost:5765. The onboarding wizard walks you through languages, providers and automation. Next step: First 10 minutes.

  • Unraid: search for Sublarr in Community Applications (template: unraid/README.md).
  • PUID / PGID: the container starts as root, remaps its sublarr user to PUID/PGID, makes /config owned by that user, then drops privileges with gosu and runs the app as PUID:PGID. /media is left untouched — its permissions must already allow that user to read and write. Use id $USER on the host to find the right IDs (Unraid uses 99/100).
  • More setups (PostgreSQL, Redis, reverse proxy, resource limits): Installation.

🤔 Is Sublarr for you?

Probably not, if your library is English-only live-action and Bazarr already covers it, you never touch anime, or you need multi-user accounts today.

Probably yes, if you run anime (absolute ordering, signs/songs tracks, several English tracks per file), care about the subtitle format (styled ASS rather than a flattened SRT), maintain several languages with per-language rules, or want to see why a file was chosen and change the answer.

More: Scope and limitations · Migrating from Bazarr.


✨ Features

🔍 Search & download

  • 28 built-in provider adapters — 20 subtitle sites (AnimeTosho, Jimaku, OpenSubtitles, SubDL, SubSource, Subf2m, SubsDump, Addic7ed, BetaSeries, Titlovi, Titrari, TVSubtitles, Gestdown, Kitsunekko, Napisy24, Podnapisi, YIFY, Zimuku, LegendasDivX, TurkceAltyazi), a Custom HTTP/JSON adapter (docs/CUSTOM_PROVIDER_API.md), embedded-track extraction and 6 Subliminal-based alternates
  • 43 opt-in catalog providers — a reviewed, pinned copy of the Bazarr+ provider catalog, off by default
  • ASS-first scoring with format, release, sync and uploader-trust components; score breakdown on hover; decision log per search
  • Language profiles — per-series/film target languages, mustContain / mustNotContain filters, cutoff, audioExclude
  • Parallel provider search, per-provider circuit breakers and rate-limit budgets, SHA-256 deduplication, machine-translation flagging

📺 *arr & media servers

  • Sonarr & Radarr webhooks, multiple instances, tag-based profile assignment, path mapping for remote hosts
  • Library refresh for Jellyfin, Emby, Plex and Kodi; Shoko Server for authoritative AniDB matching
  • Standalone mode: filesystem watching, .nfo metadata, extras skipping, symlink support

🔧 Subtitle tools

🖥️ Wanted & automation

  • Wanted scanner, event-driven by default (webhooks, manual triggers, file watcher), with an optional periodic fallback
  • Upgrade system that replaces low-quality subtitles when a better one appears; batch search with live progress
  • Scheduler admin under Settings → System → Scheduler (run now, pause, resume, edit trigger)

🌐 Translation

Off by default. Turn it on in Settings → Translation and configure a backend: Ollama, DeepL, LibreTranslate, any OpenAI-compatible endpoint, Google Cloud Translation, Claude, Gemini, DeepSeek, Mistral, ChatGPT, Azure Translator or MyMemory. The result depends on the translation backend and model you choose — use at your own risk. See Translation.


🖥️ UI Overview

Dashboard Library
Dashboard Library
Series detail Wanted
Series detail Wanted
Page Description
Dashboard Customizable widget grid — status, queue, recent activity, automation status
Library Series and movies with subtitle progress and bulk actions
Wanted Missing subtitles with one-click search, failure reasons and retry countdown
Activity Tabs for live queue, history and blacklist (/queue and /history redirect here)
Statistics Provider success rates, language distribution, quality trends
Providers Per-provider statistics — success rates, response times, circuit-breaker and throttle state, API budget
Health Library problems — series with missing subtitles, stuck wanted items, provider health
Trash Deleted subtitle sidecars and video backups, restorable
Logs Application log viewer
Settings General, Connections, Subtitles, Providers (incl. plugin marketplace — /plugins redirects here), Automation, Translation, Notifications, System

Global search with Ctrl+K, keyboard shortcuts (?), real-time updates via WebSocket.


⚙️ Configuration

Almost everything — providers and API keys, languages, Sonarr/Radarr/media-server connections, path mapping, automation, translation — is configured in the Settings UI and stored in the database. SUBLARR_* environment variables for those settings are ignored (Sublarr logs a warning at startup when it finds one).

Only these bootstrap variables are read from the environment (backend/config_settings.py → BootSettings):

Variable Default Description
SUBLARR_PORT 5765 HTTP port
SUBLARR_API_KEY (empty) Optional API key (X-Api-Key header); empty = no API-key auth
SUBLARR_CORS_ORIGINS (empty) Extra Socket.IO origins, comma-separated. Sublarr's own origin is always allowed; behind a reverse proxy, forward the original Host header (nginx: proxy_set_header Host $http_host;) or list the public origin here
SUBLARR_MEDIA_PATH /media Media library root inside the container
SUBLARR_CONFIG_DIR /config Persistent config directory
SUBLARR_DB_PATH /config/sublarr.db SQLite database path
SUBLARR_DATABASE_URL (empty) SQLAlchemy URL (e.g. PostgreSQL); wins over DB_PATH
SUBLARR_REDIS_URL (empty) Optional Redis for cache and queue
SUBLARR_LOG_LEVEL INFO DEBUG, INFO, WARNING, ERROR
SUBLARR_LOG_FILE /config/sublarr.log (image) Log file path
SUBLARR_LOG_FORMAT text text or json
SUBLARR_STATS_ENDPOINT https://stats.sublarr.de/v1/ping Opt-in usage statistics target; empty disables sending
SUBLARR_SCHEDULER_ROLE primary disabled on extra replicas so recurring jobs do not run twice
PUID / PGID 1000 User/group the app runs as (see Quick Start)
UMASK 022 umask for files written into /media

Full reference: Environment variables · Settings.

Hardlinks: most Sonarr/Radarr setups hardlink the library to the download folder. A container remux (foreign-track cleanup, signs removal, stream removal) rewrites the file and breaks that hardlink. The default hardlink policy skip refuses to remux hardlinked files.


🔌 Integrations

  • Sonarr & Radarr — add the connection in Settings → Connections, then in Sonarr/Radarr add a webhook (Settings → Connect → Webhook) to http://sublarr:5765/api/v1/webhook/sonarr (or /radarr) for On Import and On Upgrade.
  • Jellyfin / Emby / Plex / Kodi / Shoko — add the server in Settings → Connections; Sublarr triggers a rescan after each subtitle download. Shoko additionally supplies authoritative AniDB IDs and absolute episode numbers.
  • Standalone — point Sublarr at your media folders; new video files are added to the wanted list.
  • *Remote arr hosts — when paths differ between hosts, set a path mapping in Settings → Connections.

Walkthroughs: Integrations · AniDB · Reverse proxy.


⚠️ Known limitations

  • One shared password, no user accounts. No usernames, roles or per-user audit trail. For multi-user setups put it behind a reverse proxy with forward-auth; Sublarr can read proxy auth headers (Authelia / authentik).
  • One instance per library. The scheduler assumes a single primary; extra replicas need SUBLARR_SCHEDULER_ROLE=disabled. No worker pool, no multi-host distribution.
  • No auto-update, by design. The UI tells you when a newer release exists; you run the upgrade. Read the CHANGELOG first.
  • Docker is the supported path. Running from source is for development; bare-metal installs are not tested.
  • Provider coverage depends on your accounts. Several providers need credentials or an API key; without them you run a smaller subset.
  • Anime-first defaults. ASS gets a large scoring bonus over SRT — deliberate for anime, less relevant for English live-action.
  • Solo-maintained. Bug reports get read; response time varies.
  • Docs can drift. If the documentation and the running app disagree, trust the app and open an issue.

Keep backups of your subtitle files before enabling automation.


🔒 Security

CI runs on every push to master.

  • Blocks the build: ruff check + ruff format --check, pip-audit -r requirements.txt (no ignored advisories), bandit at HIGH severity / HIGH confidence (backend/.bandit), npm audit --omit=dev --audit-level=high, custom lint gates (is_safe_path() argument order, UI-first config, no routes imports in services), backend and frontend test suites.
  • Reported in the CI job log, non-blocking: Semgrep, Trivy, bandit findings below the gate, npm audit over dev dependencies. Nothing is uploaded to GitHub code scanning.

Report vulnerabilities as described in SECURITY.md.


💻 Development

# First-time setup (Python + Node dependencies, optional pre-commit hooks)
npm run setup:sh      # Linux/Mac
npm run setup:ps1     # Windows PowerShell

# Backend (:5765) + frontend (:5173)
npm run dev

# Tests
cd backend && python -m pytest
cd frontend && npm test

# Lint & type check
cd backend && ruff check . && ruff format --check .
cd frontend && npm run lint && npx tsc --noEmit

Every instance serves its own API reference at /api/docs (Swagger UI) and /api/v1/openapi.json. Further reading: Architecture · API reference · Plugin development · Database schema · ROADMAP.md.

AI was used as a coding assistant during development (scaffolding, test drafting, refactoring sweeps, documentation drafts); architecture, scoring, provider integrations and release decisions were made and debugged by hand.


🤝 Contributing

  1. Bug reports → open a GitHub Issue with log output and config
  2. Feature requests → open a Discussion first so the approach can be agreed
  3. Pull requests → see CONTRIBUTING.md and Contributing for code style, tests and commit format

💬 Community


📄 License

GPL-3.0 — see LICENSE.

Sublarr is not affiliated with the *arr project or any subtitle provider.


Categories

Download Statistics

9,874
Total Downloads

Related apps

Links

Details

Repository
ghcr.io/abrechen2/sublarr:latest
Last Updated2026-11-01
First Seen2026-06-13

Runtime arguments

Web UI
http://[IP]:[PORT:5765]/
Network
bridge
Shell
sh
Privileged
false
Extra Params
--restart=unless-stopped --add-host=host.docker.internal:host-gateway

Template configuration

WebUI PortPorttcp

Host port for the Sublarr web UI and API. Swagger UI is available at /api/docs.

Target
5765
Default
5765
Value
5765
Config PathPathrw

Persistent application data — SQLite database, plugins, backups and logs. Single volume; nothing else needs to be mounted for normal use.

Target
/config
Default
/mnt/user/appdata/sublarr
Value
/mnt/user/appdata/sublarr
Media PathPathrw

Root of your media library. Must be the same path your Sonarr/Radarr/Jellyfin use so subtitles are written next to the video files.

Target
/media
Default
/mnt/user/media
Value
/mnt/user/media
PUIDVariable

User ID for file ownership. Unraid default is 99 (nobody).

Default
99
Value
99
PGIDVariable

Group ID for file ownership. Unraid default is 100 (users).

Default
100
Value
100
TZVariable

Container timezone, e.g. Europe/Berlin or UTC.

Default
Europe/Berlin
Value
Europe/Berlin
API KeyVariable

Optional API key (X-Api-Key header) protecting the API. Strongly recommended if the port is exposed beyond your LAN.

Target
SUBLARR_API_KEY
Database URLVariable

Advanced: PostgreSQL DSN to use Postgres instead of the built-in SQLite, e.g. postgresql://sublarr:PASSWORD@host.docker.internal:5432/sublarr. Leave empty for SQLite (recommended).

Target
SUBLARR_DATABASE_URL
Redis URLVariable

Advanced: Redis connection string for the job queue, e.g. redis://host.docker.internal:6379/0. Leave empty to use the in-process queue (recommended).

Target
SUBLARR_REDIS_URL
Log LevelVariable

Advanced: log verbosity — DEBUG, INFO, WARNING or ERROR.

Target
SUBLARR_LOG_LEVEL
Default
INFO
Value
INFO