Configuration files allow you to set default options for yt-dlp without having to specify them on the command line every time. yt-dlp loads configuration from multiple locations in a specific order.
Configuration File Locations yt-dlp searches for configuration files in the following locations (in order of priority):
1. Main Configuration The file specified with --config-locations:
yt-dlp --config-locations /path/to/custom/config URL # Read from stdin yt-dlp --config-locations - URL
2. Portable Configuration Recommended for portable installations If using a binary:
yt-dlp.conf in the same directory as the binary
If running from source:
yt-dlp.conf in the parent directory of yt_dlp
This is ideal for portable installations where you want the configuration to travel with the executable.
3. Home Configuration
yt-dlp.conf in the home path given to -PIf -P is not given, the current directory is searched
4. User Configuration Recommended locations:
${XDG_CONFIG_HOME}/yt-dlp/config${XDG_CONFIG_HOME}/yt-dlp.conf${XDG_CONFIG_HOME}/yt-dlp/config.txt Fallback locations:
~/.yt-dlp/config~/yt-dlp.conf~/yt-dlp.conf.txt~/.yt-dlp/config.txt ${XDG_CONFIG_HOME} defaults to ~/.config if unset
Recommended locations:
${APPDATA}/yt-dlp/config${APPDATA}/yt-dlp.conf${APPDATA}/yt-dlp/config.txt Fallback locations:
~/yt-dlp.conf~/yt-dlp.conf.txt~/.yt-dlp/config~/.yt-dlp/config.txt ${APPDATA} typically points to C:\Users\<username>\AppData\Roaming
5. System Configuration Linux/macOS only:
/etc/yt-dlp.conf/etc/yt-dlp/config/etc/yt-dlp/config.txt
If --ignore-config is found in the system configuration file, user configuration is not loaded (for backward compatibility).
Configuration File Syntax Configuration files use the same options as command line switches:
Basic Rules
One option per line No whitespace after - or --Comments start with #Quote values when necessary (as in a shell)
Example Configuration Basic Config
Advanced Config
Audio Extraction Config
# Lines starting with # are comments # Always extract audio -x # Copy the mtime --mtime # Use this proxy --proxy 127.0.0.1:3128 # Save all videos under YouTube directory in your home -o ~/YouTube/% ( title ) s.% ( ext ) s
Configuration File Encoding Configuration files are decoded according to:
UTF BOM if presentSystem locale encoding otherwise
Specifying Encoding To force a specific encoding, add this as the first line :
Examples:
There must be no characters before the encoding declaration, not even spaces or BOM.
Ignoring Configuration Files Disable configuration file loading:
# Ignore all configuration files for this run yt-dlp --ignore-config URL # Alias yt-dlp --no-config URL
Partial Ignore If --ignore-config is found inside a configuration file:
No further configuration files are loaded
Useful for preventing cascading configs
Exclude Specific Locations # Don't load custom configs yt-dlp --no-config-locations URL
Multiple Configuration Files Load additional configuration files:
# Load specific config file(s) yt-dlp --config-locations /path/to/config1 --config-locations /path/to/config2 URL # Can be used inside other config files # In config file: --config-locations /path/to/another/config
Practical Configuration Examples Default Quality Settings ~/.config/yt-dlp/config
Audio Downloads
# Video quality -f bestvideo[height < =1080]+bestaudio/best[height < =1080] # Prefer free formats --prefer-free-formats # Merge to mkv --merge-output-format mkv
Organization and Archiving # Download archive (avoid re-downloading) --download-archive ~/.yt-dlp-archive.txt # Organized output -o "%(uploader)s/%(playlist|)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s" # Write metadata files --write-info-json --write-description --write-thumbnail
# Concurrent downloads --concurrent-fragments 5 # Retry configuration --retries 10 --fragment-retries 10 # Rate limiting (be nice to servers) --limit-rate 5M # Sleep between downloads --sleep-interval 3 --max-sleep-interval 10
Subtitle Preferences # Download subtitles --write-subs --write-auto-subs # Languages (regex supported) --sub-langs "en.*,ja" # Embed in video --embed-subs # Convert format --convert-subs srt
Post-Processing # Embed metadata --embed-metadata --embed-thumbnail --embed-chapters # SponsorBlock integration --sponsorblock-mark all --sponsorblock-remove sponsor,intro,outro # Execute after download --exec "notify-send 'Download complete' '%(title)s'"
Per-Site Configuration While yt-dlp doesn’t have built-in per-site configs, you can use shell aliases:
Bash/Zsh (~/.bashrc or ~/.zshrc)
PowerShell (Profile)
alias yt-music = 'yt-dlp --config-locations ~/.config/yt-dlp/music.conf' alias yt-archive = 'yt-dlp --config-locations ~/.config/yt-dlp/archive.conf' alias yt-quick = 'yt-dlp -f worst'
Environment Variables Variable Syntax
UNIX : ${VARIABLE} or $VARIABLEWindows : %VARIABLE%yt-dlp allows UNIX-style variables on Windows for path options
Common Variables
${HOME} - User home directory${XDG_CONFIG_HOME} - Config directory (defaults to ~/.config)${XDG_CACHE_HOME} - Cache directory (defaults to ~/.cache)
${USERPROFILE} - User profile directory (typically C:\Users\<user>)${APPDATA} - Application data directory (${USERPROFILE}\AppData\Roaming)${HOME} - Falls back to ${USERPROFILE} or ${HOMEDRIVE}${HOMEPATH} Using Variables in Config # Cross-platform paths -o "${ HOME }/Videos/%(title)s.%(ext)s" # Cache directory --cache-dir "${ XDG_CACHE_HOME }/yt-dlp" # Windows example -P "${ USERPROFILE }\Downloads\YouTube"
Debugging Configuration See which configuration files are loaded:
# Verbose output shows config loading yt-dlp --verbose URL # Output will include: # [debug] Command-line config: [...] # [debug] User config: [...] # [debug] Configuration loaded from: /path/to/config
Best Practices Minimal Config
Power User Config
# ~/.config/yt-dlp/config # Keep it simple - only essentials -f bestvideo+bestaudio/best -o "~/Videos/%(title)s [%(id)s].%(ext)s" --download-archive ~/.yt-dlp-archive.txt
Troubleshooting Config Not Loading # Check if config file exists ls -la ~/.config/yt-dlp/config # Verify with verbose mode yt-dlp --verbose URL 2>&1 | grep -i config # Test with explicit config location yt-dlp --config-locations ~/.config/yt-dlp/config URL
Option Conflicts # Command line options override config file yt-dlp -f worst URL # Overrides config's format setting # Use --ignore-config to bypass all configs yt-dlp --ignore-config -f best URL
Syntax Errors Common mistakes:
# ❌ WRONG - space after dash - o "~/Videos/%(title)s.%(ext)s" # ✅ CORRECT -o "~/Videos/%(title)s.%(ext)s" # ❌ WRONG - unquoted path with spaces -o ~/My Videos/% ( title ) s.% ( ext ) s # ✅ CORRECT -o "~/My Videos/%(title)s.%(ext)s"