Skip to main content
This guide covers common issues you might encounter when using yt-dlp and their solutions.

​
Before You Start

Always update to the latest nightly version before reporting issues:
yt-dlp --update-to nightly
Many issues are already fixed in newer versions.

​
Check Verbose Output

When troubleshooting, always use verbose mode to see detailed information: 
yt-dlp --verbose URL

​
Common Error Messages

​
”ERROR: Unable to download webpage: HTTP Error 403: Forbidden”

Cause: The website is blocking your request, often due to:
  • Geographic restrictions
  • Rate limiting
  • Bot detection
  • TLS fingerprinting
Solutions: 
yt-dlp --impersonate chrome URL
Requires curl_cffi to be installed. See available targets:
yt-dlp --list-impersonate-targets

yt-dlp --cookies-from-browser firefox URL
Supported browsers: firefox, chrome, chromium, edge, opera, safari
yt-dlp --proxy socks5://127.0.0.1:1080 URL

yt-dlp --geo-bypass URL

# Or specify country code
yt-dlp --xff "US" URL

​
”ERROR: [youtube] Video unavailable”

Solutions:
YouTube frequently changes its code. Ensure you have:
  1. Latest nightly version
  2. yt-dlp-ejs installed with a JavaScript runtime
yt-dlp --update-to nightly
# Install deno (recommended JS runtime)
Check the EJS wiki for setup.
Some videos require authentication:
yt-dlp --cookies-from-browser firefox URL
Try opening the URL in your browser to verify the video exists and is accessible.

​
”ERROR: ffmpeg not found”

Cause: ffmpeg is not installed or not in your system PATH. Solutions: 
# Linux (Debian/Ubuntu)
sudo apt install ffmpeg

# macOS (Homebrew)
brew install ffmpeg

# Windows - download from:
# https://github.com/yt-dlp/FFmpeg-Builds/releases
Or specify ffmpeg location: 
yt-dlp --ffmpeg-location /path/to/ffmpeg URL
Use yt-dlp’s custom ffmpeg builds which include patches for known issues.

​
”ERROR: Requested format is not available”

Cause: The format you requested doesn’t exist for this video. Solutions: 
yt-dlp -F URL
This shows all available formats with their IDs.
# Best video + best audio
yt-dlp -f "bestvideo+bestaudio" URL

# Best overall quality
yt-dlp -f "best" URL

# Specific format by ID
yt-dlp -f 137+140 URL

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" URL

​
”ERROR: This video requires payment to watch”

Cause: The video is behind a paywall or requires authentication. Solution: Use cookies from a logged-in browser session: 
yt-dlp --cookies-from-browser chrome URL
yt-dlp cannot bypass DRM protection. If a video uses DRM (like Widevine), it cannot be downloaded.

​
”WARNING: unable to obtain file audio codec with ffprobe”

Cause: ffprobe is missing or outdated. Solution: Install/update ffmpeg (includes ffprobe): 
# Check ffprobe version
ffprobe -version

# Update ffmpeg/ffprobe using your package manager

​
Download Issues

​
Slow Download Speeds

Solutions: 
# Use aria2c for faster parallel downloads
yt-dlp --downloader aria2c --downloader-args "-x 16 -s 16" URL
Install aria2c:
  • Linux: sudo apt install aria2
  • macOS: brew install aria2
  • Windows: Download from aria2 releases
yt-dlp -N 10 URL
Downloads 10 fragments concurrently (default is 1).
yt-dlp --limit-rate 5M URL
Some servers throttle if you download too fast.

​
Download Keeps Failing

Solutions: 
# Increase retries
yt-dlp --retries 20 URL

# Add retry sleep time
yt-dlp --retry-sleep 5 URL

# Resume partial downloads
yt-dlp --continue URL

# Keep fragments on failure for debugging
yt-dlp --keep-fragments URL

​
“ERROR: unable to download video data: HTTP Error 416”

Cause: Server doesn’t support resuming from where you left off. Solution: 
yt-dlp --no-continue URL
This restarts the download from the beginning.

​
Authentication Issues

​
”ERROR: Unable to log in”

Solutions:
Many sites block programmatic login but work with cookies:
yt-dlp --cookies-from-browser firefox URL
Verify your username and password are correct:
yt-dlp --username YOUR_USERNAME --password YOUR_PASSWORD URL
Create ~/.netrc (Unix) or %HOME%\_netrc (Windows):
machine youtube
login YOUR_EMAIL
password YOUR_PASSWORD
Then run:
yt-dlp --netrc URL
If the site uses 2FA, use cookies from browser instead of direct login.

​
Post-Processing Issues

​
”ERROR: Postprocessing failed”

Cause: Usually related to missing or incompatible ffmpeg. Solutions: 
ffmpeg -version
Ensure you have a recent version (4.0+).
Download from yt-dlp/FFmpeg-Builds

​
Thumbnail Embedding Failed

Solutions: 
# Install mutagen
pip install mutagen

# Or use AtomicParsley for MP4 files
sudo apt install atomicparsley  # Linux
brew install atomicparsley       # macOS

​
Playlist Issues

​
”ERROR: Unable to download just video (if you want to download playlist, pass —yes-playlist)”

Solution: If the URL contains both a video and playlist: 
# Download entire playlist
yt-dlp --yes-playlist URL

# Download only the specific video
yt-dlp --no-playlist URL

​
Playlist Download Incomplete

Solutions: 
# Continue despite errors
yt-dlp --ignore-errors URL

# Download specific items
yt-dlp --playlist-items 1-10,15,20 URL

# Download in reverse order
yt-dlp --playlist-reverse URL

# Random order
yt-dlp --playlist-random URL

​
Platform-Specific Issues

​
Windows

Use Command Prompt instead of PowerShell, or set UTF-8 encoding:
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
Use shorter output templates or enable long path support in Windows.

​
macOS

Make the binary executable:
chmod a+rx /usr/local/bin/yt-dlp
Remove quarantine attribute:
xattr -d com.apple.quarantine /usr/local/bin/yt-dlp

​
Linux

Install ca-certificates:
sudo apt install ca-certificates
Reinstall Python with SSL support:
sudo apt install libssl-dev

​
Getting Help

​
Check the FAQ

Many common questions are answered in the FAQ.

​
Search Existing Issues

Before reporting a bug, search GitHub Issues to see if it’s already reported.

​
Reporting Bugs

When reporting an issue, always include:
  1. Full verbose output: 
    yt-dlp --verbose URL 2>&1 | tee output.txt
  2. Version information: 
    yt-dlp --version
  3. Complete command used
  4. URL (if not private/sensitive)
For privacy, you can redact sensitive URLs, but provide enough context about the site/extractor being used.

​
Community Support

Join the discussion:
Do not ask for help downloading copyrighted content. yt-dlp is a tool - it’s your responsibility to use it legally.

Build docs developers (and LLMs) love

Get started for freeTalk to us