Environment Variables
Sublarr is UI-first: only 12 bootstrap variables can be set via the environment. Everything else — translation, providers, scheduling, profiles, notifications — is configured through the Settings UI and stored in the database, where it survives container restarts.
If you set a non-bootstrap variable like SUBLARR_TRANSLATION_ENABLED, SUBLARR_OLLAMA_URL, or SUBLARR_OPENSUBTITLES_API_KEY, the container logs a warning and ignores it. Move the value into the Settings UI.
The 12 bootstrap variables
Section titled “The 12 bootstrap variables”These 12 variables — and only these — can be set via the environment. Everything is optional; the defaults below ship a working container.
Server
Section titled “Server”| Variable | Default | Description |
|---|---|---|
SUBLARR_PORT | 5765 | HTTP port the Flask app binds to |
SUBLARR_API_KEY | (empty) | Optional API key for X-Api-Key header. Empty = no auth required |
SUBLARR_CORS_ORIGINS | http://localhost:5173,http://localhost:5765 | Comma-separated list of allowed CORS / WebSocket origins. Set * only in fully trusted environments |
| Variable | Default | Description |
|---|---|---|
SUBLARR_MEDIA_PATH | /media | Root path of your media library (must match a Docker volume mount) |
SUBLARR_CONFIG_DIR | /config | Sublarr’s persistent config directory (database, backups, logs) |
Database
Section titled “Database”| Variable | Default | Description |
|---|---|---|
SUBLARR_DB_PATH | /config/sublarr.db | SQLite database path (used when DATABASE_URL is empty) |
SUBLARR_DATABASE_URL | (empty) | Full SQLAlchemy URL (e.g. postgresql://user:pw@host/db). Wins over DB_PATH when set |
SUBLARR_REDIS_URL | (empty) | Redis URL (e.g. redis://redis:6379/0). Empty = in-process queue + cache |
Logging
Section titled “Logging”| Variable | Default | Description |
|---|---|---|
SUBLARR_LOG_LEVEL | INFO | DEBUG, INFO, WARNING, ERROR |
SUBLARR_LOG_FILE | /config/sublarr.log | Log file path. The image sets this so the log lands on the persistent volume; point it elsewhere only if you mount /config differently. A source checkout defaults to the relative log/sublarr.log instead |
SUBLARR_LOG_FORMAT | text | text or json (structured for log aggregators like Loki) |
Telemetry
Section titled “Telemetry”| Variable | Default | Description |
|---|---|---|
SUBLARR_STATS_ENDPOINT | https://stats.sublarr.de/v1/ping | Where anonymous usage statistics are sent. Set to an empty string to disable sending entirely, regardless of the in-app consent toggle, or point it at your own collector. Read before the database exists, so it works on a first boot. See Usage Statistics |
Deployment topology (read straight from the environment, not part of the config)
Section titled “Deployment topology (read straight from the environment, not part of the config)”| Variable | Default | Description |
|---|---|---|
SUBLARR_SCHEDULER_ROLE | primary | primary runs the background scheduler; disabled suspends it so a replica only serves API/UI traffic. Any other value fails the start deliberately. Only relevant if you run more than one container against one database — see Scheduler |
Container conventions (linuxserver-style, not Sublarr-internal)
Section titled “Container conventions (linuxserver-style, not Sublarr-internal)”| Variable | Default | Description |
|---|---|---|
PUID / PGID | 1000 | UID/GID the container process runs as. Pick the IDs that own your /media and /config volumes |
Why this list is short
Section titled “Why this list is short”The only values that need to be set before Sublarr can boot, write its database, and accept its first HTTP request live in the table above. Everything else — every provider API key, every translation backend toggle, every scan/cleanup/upgrade option, every notification URL — is runtime-changeable through the UI. Putting it all in the database makes configuration:
- Discoverable — every option has a label, help text, and validation in the UI; you don’t need to grep this page to find what to set.
- Per-environment correct —
Settings → Backup → Restorecarries config across hosts; you don’t re-write a 200-line.envfor every machine. - Recoverable — a typo in a UI field shows an inline error before
it persists; a typo in
.envonly surfaces when the container fails to start.
Where everything else moved
Section titled “Where everything else moved”If you used to set SUBLARR_<X> in your .env, here is where the same
setting now lives in the UI:
| Old environment variable group | Now configured at |
|---|---|
SUBLARR_TRANSLATION_* | Settings → Translation |
SUBLARR_OLLAMA_URL, SUBLARR_OLLAMA_MODEL | Settings → Translation → Backends |
SUBLARR_*_API_KEY (OpenSubtitles, Jimaku, SubDL, SubsDump, …) | Settings → Providers → API Keys |
SUBLARR_PROVIDER_* (priorities, timeouts, rate limits) | Settings → Providers |
SUBLARR_SONARR_*, SUBLARR_RADARR_* | Settings → Sonarr / Radarr |
SUBLARR_JELLYFIN_*, SUBLARR_MEDIA_SERVERS_JSON | Settings → Media Servers |
SUBLARR_WANTED_*, SUBLARR_WEBHOOK_* | Settings → Automation |
SUBLARR_UPGRADE_* | Settings → Automation → Upgrades |
SUBLARR_REMUX_* | Settings → Automation → Stream Removal |
SUBLARR_AUTO_CLEANUP_*, SUBLARR_SUBTITLE_TRASH_* | Settings → Automation → Cleanup |
SUBLARR_HI_*, SUBLARR_FORCED_*, SUBLARR_CREDIT_*, SUBLARR_OP_WINDOW_* | Settings → Translation |
SUBLARR_SUBTITLE_* (naming) | Settings → Media Management |
SUBLARR_SCAN_* | Settings → Media Management → Scanning |
SUBLARR_STANDALONE_*, SUBLARR_TMDB_*, SUBLARR_TVDB_* | Settings → Library Sources |
SUBLARR_NOTIFY_*, SUBLARR_NOTIFICATION_URLS_JSON | Settings → Notifications |
SUBLARR_CIRCUIT_BREAKER_* | Settings → Providers → Resilience |
SUBLARR_BACKUP_* (auto-backup) | Settings → General → Backup |
SUBLARR_INTERFACE_LANGUAGE, SUBLARR_ITEMS_PER_PAGE, SUBLARR_DEFAULT_LIBRARY_*, SUBLARR_DATETIME_FORMAT | Settings → General |
SUBLARR_QUIET_HOURS_* | Settings → General → Quiet Hours |
SUBLARR_DISK_WARNING_* | Settings → General → Disk Monitoring |
SUBLARR_SESSION_TIMEOUT_*, SUBLARR_MAX_LOGIN_ATTEMPTS, SUBLARR_LOCKOUT_DURATION_*, SUBLARR_ALLOWED_IP_RANGES | Settings → General → Authentication |
SUBLARR_PLUGINS_DIR, SUBLARR_PLUGIN_HOT_RELOAD | Settings → Plugins |
SUBLARR_AUTO_SYNC_*, SUBLARR_FFMPEG_TIMEOUT, SUBLARR_MAX_CONCURRENT_*, SUBLARR_MAX_SUBTITLE_FILE_SIZE_KB | Settings → Media Management |
SUBLARR_WHISPER_* | Settings → Translation → Whisper |
SUBLARR_PATH_MAPPING | Settings → Sonarr / Radarr → Path Mapping |
If a setting you used to rely on is missing from the UI, please open a GitHub issue — every SUBLARR_* variable that ever shipped has an equivalent UI control.
Minimal .env example
Section titled “Minimal .env example”Copy this into .env next to your docker-compose.yml:
# UID/GID of the user that owns /media and /config volumesPUID=1000PGID=1000
# Optional — uncomment to enable API-key auth# SUBLARR_API_KEY=change-me-to-a-long-random-string
# Optional — only set if you mounted /media or /config differently# SUBLARR_MEDIA_PATH=/media# SUBLARR_CONFIG_DIR=/config
# Optional — set if running on a non-default port behind a reverse proxy# SUBLARR_PORT=5765# SUBLARR_CORS_ORIGINS=https://sublarr.example.com
# Optional — switch to PostgreSQL# SUBLARR_DATABASE_URL=postgresql://sublarr:pw@db:5432/sublarr
# Optional — switch to Redis-backed job queue + provider cache# SUBLARR_REDIS_URL=redis://redis:6379/0That’s it. After the first start, open http://<HOST_IP>:5765, complete the onboarding wizard, and configure everything else through the UI.