Skip to main content

Environment Variables Reference

This document provides a comprehensive reference for all environment variables supported by Youtarr.

Table of Contents​

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/youtube or /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:

  1. Uncomment and configure DB_HOST, DB_PORT, DB_USER, DB_PASSWORD in your .env file
  2. Ensure the external database has utf8mb4 character set support
  3. 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=false when 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_PROXY is explicitly configured
  • Set TRUST_PROXY=1 only 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.

  1. Create required directories:
    mkdir -p config jobs server/images /path/to/youtube/videos
  2. 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 files
  • jobs/* - Job state and artifacts
  • server/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.json through the web UI under Settings, not via env vars. There is no JELLYFIN_URL or EMBY_URL equivalent to PLEX_URL.

Development and Debugging​

LOG_LEVEL​

Required: No Default: info Options: warn, info, debug Description: Controls logging verbosity

  • warn: Minimal logging, errors and warnings only
  • info: Standard logging for production
  • debug: Verbose logging for troubleshooting Note: Settings -> Logging can override this while Youtarr runs, without a restart. Its Default option uses LOG_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​

  1. Always change default passwords in production
  2. Never disable AUTH_ENABLED for internet-exposed instances
  3. Use HTTPS/VPN for remote access; plain HTTP is intended for localhost and trusted LAN access only
  4. Set TRUST_PROXY=false when directly exposing Youtarr without a reverse proxy
  5. 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
  6. Secure your .env file with appropriate permissions:
    chmod 600 .env

Performance​

  1. Use local storage when possible for better performance
  2. Set appropriate LOG_LEVEL (info for production, debug only when needed)
  3. Configure timezone to match your location for accurate scheduling

Maintenance​

  1. Backup your .env file along with your configuration
  2. Document any custom variables for your deployment
  3. Test configuration changes in a development environment first

Environment Variable Priority​

Variables are processed in this order (highest to lowest priority):

  1. Environment variables set at runtime
  2. Variables defined in .env file
  3. Default values in docker-compose.yml
  4. Application defaults

Troubleshooting​

Permission Errors​

If you see "Permission denied" errors:

  1. Check YOUTARR_UID/GID match your file ownership
  2. Verify directory permissions with ls -la
  3. Fix ownership: sudo chown -R ${UID}:${GID} ./config ./jobs ./server/images

Database Connection Issues​

For the bundled database:

  1. Check the container is running: docker compose ps youtarr-db
  2. Check logs: docker compose logs youtarr-db
  3. Confirm credentials from inside the container: docker compose exec youtarr-db mysql -u ${DB_USER:-root} -p ${DB_NAME:-youtarr}

For an external database:

  1. Verify DB_HOST is reachable from the Youtarr container
  2. Check DB_PORT is open between Youtarr and the database host
  3. Confirm credentials with: mysql -h ${DB_HOST} -P ${DB_PORT} -u ${DB_USER} -p

Authentication Problems​

  1. If locked out, set AUTH_PRESET_USERNAME and AUTH_PRESET_PASSWORD
  2. These override existing credentials on each restart
  3. Remove them after regaining access to prevent continued override (or leave them in place to prevent any updates to credentials via the web UI)