FAQ
Frequently Asked Questions
Section titled “Frequently Asked Questions”General
Section titled “General”What is Sublarr?
Section titled “What is Sublarr?”Sublarr is a self-hosted subtitle manager for anime and media libraries. It searches subtitle providers, scores and downloads the best match (ASS-first for anime), and can translate subtitles using a local or cloud LLM — all without sending your data to third-party services.
Is Sublarr free?
Section titled “Is Sublarr free?”Yes. Sublarr is open source under GPL-3.0. The only paid components are third-party services you may optionally use (DeepL API, OpenSubtitles VIP, OpenAI API). Ollama for local LLM translation is also free.
What is the minimum setup?
Section titled “What is the minimum setup?”Three things are needed to get started:
- Set your media path in Settings → Library → Media Path (or via the
SUBLARR_MEDIA_PATHenvironment variable — see Environment Variables). - Configure your Ollama URL in Settings → Translation → Ollama URL if Ollama is not running on the same host.
- Add at least one provider API key in Settings → Providers (AnimeTosho requires no key).
Everything else has sensible defaults.
Do I need Sonarr or Radarr?
Section titled “Do I need Sonarr or Radarr?”No. Enable standalone mode in Settings → Integrations → Standalone Folders and Sublarr will watch your media directory directly. Sonarr/Radarr integration is optional but provides better episode metadata and automatic webhook triggers.
What model should I use for translation?
Section titled “What model should I use for translation?”A current general-purpose 14B-parameter Ollama model gives the best quality for anime subtitle translation. If your hardware has limited VRAM (under 8 GB), a 7B-parameter model is a practical alternative. Avoid fine-tuned anime-specific model variants — general-purpose instruction-tuned models produce more reliable results.
Subtitles
Section titled “Subtitles”Why is Sublarr not downloading subtitles?
Section titled “Why is Sublarr not downloading subtitles?”Common causes:
- No matching provider found — check which providers are enabled and have valid API keys in Settings → Providers.
- Provider circuit breaker open — the provider failed repeatedly and Sublarr paused queries to avoid overloading it. It resets automatically; you can also reset manually in Settings → Providers.
- Item not in Wanted queue — open the Wanted page and confirm the file was scanned.
- Path mapping mismatch — if Sonarr/Radarr and Sublarr use different mount paths, configure path mapping in Settings → Integrations.
- Language profile not assigned — the series needs a language profile set in Library.
Check the Queue and Activity pages for per-item error details.
Why are subtitles not appearing in your media server after download?
Section titled “Why are subtitles not appearing in your media server after download?”Sublarr triggers a library refresh automatically after each download. If subtitles still do not appear:
- Verify your media server is configured in Settings → Media Servers.
- Confirm the API key is correct — use the Test button.
- Make sure Sublarr and your media server see the same file paths (check path mapping in Settings → Integrations).
- Trigger a manual library scan in your media server.
Can Sublarr translate existing subtitles?
Section titled “Can Sublarr translate existing subtitles?”Yes. Go to Library → Series → Episode, then click the translate button on any existing subtitle. You can re-translate at any time if the model or prompt changes.
What subtitle formats are supported?
Section titled “What subtitle formats are supported?”- Download: ASS, SSA, SRT, VTT (provider-dependent)
- Translation: ASS and SRT
- Conversion: ASS ↔ SRT ↔ SSA ↔ VTT via the Format Conversion tool
- OCR: PGS and VobSub image-based tracks via Tesseract
Translation
Section titled “Translation”Why is my translation slow?
Section titled “Why is my translation slow?”LLM translation is CPU/GPU-bound. Throughput drops with these factors:
- Model size — a 14B model is roughly 2× slower than a 7B model.
- Batch size — smaller batches are safer but slower.
- Hardware — a GPU with enough VRAM beats CPU by an order of magnitude.
Fix: use a 7B model on GPU and raise the batch size in Settings → Translation → Performance.
Can I use a custom translation prompt?
Section titled “Can I use a custom translation prompt?”Yes. In Settings → Translation → Prompt Presets, create a custom preset or start from one of the built-in templates. The prompt supports {source_language} and {target_language} placeholders.
What is Translation Memory?
Section titled “What is Translation Memory?”Translation Memory stores previous translation results. When the same dialogue line appears again, Sublarr reuses the cached version instead of calling the LLM, which significantly speeds up repeated content across episodes.
What languages are supported?
Section titled “What languages are supported?”Any language pair supported by your chosen LLM or translation backend. Ollama models work well for:
- Japanese → English
- Japanese → German
- Chinese → English
- Korean → English
For European language pairs, DeepL or LibreTranslate may give better results than a local Ollama model.
Performance
Section titled “Performance”Why does Sublarr use a lot of CPU during scanning?
Section titled “Why does Sublarr use a lot of CPU during scanning?”The wanted scanner runs ffprobe on every video file to detect existing embedded subtitles. On large libraries this is CPU-intensive. Reduce the impact by:
- Lowering the worker count in Settings → System → Scanner Workers (default is 4; try 2).
- Enabling Incremental Scanning in Settings → System → Scanner so only changed files are re-probed (mtime-based cache).
- Increasing the scan interval in Settings → System → Scheduler (for example, every 12 hours instead of the default).
Can I use PostgreSQL instead of SQLite?
Section titled “Can I use PostgreSQL instead of SQLite?”Yes. Set SUBLARR_DATABASE_URL=postgresql://<USER>:<PASSWORD>@<HOST_IP>:5432/sublarr. PostgreSQL is recommended for libraries with 1000+ series or concurrent access from multiple processes. See PostgreSQL Setup for migration steps.
Updates & Backup
Section titled “Updates & Backup”How do I update Sublarr?
Section titled “How do I update Sublarr?”docker pull ghcr.io/abrechen2/sublarr:latestdocker compose up -dCheck the GitHub Releases page for breaking changes before updating.
How do I back up my configuration?
Section titled “How do I back up my configuration?”Settings → System → Backup creates a ZIP containing the database and config. Automatic backups run on a configurable schedule. The backup directory (default /config/backups) is configured under the same page.
How do I restore a backup?
Section titled “How do I restore a backup?”Go to Settings → System → Restore and upload your backup ZIP file. This replaces the current database and config. Sublarr restarts automatically after the restore completes.