Skip to main content

Environment Variables in yt-dlp

Environment variables in yt-dlp provide a way to configure behavior without using command-line options or configuration files.

Environment Variable Syntax​

Cross-Platform Compatibility​

Environment variables are normally specified as:

  • UNIX: ${VARIABLE} or $VARIABLE
  • Windows: %VARIABLE%

However, yt-dlp allows using UNIX-style variables on Windows for path-like options (e.g. --output, --config-location).

Note: In this documentation, environment variables are always shown as ${VARIABLE} regardless of platform.

Default Values​

XDG Base Directory Specification​

If unset, these variables have the following defaults:

  • ${XDG_CONFIG_HOME} defaults to ~/.config
  • ${XDG_CACHE_HOME} defaults to ~/.cache

Home Directory Resolution​

On Windows:

  • ~ points to ${HOME} if present
  • Otherwise uses ${USERPROFILE} or ${HOMEDRIVE}${HOMEPATH}
  • ${USERPROFILE} generally points to C:\Users\<user name>
  • ${APPDATA} points to ${USERPROFILE}\AppData\Roaming

Plugin Control​

YTDLP_NO_PLUGINS​

Disable loading plugins entirely:

export YTDLP_NO_PLUGINS=1
yt-dlp "https://example.com/video"
set YTDLP_NO_PLUGINS=1
yt-dlp "https://example.com/video"

YTDLP_NO_LAZY_EXTRACTORS​

Force disable lazy extractor loading:

export YTDLP_NO_LAZY_EXTRACTORS=1
yt-dlp "https://example.com/video"

Configuration Paths​

XDG_CONFIG_HOME​

Override default configuration directory:

export XDG_CONFIG_HOME="/custom/config/path"
yt-dlp "https://example.com/video"

This affects where yt-dlp looks for configuration files:

  • ${XDG_CONFIG_HOME}/yt-dlp.conf
  • ${XDG_CONFIG_HOME}/yt-dlp/config
  • ${XDG_CONFIG_HOME}/yt-dlp/config.txt

XDG_CACHE_HOME​

Override default cache directory:

export XDG_CACHE_HOME="/custom/cache/path"
yt-dlp "https://example.com/video"

Default cache location: ${XDG_CACHE_HOME}/yt-dlp

PATH Variables​

HOME​

Set custom home directory:

export HOME="/custom/home"
yt-dlp "https://example.com/video"

USERPROFILE (Windows)​

Windows user profile directory:

set USERPROFILE=C:\CustomUsers\username
yt-dlp "https://example.com/video"

APPDATA (Windows)​

Windows application data directory:

set APPDATA=C:\CustomAppData\Roaming
yt-dlp "https://example.com/video"

Practical Examples​

Portable Installation​

Create a portable yt-dlp setup:

# Set custom paths
export XDG_CONFIG_HOME="/portable/yt-dlp/config"
export XDG_CACHE_HOME="/portable/yt-dlp/cache"
export HOME="/portable/yt-dlp/home"

# Run yt-dlp
yt-dlp "https://example.com/video"

Disable Features​

# Disable plugins and lazy extractors
export YTDLP_NO_PLUGINS=1
export YTDLP_NO_LAZY_EXTRACTORS=1

yt-dlp "https://example.com/video"

Custom Configuration Location​

# Use custom config directory
export XDG_CONFIG_HOME="/opt/yt-dlp/config"

# yt-dlp will look for configs in:
# /opt/yt-dlp/config/yt-dlp.conf
# /opt/yt-dlp/config/yt-dlp/config
# /opt/yt-dlp/config/yt-dlp/config.txt

Priority Order​

Environment variables interact with other configuration methods in this priority order:

  1. Command-line options (highest priority)
  2. Configuration files
  3. Environment variables
  4. Default values (lowest priority)

Security Considerations​

Sensitive Information​

Avoid putting sensitive information in environment variables:

# DON'T do this
export YOUTUBE_PASSWORD="mysecretpassword"

# DO use configuration files or --netrc instead
yt-dlp --netrc "https://example.com/video"

System-Wide vs User-Specific​

Be careful with system-wide environment variables that might affect all users:

# User-specific (recommended)
echo 'export XDG_CONFIG_HOME="$HOME/.config"' >> ~/.bashrc

# System-wide (use with caution)
echo 'export XDG_CONFIG_HOME="/etc/yt-dlp"' >> /etc/environment