Documentation Index Fetch the complete documentation index at: https://mintlify.com/yt-dlp/yt-dlp/llms.txt
Use this file to discover all available pages before exploring further.
yt-dlp provides several workaround options to handle problematic websites, network issues, and other edge cases.
Network and Connection Issues SSL Certificate Problems
SSL certificate validation errors
If you encounter SSL certificate validation errors: yt-dlp --no-check-certificates < ur l >
This disables certificate validation and may expose you to security risks. Only use this option if you trust the source.
Alternatively, use legacy server connection for servers that don’t support RFC 5746: yt-dlp --legacy-server-connect < ur l >
Encoding Issues
Character encoding problems in output
Force a specific encoding: yt-dlp --encoding utf-8 < ur l >
This is experimental and may not work in all cases.
Websites requiring specific headers
Using Insecure Connections
Force HTTP instead of HTTPS
For YouTube and other supported sites: yt-dlp --prefer-insecure < ur l >
Currently supported only for YouTube and a few other sites.
Rate Limiting and Throttling Sleep Between Requests
Avoid getting rate-limited
Add delays between operations: # Sleep between data extraction requests yt-dlp --sleep-requests 2 < ur l > # Sleep before each download yt-dlp --sleep-interval 5 < ur l > # Random sleep interval yt-dlp --min-sleep-interval 2 --max-sleep-interval 5 < ur l > # Sleep before subtitle downloads yt-dlp --sleep-subtitles 1 < ur l >
These options help avoid triggering anti-bot measures. Retry Configuration
Terminal and Display Issues Bidirectional Text Support
Terminal doesn't support bidirectional text
Enable the bidi workaround: yt-dlp --bidi-workaround < ur l >
Requires bidiv or fribidi executable in PATH. Color Output Issues
# Disable colors yt-dlp --no-colors < ur l > # or yt-dlp --color no_color < ur l > # Force colors for specific stream yt-dlp --color stdout:always < ur l > yt-dlp --color stderr:never < ur l >
Download Issues
Video format not available or download fails
Geo-Restrictions
Video not available in your country
Use a proxy or VPN: # HTTP/HTTPS proxy yt-dlp --proxy http://proxy.example.com:8080 < ur l > # SOCKS proxy yt-dlp --proxy socks5://127.0.0.1:1080 < ur l > # Geo-verification proxy (for IP checks only) yt-dlp --geo-verification-proxy http://proxy.example.com:8080 < ur l > # Fake X-Forwarded-For header yt-dlp --xff "US" < ur l >
Extractor fails or times out
Fragment Download Issues
DASH/HLS fragment downloads failing
# Set fragment retries yt-dlp --fragment-retries 10 < ur l > # Skip unavailable fragments yt-dlp --skip-unavailable-fragments < ur l > # Keep fragments for debugging yt-dlp --keep-fragments < ur l >
Authentication Issues Login Problems
Try different authentication methods: # Use username and password yt-dlp -u username -p password < ur l > # Use .netrc file yt-dlp --netrc < ur l > # Specify netrc location yt-dlp --netrc-location ~/.netrc-custom < ur l > # Two-factor authentication yt-dlp -u username -p password --twofactor CODE < ur l >
Cookie Issues
# Load cookies from browser yt-dlp --cookies-from-browser chrome < ur l > yt-dlp --cookies-from-browser firefox < ur l > # Specify browser profile yt-dlp --cookies-from-browser "firefox:~/.mozilla/firefox/profile" < ur l > # Use cookies file yt-dlp --cookies cookies.txt < ur l >
Supported browsers: brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale Slow Downloads
Download speed is too slow
# Increase concurrent fragments yt-dlp --concurrent-fragments 5 < ur l > # Use external downloader yt-dlp --downloader aria2c < ur l > # Adjust buffer size yt-dlp --buffer-size 16K < ur l > # Set HTTP chunk size yt-dlp --http-chunk-size 10M < ur l >
High CPU/Memory Usage
yt-dlp consuming too many resources
# Reduce concurrent fragments yt-dlp --concurrent-fragments 1 < ur l > # Use external downloader for HLS/DASH yt-dlp --downloader m3u8:ffmpeg < ur l > # Process playlist lazily yt-dlp --lazy-playlist < ur l >
Website-Specific Workarounds YouTube Issues
YouTube download problems
# Ensure you have the latest version yt-dlp -U # Use specific user agent yt-dlp --add-headers "User-Agent:Mozilla/5.0" < ur l > # Use cookies from browser yt-dlp --cookies-from-browser chrome < ur l > # Bypass age restriction yt-dlp --cookies-from-browser firefox < ur l > # Download from start for live streams yt-dlp --live-from-start < ur l >
Force using generic extractor
Debugging Enable Verbose Output
Get detailed debug information
Test Without Downloading
Test extraction without downloading
Configuration File Workarounds Permanent Workaround Settings Create a configuration file to apply workarounds permanently:
# Network workarounds --socket-timeout 30 --retries 10 --sleep-requests 1 # Rate limiting --limit-rate 1M # Custom headers --add-headers "User-Agent:Mozilla/5.0" # Format selection --format bestvideo+bestaudio/best
Compatibility Options yt-dlp provides compatibility options to revert to older behaviors:
# Use youtube-dl compatible behavior yt-dlp --compat-options youtube-dl < ur l > # Specific compat options yt-dlp --compat-options no-live-chat,no-certifi < ur l > # Use legacy HTTP handler yt-dlp --compat-options prefer-legacy-http-handler < ur l >
Getting Help
Check the FAQ Many common issues are covered in the FAQ.
Search Issues Search existing issues to see if your problem is already reported.
Report Bugs Create a new issue with verbose output and reproduction steps.
Join Discord Get help from the community on Discord.