Skip to main content

Network Configuration

Configure yt-dlp's network behavior for optimal downloading performance and compatibility.

Basic Network Options​

Proxy Configuration​

Use HTTP/HTTPS/SOCKS proxy:

# HTTP proxy
yt-dlp --proxy "http://proxy.example.com:8080" "https://example.com/video"

# HTTPS proxy
yt-dlp --proxy "https://proxy.example.com:8080" "https://example.com/video"

# SOCKS proxy with authentication
yt-dlp --proxy "socks5://user:pass@127.0.0.1:1080" "https://example.com/video"

# Direct connection (no proxy)
yt-dlp --proxy "" "https://example.com/video"

Socket Timeout​

Set connection timeout:

# Wait 30 seconds before giving up
yt-dlp --socket-timeout 30 "https://example.com/video"

Source Address Binding​

Bind to specific network interface:

# Bind to specific IP address
yt-dlp --source-address 192.168.1.100 "https://example.com/video"

IP Version Control​

Force IPv4​

# Use only IPv4 connections
yt-dlp -4 "https://example.com/video"
yt-dlp --force-ipv4 "https://example.com/video"

Force IPv6​

# Use only IPv6 connections
yt-dlp -6 "https://example.com/video"
yt-dlp --force-ipv6 "https://example.com/video"

Client Impersonation​

Basic Impersonation​

# Impersonate Chrome browser
yt-dlp --impersonate chrome "https://example.com/video"

# Impersonate specific Chrome version
yt-dlp --impersonate chrome-110 "https://example.com/video"

# Impersonate Chrome on Windows 10
yt-dlp --impersonate chrome:windows-10 "https://example.com/video"

# Impersonate any available client
yt-dlp --impersonate "" "https://example.com/video"

List Available Targets​

# Show all available impersonation targets
yt-dlp --list-impersonate-targets

Note: Forcing impersonation for all requests may have a detrimental impact on download speed and stability.

File URL Support​

Enable File URLs​

# Enable file:// URLs (disabled by default for security)
yt-dlp --enable-file-urls "file:///path/to/video.mp4"

Security Warning: File URLs are disabled by default for security reasons. Only enable when necessary and from trusted sources.

SSL/TLS Configuration​

Certificate Validation​

# Suppress HTTPS certificate validation (not recommended)
yt-dlp --no-check-certificates "https://example.com/video"

# Allow connections to servers without RFC 5746 support
yt-dlp --legacy-server-connect "https://example.com/video"

Prefer Insecure Connections​

# Use unencrypted connection (YouTube only, not recommended)
yt-dlp --prefer-insecure "https://youtube.com/watch?v=VIDEO_ID"

Custom Headers​

Add HTTP Headers​

# Add custom User-Agent
yt-dlp --add-headers "User-Agent:My Custom Bot 1.0" "https://example.com/video"

# Add multiple headers
yt-dlp --add-headers "User-Agent:My Bot" --add-headers "Referer:https://example.com" "https://example.com/video"

# Add Authorization header
yt-dlp --add-headers "Authorization:Bearer TOKEN" "https://example.com/video"

Common Header Examples​

# Mobile user agent
yt-dlp --add-headers "User-Agent:Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)" "https://example.com/video"

# Desktop browser
yt-dlp --add-headers "User-Agent:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" "https://example.com/video"

Rate Limiting and Delays​

Request Delays​

# Wait between requests during extraction
yt-dlp --sleep-requests 1.5 "https://example.com/playlist"

# Wait before each download
yt-dlp --sleep-interval 5 "https://example.com/playlist"

# Random delay between 5-15 seconds
yt-dlp --sleep-interval 5 --max-sleep-interval 15 "https://example.com/playlist"

# Wait before subtitle downloads
yt-dlp --sleep-subtitles 2 "https://example.com/video"

Download Rate Limiting​

# Limit download rate to 1MB/s
yt-dlp --limit-rate 1M "https://example.com/video"

# Limit to 500KB/s
yt-dlp --limit-rate 500K "https://example.com/video"

Retry Configuration​

Basic Retries​

# Set number of retries (default: 10)
yt-dlp --retries 5 "https://example.com/video"

# Infinite retries
yt-dlp --retries infinite "https://example.com/video"

# File access retries
yt-dlp --file-access-retries 5 "https://example.com/video"

# Fragment retries for DASH/HLS
yt-dlp --fragment-retries 10 "https://example.com/video"

Retry Sleep Patterns​

# Linear backoff: start at 1s, increase by 1s each retry
yt-dlp --retry-sleep linear=1::1 "https://example.com/video"

# Exponential backoff: start at 1s, double each retry, max 60s
yt-dlp --retry-sleep exp=1:60:2 "https://example.com/video"

# Different patterns for different retry types
yt-dlp --retry-sleep linear=1::2 --retry-sleep fragment:exp=1:20 "https://example.com/video"

Network Troubleshooting​

Debug Network Traffic​

# Show all HTTP traffic
yt-dlp --print-traffic "https://example.com/video"

# Verbose output for debugging
yt-dlp --verbose "https://example.com/video"

Test Network Configuration​

# Test with simple video
yt-dlp --simulate --verbose "https://example.com/video"

# Test proxy configuration
yt-dlp --proxy "http://proxy:8080" --simulate "https://example.com/video"

Advanced Network Options​

Connection Pooling​

# Use requests library for persistent connections
yt-dlp --extractor-args "generic:impersonate=false" "https://example.com/video"

Fragment Downloads​

# Number of concurrent fragments for DASH/HLS
yt-dlp --concurrent-fragments 4 "https://example.com/video"

# Skip unavailable fragments
yt-dlp --skip-unavailable-fragments "https://example.com/video"

# Abort on unavailable fragments
yt-dlp --abort-on-unavailable-fragments "https://example.com/video"

Configuration Examples​

Corporate Network​

# Configuration for corporate environments
yt-dlp \
  --proxy "http://corporate-proxy:8080" \
  --socket-timeout 60 \
  --retries 3 \
  --retry-sleep linear=5::5 \
  --sleep-requests 2 \
  "https://example.com/video"

Slow Connection​

# Optimized for slow/unreliable connections
yt-dlp \
  --socket-timeout 120 \
  --retries infinite \
  --fragment-retries infinite \
  --retry-sleep exp=1:300:2 \
  --concurrent-fragments 1 \
  "https://example.com/video"

Privacy-Focused​

# Privacy-focused configuration
yt-dlp \
  --proxy "socks5://127.0.0.1:9050" \
  --add-headers "User-Agent:Mozilla/5.0 (Windows NT 10.0; rv:91.0) Gecko/20100101 Firefox/91.0" \
  --no-check-certificates \
  "https://example.com/video"