Environment Variables Reference
This document provides a comprehensive reference for all environment variables supported by Youtarr.
Table of Contents
- Required Variables
- Application Access
- Database Configuration
- Authentication
- YouTube Cookies
- User and Permissions
- Output Directory
- Platform Deployment
- Development and Debugging
- Docker Configuration
- Gluetun Integration
Required Variables
YOUTUBE_OUTPUT_DIR
Required: Yes
Default: ./downloads
Description: Directory on the host machine where downloaded YouTube videos will be stored
Example Values:
- Linux/Mac:
/mnt/media/youtubeor/home/user/videos/youtube - Windows:
C:/Media/YouTube(use forward slashes) - Synology NAS:
/volume1/media/youtube
Important Notes:
- This path must exist on your host system before starting the containers
- Ensure the directory has appropriate write permissions for the configured UID/GID
- For network storage, mount the storage before starting Youtarr
Application Access
YOUTARR_HOST_PORT
Required: No
Default: 3087
Description: Host port mapped to the Youtarr web interface. The container still listens on port 3011.
Example: YOUTARR_HOST_PORT=8087
Note: The bundled start scripts use this value when polling /setup/status and printing first-time setup URLs.
Database Configuration
Internal Database (Default)
When using the bundled MariaDB container, these variables typically use their defaults:
DB_HOST
Required: No
Default: youtarr-db (the internal container name, set by docker-compose; the application itself falls back to localhost when the variable is unset)
Description: Database hostname or IP address
Example: 192.168.1.100 (for external database)
DB_PORT
Required: No
Default: 3321 for the internal database (docker-compose.yml), 3306 for external databases (docker-compose.external-db.yml)
Description: Database port number
Note: The bundled MariaDB container listens on 3321 inside the Docker network only and is not published to the host. When pointing Youtarr at an external MariaDB/MySQL instance, the default drops to the standard 3306; override it in .env if your external database listens elsewhere.
DB_USER
Required: No
Default: root
Description: Database username
Note: If switching from root, ensure MYSQL_USER is configured in docker-compose.yml
DB_PASSWORD
Required: No
Default: 123qweasd
Description: Database password
Security: Change this in production environments
DB_NAME
Required: No
Default: youtarr
Description: Database name for Youtarr DB
DB_ROOT_PASSWORD
Required: Only for internal database setup
Default: 123qweasd
Description: Root password for MariaDB container
Note: Only used when creating the internal database container
External Database Setup
To use an external database:
- Uncomment and configure DB_HOST, DB_PORT, DB_USER, DB_PASSWORD in your .env file
- Ensure the external database has utf8mb4 character set support
- See docs/platforms/external-db.md for detailed setup
Authentication
AUTH_ENABLED
Required: No
Default: true
Options: true, false
Description: Enable/disable built-in authentication
Warning: Never set to false when exposed to the internet
Use Cases for Disabling:
- When only using Youtarr in an environment that is not exposed to the internet
- When behind a VPN
- When using reverse proxy with authentication
- Platform deployments with external auth (e.g., Cloudflare Access)
Note: The RSS feed still requires the secret in its URL when this is false.
EXTERNAL_API_ENABLED
Required: No
Default: false
Options: true, false
Description: Enables the versioned /external-api/v1 integration API when set to true
Security: External API routes always require a non-legacy x-api-key, even when AUTH_ENABLED=false
Set this to true only after the external trust boundary, key policy, and
reverse-proxy rules have been reviewed. The namespace is disabled by default.
The routes remain protected until an administrator has assigned an API key an
external role and policy. Existing API keys migrate as legacy_download and
cannot use the versioned API. For endpoint-only public access, keep the Youtarr
origin port private and publish only the exact v1 path through a TLS reverse
proxy. Exposing the complete port also exposes unrelated application routes; see
Youtarr External API.
EXTERNAL_API_WORK_CONCURRENCY
Required: No
Default: 2
Options: 1 or 2 (larger values are capped at 2)
Description: How many expensive External API tasks run at once: video-detail
lookups, channel provisioning, and video deletion. Download jobs are queued
separately through Youtarr's normal download queue.
EXTERNAL_API_WORK_QUEUE
Required: No
Default: 20
Options: 0-100 (larger values are capped at 100)
Description: How many External API tasks may wait for a free slot. When the
queue is full, video-detail lookups return 503 and approved requests stay
approved until the next background sweep.
AUTH_PRESET_USERNAME
Required: No Default: None Description: Pre-configured admin username for automated deployments Validation: 1-32 characters, no leading/trailing spaces
AUTH_PRESET_PASSWORD
Required: No Default: None Description: Pre-configured admin password for automated deployments Validation: 8-64 characters
Important Notes:
- These override any existing credentials in config.json
- If not set, credentials must be configured through the web UI using the one-time setup token from the logs or
config/setup-token - Useful for deployment environments where you want to skip the browser setup wizard entirely.
TRUST_PROXY
Required: No
Default: true (backwards-compatible with existing reverse-proxy deployments)
Options: true, false, a hop count such as 1, or an Express trust-proxy value such as loopback
Description: Controls whether Express trusts proxy headers such as X-Forwarded-For
Recommendations:
- Set
TRUST_PROXY=falsewhen Youtarr is exposed directly without a reverse proxy - Leave unset only if you want the historical Express proxy-header trust behavior; Youtarr's rate-limit, session, and setup audit IPs will still key on the direct peer IP until
TRUST_PROXYis explicitly configured - Set
TRUST_PROXY=1only when Youtarr is behind exactly one trusted reverse proxy and you want per-client rate limits - Prefer the exact proxy IP/subnet over broad
true; the origin must not be reachable in a way that lets a client bypass the trusted proxy
YouTube Cookies
YOUTARR_COOKIES_FILE
Required: No
Default: Unset (use cookies uploaded through Settings)
Description: Absolute path inside the container to an externally maintained
Netscape cookie file, up to 1 MB. Requires Enable Cookies in Settings. Takes
precedence over uploaded cookies without modifying them. New operations use
private copies checked by yt-dlp. If the file is missing, unreadable, or rejected,
operations continue without cookies and a warning appears in Settings and logs.
A usable replacement restores cookie use automatically. Validation checks file
format, not whether YouTube accepts the session.
Example: YOUTARR_COOKIES_FILE=/app/config/cookies.external.txt
Setup: Put the file at config/cookies.external.txt and set this variable
in .env to use the existing mount without editing Compose. See
External Cookie File.
User and Permissions
YOUTARR_UID
Required: No
Default: 0 (root)
Recommended: 1000 (typical first user on Linux)
Description: User ID for running Youtarr inside the container
YOUTARR_GID
Required: No
Default: 0 (root)
Recommended: 1000
Description: Group ID for running Youtarr inside the container
Important Setup Steps:
Note: The /path/to/youtube/videos is just an example. Use the path you have configured in your .env file.
- Create required directories:
mkdir -p config jobs server/images /path/to/youtube/videos - Set ownership to match UID/GID:
sudo chown -R 1000:1000 ./config ./jobs ./server/images
sudo chown -R 1000:1000 /path/to/youtube/videos
Affected Directories:
config/*- Configuration filesjobs/*- Job state and artifactsserver/images/*- Thumbnails and cache${YOUTUBE_OUTPUT_DIR}- Downloaded videos
Output Directory
OUTPUT_DIR_HEALTHCHECK_TIMEOUT
Required: No
Default: 10
Format: A whole number of seconds from 1 to 3600, such as 45.
Description: Before each download, Youtarr writes and deletes a small probe file in the output directory, so a stale or unmounted share fails the job right away instead of hanging it. This is how long that check may take before the job fails with "Output directory health check timed out". The default is enough for local disks and most network shares. If the output directory is on a slow but healthy share (for example NFS backed by disks that spin up on demand), raise it. Only this check is affected, and a larger value also means a truly dead mount takes that much longer to fail each job in a sweep. A value outside the range, or one that is not a whole number, logs a warning and uses the default.
Note: See NFS Output Directory Considerations for mount options that help with stale shares.
Platform Deployment
DATA_PATH
Required: No (Platform-specific)
Default: None
Description: Override video storage path inside container
Example: /storage/rclone/storagebox/youtube
Used By: Elfhosted and similar platform deployments. Most users will never need to use this setting.
Behavior:
- When set, consolidates all data under
/app/config/ - Creates platform-specific subdirectories
- Internally the container will write to DATA_PATH instead of the default of
/usr/src/app/data/
PLEX_URL
Required: No
Default: None
Description: Pre-configured Plex server URL
Example: http://plex:32400
Note: When set inside the container, it takes precedence over plexUrl, plexIP, plexPort and plexViaHttps from config.json. It is also copied into plexUrl when config.json is first created.
Not passed through by default: the bundled docker-compose.yml and docker-compose.external-db.yml do not forward PLEX_URL into the container, so setting it in .env alone has no effect. Either add it to the youtarr service's environment: section:
environment:
PLEX_URL: ${PLEX_URL:-}
or, for a standard install, set plexUrl in config/config.json instead, which needs no compose change. Only docker-compose.dev.yml forwards PLEX_URL out of the box. DATA_PATH is in the same position: it is commented out in docker-compose.yml and must be added to the service's environment: to take effect.
Jellyfin and Emby have no environment variables. Their playlist-sync settings (URL, API key, user ID) are managed in
config/config.jsonthrough the web UI under Settings, not via env vars. There is noJELLYFIN_URLorEMBY_URLequivalent toPLEX_URL.
Development and Debugging
LOG_LEVEL
Required: No
Default: info
Options: warn, info, debug
Description: Controls logging verbosity
warn: Minimal logging, errors and warnings onlyinfo: Standard logging for productiondebug: Verbose logging for troubleshooting Note: Settings -> Logging can override this while Youtarr runs, without a restart. Its Default option usesLOG_LEVEL.
LOG_FILE_MAX_SIZE
Required: No
Default: 10MB
Format: A whole number of MB or GB, such as 25MB or 1GB. A number without a unit means MB.
Description: Youtarr writes its log to rolling files in config/logs/ (youtarr.1.log, youtarr.2.log, ...; the highest number is the current file) as well as to the console. When the current file reaches this size, a new one starts. An invalid value logs a warning and uses the default.
LOG_FILE_MAX_COUNT
Required: No
Default: 5
Description: How many older log files to keep in addition to the current one. When a new file starts, the oldest files beyond this count are deleted, so with the defaults the log files never use more than about 60 MB. Must be a whole number of 1 or more; an invalid value logs a warning and uses the default.
TZ
Required: No
Default: UTC
Description: Timezone for console log timestamps, scheduled jobs, and cleanup tasks
Format: IANA timezone (e.g., America/Los_Angeles, Europe/Paris)
Note: Console timestamps include the numeric UTC offset and follow daylight-saving changes for the configured timezone. The provided Compose files default to UTC when TZ is unset.
YOUTARR_IMAGE
Required: No
Default: dialmaster/youtarr:latest
Description: Docker image selection
Development: Set to youtarr-dev:latest for local builds
Note: Development scripts handle this automatically
Docker Configuration
These variables are used by docker-compose.yml but not directly by the application:
Container Naming
- Container names are automatically prefixed with the directory name
- Default containers:
youtarr,youtarr-db
Network Configuration
- Network:
youtarr-network(internal bridge) - Application port: 3087 (host) → 3011 (container)
- Database port: 3321 inside the Docker network only
Gluetun Integration
Only docker-compose.gluetun.yml, the optional VPN override, reads these variables; see GLUETUN_INTEGRATION.md. They're passed straight through to the Gluetun container, so the Gluetun wiki has the full details.
VPN_SERVICE_PROVIDER
Required: Yes, when the Gluetun override is in use
Description: Your VPN provider's name as Gluetun spells it, for example mullvad, protonvpn or custom.
Note: See https://github.com/qdm12/gluetun-wiki/tree/main/setup/providers for a list of supported providers and setup. May require modifying your Docker Compose file to add additional needed settings (based on provider).
Wireguard
WIREGUARD_PRIVATE_KEY
Required: Yes Description: The Wireguard private key your provider gives you.
WIREGUARD_ADDRESSES
Required: Yes
Description: The WireGuard address your provider gives you, for example 10.64.222.21/32.
WIREGUARD_PRESHARED_KEY
Required: Only if your provider gives you one Description: The preshared Wireguard key your provider gives you.
WIREGUARD_MTU
Required: No Default: Gluetun's default if unset. Description: Used for MTU tuning for better WireGuard speeds. Note: See https://github.com/qdm12/gluetun-wiki/blob/main/setup/options/wireguard.md for info.
FIREWALL_OUTBOUND_SUBNETS
Required: No, unless Youtarr needs to reach Plex, Jellyfin, Emby or an external database outside the VPN
Description: Comma-separated subnets that Youtarr can reach directly instead of through the VPN (like Plex, Jellyfin, & Emby on your LAN). host.docker.internal is the Docker bridge gateway, so include 172.17.0.0/16 (or your bridge subnet) if you use it. They can't overlap the VPN tunnel's address range.
Format: CIDR, comma-separated (e.g., 192.168.1.0/24,172.17.0.0/16)
Note: See https://github.com/qdm12/gluetun-wiki/blob/main/setup/options/firewall.md for more info.
GLUETUN_CONTAINER_NAME
Required: No
Default: youtarr-gluetun
Description: Gluetun's container name.
Note: Useful if running multiple Gluetun containers.
Best Practices
Security
- Always change default passwords in production
- Never disable AUTH_ENABLED for internet-exposed instances
- Use HTTPS/VPN for remote access; plain HTTP is intended for localhost and trusted LAN access only
- Set TRUST_PROXY=false when directly exposing Youtarr without a reverse proxy
- Use non-root UID/GID (set YOUTARR_UID=1000)
- Existing Youtarr users that were previously using the default root GID/UID (0:0) will need to completely stop Youtarr and ensure that directory permissions are updated if they want to switch from root UID/GID to non-root
- Secure your .env file with appropriate permissions:
chmod 600 .env
Performance
- Use local storage when possible for better performance
- Set appropriate LOG_LEVEL (
infofor production,debugonly when needed) - Configure timezone to match your location for accurate scheduling
Maintenance
- Backup your .env file along with your configuration
- Document any custom variables for your deployment
- Test configuration changes in a development environment first
Environment Variable Priority
Variables are processed in this order (highest to lowest priority):
- Environment variables set at runtime
- Variables defined in .env file
- Default values in docker-compose.yml
- Application defaults
Troubleshooting
Permission Errors
If you see "Permission denied" errors:
- Check YOUTARR_UID/GID match your file ownership
- Verify directory permissions with
ls -la - Fix ownership:
sudo chown -R ${UID}:${GID} ./config ./jobs ./server/images
Database Connection Issues
For the bundled database:
- Check the container is running:
docker compose ps youtarr-db - Check logs:
docker compose logs youtarr-db - Confirm credentials from inside the container:
docker compose exec youtarr-db mysql -u ${DB_USER:-root} -p ${DB_NAME:-youtarr}
For an external database:
- Verify
DB_HOSTis reachable from the Youtarr container - Check
DB_PORTis open between Youtarr and the database host - Confirm credentials with:
mysql -h ${DB_HOST} -P ${DB_PORT} -u ${DB_USER} -p
Authentication Problems
- If locked out, set AUTH_PRESET_USERNAME and AUTH_PRESET_PASSWORD
- These override existing credentials on each restart
- Remove them after regaining access to prevent continued override (or leave them in place to prevent any updates to credentials via the web UI)