Troubleshooting

Common issues and solutions for yt-dlp

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:

Solution 1: Use browser impersonation

yt-dlp --impersonate chrome URL

Requires curl_cffi to be installed. See available targets:

yt-dlp --list-impersonate-targets

Solution 2: Use cookies from your browser

yt-dlp --cookies-from-browser firefox URL

Supported browsers: firefox, chrome, chromium, edge, opera, safari

Solution 3: Use a proxy

yt-dlp --proxy socks5://127.0.0.1:1080 URL

Solution 4: Bypass geo-restrictions

yt-dlp --geo-bypass URL

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

”ERROR: [youtube] Video unavailable”

Solutions:

Update and use yt-dlp-ejs

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.

Use cookies

Some videos require authentication:

yt-dlp --cookies-from-browser firefox URL

Check if video is actually available

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:

List available formats

yt-dlp -F URL

This shows all available formats with their IDs.

Use format selection

# 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

Fallback to next best

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 external downloader

# 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

Increase concurrent fragments

yt-dlp -N 10 URL

Downloads 10 fragments concurrently (default is 1).

Limit rate to avoid throttling

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:

Use cookies instead of username/password

Many sites block programmatic login but work with cookies:

yt-dlp --cookies-from-browser firefox URL

Check credentials

Verify your username and password are correct:

yt-dlp --username YOUR_USERNAME --password YOUR_PASSWORD URL

Use .netrc file

Create ~/.netrc (Unix) or %HOME%\_netrc (Windows):

machine youtube
login YOUR_EMAIL
password YOUR_PASSWORD

Then run:

yt-dlp --netrc URL

Two-factor authentication

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:

Check ffmpeg installation

ffmpeg -version

Ensure you have a recent version (4.0+).

Use yt-dlp's ffmpeg builds

Download from yt-dlp/FFmpeg-Builds

Skip post-processing

To download without post-processing:

yt-dlp --no-post-overwrites URL

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

Missing MSVCR100.dll

Install Microsoft Visual C++ 2010 Redistributable

PowerShell encoding issues

Use Command Prompt instead of PowerShell, or set UTF-8 encoding:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Path too long error

Use shorter output templates or enable long path support in Windows.

macOS

Permission denied

Make the binary executable:

chmod a+rx /usr/local/bin/yt-dlp

Quarantine warning

Remove quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/yt-dlp

Linux

SSL certificate errors

Install ca-certificates:

sudo apt install ca-certificates

Python SSL module not available

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:

• Discord Server
• GitHub Discussions
• GitHub Issues

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