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
Readme
View on GitHubSublarr

Subtitle Manager & Downloader for Anime and Media
*arr-compatible · Self-hosted · Open Source · Anime-first scoring
Version
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.
🚀 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
sublarruser toPUID/PGID, makes/configowned by that user, then drops privileges withgosuand runs the app asPUID:PGID./mediais left untouched — its permissions must already allow that user to read and write. Useid $USERon the host to find the right IDs (Unraid uses99/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,
.nfometadata, extras skipping, symlink support
🔧 Subtitle tools
- Subtitle editor (CodeMirror, diff view) and waveform editor for retiming
- Sync with ffsubsync / alass, format conversion (ASS, SRT, VTT, SSA), post-processing pipeline (HI removal, OCR cleanup, formatting fixes)
- OCR for PGS/VobSub tracks (Tesseract), Whisper transcription when no text subtitle exists, embedded-stream removal without re-encoding
- Subtitle health checks and subtitle repair
🖥️ 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 |
|---|---|
![]() |
![]() |
| 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
skiprefuses 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),banditat HIGH severity / HIGH confidence (backend/.bandit),npm audit --omit=dev --audit-level=high, custom lint gates (is_safe_path()argument order, UI-first config, noroutesimports inservices), backend and frontend test suites. - Reported in the CI job log, non-blocking: Semgrep, Trivy, bandit findings below the gate,
npm auditover 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
- Bug reports → open a GitHub Issue with log output and config
- Feature requests → open a Discussion first so the approach can be agreed
- Pull requests → see CONTRIBUTING.md and Contributing for code style, tests and commit format
💬 Community
- Discord — discord.gg/WjatsKzHXz — live chat, install help, release testing
- Reddit — r/Sublarr — announcements, showcases, discussions
- GitHub Issues — bug reports & feature requests
📄 License
GPL-3.0 — see LICENSE.
Sublarr is not affiliated with the *arr project or any subtitle provider.
A project by <abrechen2 />
Categories
Download Statistics
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/abrechen2/sublarr:latestRuntime 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
Host port for the Sublarr web UI and API. Swagger UI is available at /api/docs.
- Target
- 5765
- Default
- 5765
- Value
- 5765
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
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
User ID for file ownership. Unraid default is 99 (nobody).
- Default
- 99
- Value
- 99
Group ID for file ownership. Unraid default is 100 (users).
- Default
- 100
- Value
- 100
Container timezone, e.g. Europe/Berlin or UTC.
- Default
- Europe/Berlin
- Value
- Europe/Berlin
Optional API key (X-Api-Key header) protecting the API. Strongly recommended if the port is exposed beyond your LAN.
- Target
- SUBLARR_API_KEY
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
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
Advanced: log verbosity — DEBUG, INFO, WARNING or ERROR.
- Target
- SUBLARR_LOG_LEVEL
- Default
- INFO
- Value
- INFO



