Skip to main content

Geo-Restriction Bypass in yt-dlp

Overcome geographical restrictions and access content from different regions using yt-dlp's geo-restriction bypass features.

Geo-Verification Proxy​

Basic Usage​

Use a proxy specifically for IP verification while downloading through your regular connection:

# Use proxy only for geo-verification
yt-dlp --geo-verification-proxy "http://proxy.example.com:8080" "https://example.com/video"

# Use SOCKS proxy for verification
yt-dlp --geo-verification-proxy "socks5://proxy.example.com:1080" "https://example.com/video"

How it works: The geo-verification proxy is used only to verify your IP address for geo-restricted sites. The actual downloading uses your regular connection (or the proxy specified by --proxy).

X-Forwarded-For Header Manipulation​

XFF Policy Options​

Control how the X-Forwarded-For HTTP header is used to bypass geographic restrictions:

# Default behavior (only when known to be useful)
yt-dlp --xff default "https://example.com/video"

# Never add X-Forwarded-For header
yt-dlp --xff never "https://example.com/video"

# Use specific IP address
yt-dlp --xff "203.0.113.1" "https://example.com/video"

# Use IP block in CIDR notation
yt-dlp --xff "203.0.113.0/24" "https://example.com/video"

# Use country code (ISO 3166-2)
yt-dlp --xff "US" "https://example.com/video"
yt-dlp --xff "GB" "https://example.com/video"
yt-dlp --xff "JP" "https://example.com/video"

Country Code Examples​

# United States
yt-dlp --xff "US" "https://example.com/video"

# United Kingdom
yt-dlp --xff "GB" "https://example.com/video"

# Germany
yt-dlp --xff "DE" "https://example.com/video"

# Japan
yt-dlp --xff "JP" "https://example.com/video"

# Canada
yt-dlp --xff "CA" "https://example.com/video"

# Australia
yt-dlp --xff "AU" "https://example.com/video"

Combined Approaches​

Proxy + XFF​

Combine different bypass methods for maximum effectiveness:

# Use proxy for actual connection and XFF for geo-spoofing
yt-dlp \
  --proxy "http://us-proxy.example.com:8080" \
  --xff "US" \
  "https://example.com/video"

# Different proxy for geo-verification
yt-dlp \
  --proxy "http://main-proxy.example.com:8080" \
  --geo-verification-proxy "http://us-proxy.example.com:8080" \
  --xff "US" \
  "https://example.com/video"

Legacy Options (Deprecated)​

These options are deprecated but still available for compatibility:

# Legacy geo-bypass (equivalent to --xff "default")
yt-dlp --geo-bypass "https://example.com/video"

# Disable geo-bypass (equivalent to --xff "never")
yt-dlp --no-geo-bypass "https://example.com/video"

# Country-specific bypass (equivalent to --xff "CODE")
yt-dlp --geo-bypass-country US "https://example.com/video"

# IP block bypass (equivalent to --xff "IP_BLOCK")
yt-dlp --geo-bypass-ip-block "203.0.113.0/24" "https://example.com/video"

Practical Examples​

Accessing US Content​

# Method 1: Use US proxy
yt-dlp --proxy "http://us-proxy.example.com:8080" "https://example.com/video"

# Method 2: Use XFF header with US IP
yt-dlp --xff "US" "https://example.com/video"

# Method 3: Combine both approaches
yt-dlp --proxy "http://us-proxy.example.com:8080" --xff "US" "https://example.com/video"

Multiple Region Strategy​

# Try different regions automatically using a script
regions=("US" "GB" "CA" "AU" "DE")
for region in "${regions[@]}"; do
    echo "Trying region: $region"
    if yt-dlp --xff "$region" --simulate "https://example.com/video" 2>/dev/null; then
        echo "Success with region: $region"
        yt-dlp --xff "$region" "https://example.com/video"
        break
    fi
done

Corporate Network Bypass​

# For networks with both corporate proxy and geo-restrictions
yt-dlp \
  --proxy "http://corporate-proxy:8080" \
  --geo-verification-proxy "http://external-proxy:8080" \
  --xff "US" \
  "https://example.com/video"

Advanced Techniques​

Custom IP Ranges​

# Use specific IP ranges known to work
yt-dlp --xff "8.8.8.0/24" "https://example.com/video"        # Google DNS range
yt-dlp --xff "1.1.1.0/24" "https://example.com/video"        # Cloudflare DNS range
yt-dlp --xff "208.67.222.0/24" "https://example.com/video"   # OpenDNS range

Testing Geo-Restrictions​

# Test if content is geo-restricted
yt-dlp --simulate --verbose "https://example.com/video"

# Test with different regions
yt-dlp --xff "US" --simulate "https://example.com/video"
yt-dlp --xff "GB" --simulate "https://example.com/video"

Debugging Geo-Issues​

# Verbose output to see geo-restriction details
yt-dlp --verbose --xff "US" "https://example.com/video"

# Print network traffic to debug headers
yt-dlp --print-traffic --xff "US" "https://example.com/video"

Site-Specific Considerations​

YouTube​

# YouTube geo-restrictions
yt-dlp --xff "US" "https://youtube.com/watch?v=VIDEO_ID"

BBC iPlayer​

# UK-specific content
yt-dlp --xff "GB" "https://bbc.co.uk/iplayer/episode/VIDEO_ID"

US Network Sites​

# US network content
yt-dlp --xff "US" "https://cbs.com/shows/video/VIDEO_ID"
yt-dlp --xff "US" "https://nbc.com/video/VIDEO_ID"

Troubleshooting​

Common Issues​

  1. Still geo-blocked: Try different regions or IP ranges
  2. Slow downloads: Geo-verification proxy might be slow
  3. Connection errors: Proxy might be unreliable

Debug Commands​

# Check if geo-restriction is the issue
yt-dlp --verbose --simulate "https://example.com/video"

# Test different bypass methods
yt-dlp --xff "US" --verbose --simulate "https://example.com/video"
yt-dlp --proxy "http://proxy:8080" --verbose --simulate "https://example.com/video"
yt-dlp --geo-verification-proxy "http://proxy.example.com:8080" "https://example.com/video"

# Use SOCKS proxy for verification
yt-dlp --geo-verification-proxy "socks5://proxy.example.com:1080" "https://example.com/video"

How it works: The geo-verification proxy is used only to verify your IP address for geo-restricted sites. The actual downloading uses your regular connection (or the proxy specified by --proxy).

X-Forwarded-For Header Manipulation​

XFF Policy Options​

Control how the X-Forwarded-For HTTP header is used to bypass geographic restrictions:

# Default behavior (only when known to be useful)
yt-dlp --xff default "https://example.com/video"

# Never add X-Forwarded-For header
yt-dlp --xff never "https://example.com/video"

# Use specific IP address
yt-dlp --xff "203.0.113.1" "https://example.com/video"

# Use IP block in CIDR notation
yt-dlp --xff "203.0.113.0/24" "https://example.com/video"

# Use country code (ISO 3166-2)
yt-dlp --xff "US" "https://example.com/video"
yt-dlp --xff "GB" "https://example.com/video"
yt-dlp --xff "JP" "https://example.com/video"

Country Code Examples​

# United States
yt-dlp --xff "US" "https://example.com/video"

# United Kingdom
yt-dlp --xff "GB" "https://example.com/video"

# Germany
yt-dlp --xff "DE" "https://example.com/video"

# Japan
yt-dlp --xff "JP" "https://example.com/video"

# Canada
yt-dlp --xff "CA" "https://example.com/video"

# Australia
yt-dlp --xff "AU" "https://example.com/video"

Combined Approaches​

Proxy + XFF​

Combine different bypass methods for maximum effectiveness:

# Use proxy for actual connection and XFF for geo-spoofing
yt-dlp \
  --proxy "http://us-proxy.example.com:8080" \
  --xff "US" \
  "https://example.com/video"

# Different proxy for geo-verification
yt-dlp \
  --proxy "http://main-proxy.example.com:8080" \
  --geo-verification-proxy "http://us-proxy.example.com:8080" \
  --xff "US" \
  "https://example.com/video"

Legacy Options (Deprecated)​

These options are deprecated but still available for compatibility:

# Legacy geo-bypass (equivalent to --xff "default")
yt-dlp --geo-bypass "https://example.com/video"

# Disable geo-bypass (equivalent to --xff "never")
yt-dlp --no-geo-bypass "https://example.com/video"

# Country-specific bypass (equivalent to --xff "CODE")
yt-dlp --geo-bypass-country US "https://example.com/video"

# IP block bypass (equivalent to --xff "IP_BLOCK")
yt-dlp --geo-bypass-ip-block "203.0.113.0/24" "https://example.com/video"

Practical Examples​

Accessing US Content​

# Method 1: Use US proxy
yt-dlp --proxy "http://us-proxy.example.com:8080" "https://example.com/video"

# Method 2: Use XFF header with US IP
yt-dlp --xff "US" "https://example.com/video"

# Method 3: Combine both approaches
yt-dlp --proxy "http://us-proxy.example.com:8080" --xff "US" "https://example.com/video"

Multiple Region Strategy​

# Try different regions automatically using a script
regions=("US" "GB" "CA" "AU" "DE")
for region in "${regions[@]}"; do
    echo "Trying region: $region"
    if yt-dlp --xff "$region" --simulate "https://example.com/video" 2>/dev/null; then
        echo "Success with region: $region"
        yt-dlp --xff "$region" "https://example.com/video"
        break
    fi
done

Corporate Network Bypass​

# For networks with both corporate proxy and geo-restrictions
yt-dlp \
  --proxy "http://corporate-proxy:8080" \
  --geo-verification-proxy "http://external-proxy:8080" \
  --xff "US" \
  "https://example.com/video"

Advanced Techniques​

Custom IP Ranges​

# Use specific IP ranges known to work
yt-dlp --xff "8.8.8.0/24" "https://example.com/video"        # Google DNS range
yt-dlp --xff "1.1.1.0/24" "https://example.com/video"        # Cloudflare DNS range
yt-dlp --xff "208.67.222.0/24" "https://example.com/video"   # OpenDNS range

Testing Geo-Restrictions​

# Test if content is geo-restricted
yt-dlp --simulate --verbose "https://example.com/video"

# Test with different regions
yt-dlp --xff "US" --simulate "https://example.com/video"
yt-dlp --xff "GB" --simulate "https://example.com/video"

Debugging Geo-Issues​

# Verbose output to see geo-restriction details
yt-dlp --verbose --xff "US" "https://example.com/video"

# Print network traffic to debug headers
yt-dlp --print-traffic --xff "US" "https://example.com/video"

Site-Specific Considerations​

YouTube​

# YouTube geo-restrictions
yt-dlp --xff "US" "https://youtube.com/watch?v=VIDEO_ID"

BBC iPlayer​

# UK-specific content
yt-dlp --xff "GB" "https://bbc.co.uk/iplayer/episode/VIDEO_ID"

US Network Sites​

# US network content
yt-dlp --xff "US" "https://cbs.com/shows/video/VIDEO_ID"
yt-dlp --xff "US" "https://nbc.com/video/VIDEO_ID"

Troubleshooting​

Debug Commands​

# Check if geo-restriction is the issue
yt-dlp --verbose --simulate "https://example.com/video"

# Test different bypass methods
yt-dlp --xff "US" --verbose --simulate "https://example.com/video"
yt-dlp --proxy "http://proxy:8080" --verbose --simulate "https://example.com/video"