Configuration Files in yt-dlp

yt-dlp supports configuration files to store default options, making it easier to maintain consistent settings across downloads without repeating command-line arguments.

Configuration File Locations

yt-dlp loads configuration files from multiple locations in a specific order of precedence:

1. Main Configuration

The file specified with --config-location:

yt-dlp --config-location /path/to/config.conf 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

3. Home Configuration

• yt-dlp.conf in the home path given to -P
• If -P is not given, the current directory is searched

4. User Configuration

Platform-specific user configuration directories:

Linux/macOS (XDG-compliant):

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

Windows:

• ${APPDATA}/yt-dlp.conf
• ${APPDATA}/yt-dlp/config (recommended)
• ${APPDATA}/yt-dlp/config.txt

Universal:

• ~/yt-dlp.conf
• ~/yt-dlp.conf.txt
• ~/.yt-dlp/config
• ~/.yt-dlp/config.txt

5. System Configuration

• /etc/yt-dlp.conf
• /etc/yt-dlp/config
• /etc/yt-dlp/config.txt

Configuration File Format

Basic Syntax

Configuration files contain command-line options, one per line:

# 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 directory
-o ~/YouTube/%(title)s.%(ext)s

Important Rules

• No whitespace after - or -- (use -o, not - o)
• Quote when necessary as if it were a UNIX shell
• Comments start with #
• One option per line

Configuration File Examples

Basic Configuration

# Basic yt-dlp configuration

# Output template
-o %(uploader)s/%(title)s.%(ext)s

# Always write metadata
--write-info-json
--write-thumbnail

# Quality preferences
-f bestvideo+bestaudio/best

# Subtitle options
--write-subs
--sub-langs en,en-US

# Retry on errors
--retries 3

Advanced Configuration

# Advanced yt-dlp configuration

# Output organization
-o %(uploader)s/%(upload_date>%Y)s/%(title)s [%(id)s].%(ext)s

# Quality and format
-f bestvideo[height<=1080]+bestaudio/best[height<=1080]
--merge-output-format mp4

# Audio extraction settings
--extract-audio
--audio-format mp3
--audio-quality 192K

# Metadata and post-processing
--embed-metadata
--embed-thumbnail
--write-info-json
--write-description

# Archive downloaded videos
--download-archive ~/Downloads/archive.txt

# Network settings
--socket-timeout 30
--retries 5
--retry-sleep linear=1::2

# Subtitle handling
--write-subs
--write-auto-subs
--sub-langs en,en-US,en-GB
--embed-subs

# Thumbnail settings
--write-all-thumbnails
--convert-thumbnails jpg

# Progress display
--no-progress
--console-title

# Error handling
--ignore-errors
--no-abort-on-error

Platform-Specific Configurations

Windows Configuration

# Windows-specific configuration

# Use Windows-safe filenames
--windows-filenames

# Output to Downloads folder
-o C:/Users/%USERNAME%/Downloads/%(title)s.%(ext)s

# Use Windows proxy if needed
--proxy http://proxy.company.com:8080

# FFmpeg location (if not in PATH)
--ffmpeg-location C:/ffmpeg/bin/ffmpeg.exe

macOS Configuration

# macOS-specific configuration

# Use Downloads folder
-o ~/Downloads/%(title)s.%(ext)s

# Prefer free formats
--prefer-free-formats

# Use system certificate store
--no-check-certificates

Linux Configuration

# Linux-specific configuration

# Use XDG directories
-o ~/Videos/%(uploader)s/%(title)s.%(ext)s

# Prefer open formats
--prefer-free-formats
-S ext:webm:mp4

# Use system proxy settings
--proxy ""

Use Case-Specific Configurations

Music Download Configuration

# Music-focused configuration

# Extract audio only
--extract-audio
--audio-format mp3
--audio-quality 320K

# Music-specific metadata
--embed-metadata
--add-metadata

# Music organization
-o ~/Music/%(uploader)s/%(album|Unknown Album)s/%(track_number|00)s - %(title)s.%(ext)s

# Playlist handling for albums
--yes-playlist

Podcast Configuration

# Podcast download configuration

# Audio only
--extract-audio
--audio-format mp3

# Podcast organization
-o ~/Podcasts/%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s

# Include description
--write-description

# Playlist as single downloads
--no-playlist

Educational Content Configuration

# Educational content configuration

# High quality video
-f best[height<=1080]

# Include subtitles
--write-subs
--write-auto-subs
--sub-langs en
--embed-subs

# Organize by course
-o ~/Education/%(uploader)s/%(playlist)s/%(playlist_index)02d - %(title)s.%(ext)s

# Include all metadata
--write-info-json
--write-description
--embed-metadata

Archival Configuration

# Archival configuration

# Best quality available
-f best

# Save all metadata
--write-info-json
--write-description
--write-thumbnail
--write-all-thumbnails
--write-subs
--write-auto-subs
--sub-langs all

# Keep original formats
--no-post-overwrites

# Comprehensive organization
-o Archives/%(extractor)s/%(uploader)s/%(upload_date>%Y/%m)s/%(title)s [%(id)s].%(ext)s

# Use archive file
--download-archive ~/archives.txt

Configuration Management

Disabling Configuration

# Ignore all configuration files
yt-dlp --ignore-config URL

# Ignore only user and system configs
yt-dlp --no-config-locations URL

Multiple Configuration Files

# Load additional configuration
yt-dlp --config-locations ~/.yt-dlp/music.conf URL

# Load from stdin
echo "-f best" | yt-dlp --config-locations - URL

Configuration Debugging

# See what configuration is being loaded
yt-dlp --verbose URL 2>&1 | grep -i config

# Test configuration without downloading
yt-dlp --simulate --verbose URL

Configuration File Encoding

Encoding Detection

• Configuration files are decoded according to UTF BOM if present
• Falls back to system locale encoding
• Specify encoding at the beginning of file if needed

Custom Encoding

# coding: shift-jis
# This file uses Shift-JIS encoding

-o %(title)s.%(ext)s

UTF-8 with BOM

# UTF-8 encoded configuration
# Supports Unicode characters in paths and options

-o ~/Downloads/%(title)s.%(ext)s
--proxy http://プロキシ.example.com:8080

Best Practices

Organization

# Group related options together
# Network settings
--proxy 127.0.0.1:8080
--socket-timeout 30

# Output settings
-o %(title)s.%(ext)s
--restrict-filenames

# Quality settings
-f best
--merge-output-format mp4

Documentation

# Document your configuration choices
# This proxy is required for corporate network
--proxy http://proxy.company.com:8080

# Prefer MP4 for compatibility
--merge-output-format mp4

Modular Configurations

Create specialized configuration files for different purposes:

base.conf:

# Base configuration
--retries 3
--socket-timeout 30
-o %(title)s.%(ext)s

music.conf:

# Music-specific settings
--config-locations ~/.yt-dlp/base.conf
--extract-audio
--audio-format mp3
-o ~/Music/%(title)s.%(ext)s

Security Considerations

# Avoid putting passwords in configuration files
# Use --netrc or environment variables instead

# Instead of:
# --password mypassword

# Use:
--netrc

Troubleshooting Configuration

Common Issues

Option Not Working

# Check if option is correct
yt-dlp --help | grep option

# Verify configuration syntax
yt-dlp --verbose --simulate URL

Path Issues

# Use absolute paths in configuration
-o /full/path/to/%(title)s.%(ext)s

# Or properly escape paths
-o "~/Videos/%(title)s.%(ext)s"

Encoding Problems

# Specify encoding at the beginning
# coding: utf-8

# Use proper quotes for special characters
-o "%(title)s.%(ext)s"

Testing Configuration

# Test without downloading
yt-dlp --simulate --verbose URL

# Check final command line
yt-dlp --print-traffic URL 2>&1 | head