Skip to main content
Answers to the most common questions about using yt-dlp.

​
General Questions

yt-dlp is a feature-rich command-line audio/video downloader with support for thousands of sites. It’s a fork of youtube-dl with additional features and fixes.Key improvements over youtube-dl:
  • Faster and more frequently updated
  • Better format selection
  • More extractors and features
  • SponsorBlock integration
  • Better playlist handling
yt-dlp is a fork of youtube-dl with:
  • More frequent updates and active development
  • Additional features (SponsorBlock, better format selection, etc.)
  • More supported sites and extractors
  • Better performance
  • Bug fixes and improvements
yt-dlp maintains compatibility with youtube-dl while adding new capabilities.
  • Python 3.10+ (CPython)
  • Python 3.11+ (PyPy)
If you use standalone binaries, Python is already included.
While technically optional, ffmpeg is strongly recommended for:
  • Merging video and audio streams
  • Converting formats
  • Embedding thumbnails and metadata
  • Downloading HLS/DASH streams
  • Most post-processing tasks
Download from: yt-dlp/FFmpeg-Builds

​
Installation & Updates

Recommended methods:
# Standalone binary (Linux/macOS)
sudo wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

# Windows (download .exe)
# https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe

# Via pip
pip install yt-dlp

# Via pip with all extras
pip install "yt-dlp[default,curl-cffi]"
See the Installation guide for more options.
For standalone binaries:
yt-dlp --update

# Update to nightly (recommended)
yt-dlp --update-to nightly
For pip installations:
pip install -U yt-dlp

# Install nightly with pip
pip install -U --pre "yt-dlp[default]"
Use nightly builds for regular use. They are:
  • Updated daily with latest fixes
  • More reliable for frequently-changing sites
  • The recommended version for bug reports
Stable builds are less frequent and may have older extractors.
yt-dlp --update-to nightly
yt-dlp-ejs is required for full YouTube support.Included in: Most standalone binariesFor pip installations:
  1. Install a JavaScript runtime (deno recommended): 
    # Install deno
curl -fsSL https://deno.land/install.sh | sh
  2. yt-dlp will automatically fetch yt-dlp-ejs when needed
See the EJS wiki for detailed setup.

​
Downloading

# Best overall quality (may be webm)
yt-dlp -f "bestvideo+bestaudio" URL

# Best MP4 video
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" URL

# Simpler: use preset
yt-dlp --preset-alias mp4 URL

# Extract audio
yt-dlp -x URL

# Extract as MP3
yt-dlp -x --audio-format mp3 URL

# Or use preset
yt-dlp --preset-alias mp3 URL

# Best quality audio (no conversion)
yt-dlp -f "bestaudio" URL

# Download entire playlist
yt-dlp PLAYLIST_URL

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

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

# Skip first N videos
yt-dlp --playlist-start 5 PLAYLIST_URL
By default, if a URL contains both a video and playlist, only the video is downloaded.
# Download entire playlist
yt-dlp --yes-playlist URL

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

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

# Exactly 720p
yt-dlp -f "bestvideo[height=720]+bestaudio" URL

# Max file size
yt-dlp --max-filesize 100M URL

# Download all available subtitles
yt-dlp --write-subs --sub-langs all URL

# Download auto-generated subs
yt-dlp --write-auto-subs --sub-langs en URL

# Embed subtitles in video
yt-dlp --embed-subs URL

# Specific languages
yt-dlp --write-subs --sub-langs en,es,fr URL

# Download from current position
yt-dlp URL

# Download from start (experimental)
yt-dlp --live-from-start URL

# Wait for scheduled stream
yt-dlp --wait-for-video 60 URL

# Resume (enabled by default)
yt-dlp --continue URL

# Restart from beginning
yt-dlp --no-continue URL

​
Authentication

Use cookies from your logged-in browser:
yt-dlp --cookies-from-browser firefox URL
Supported browsers: firefox, chrome, chromium, edge, opera, safari, brave
yt-dlp --username YOUR_USERNAME --password YOUR_PASSWORD URL

# Or use netrc file
yt-dlp --netrc URL
Many sites block programmatic login. Using cookies is more reliable.
A .netrc file stores login credentials.Location:
  • Linux/macOS: ~/.netrc
  • Windows: %HOME%\_netrc
Format:
machine youtube
login [email protected]
password your_password

machine twitch
login your_username
password your_password
Usage:
yt-dlp --netrc URL

​
Format Selection

yt-dlp -F URL
This shows all formats with IDs, resolutions, codecs, and file sizes.
# By format ID
yt-dlp -f 137+140 URL

# By criteria
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" URL
Many sites (especially YouTube) serve high-quality video and audio as separate streams.yt-dlp automatically:
  1. Downloads both streams
  2. Merges them using ffmpeg
This is why ffmpeg is required for best quality downloads.
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best" URL

# Or merge to MP4
yt-dlp --merge-output-format mp4 URL

​
Output & File Naming

# Basic template
yt-dlp -o "%(title)s.%(ext)s" URL

# With uploader and date
yt-dlp -o "%(uploader)s - %(upload_date)s - %(title)s.%(ext)s" URL

# Organize in folders
yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" URL
See Output Templates for all available fields.
# Using -P option
yt-dlp -P /path/to/folder URL

# Using -o with full path
yt-dlp -o "/path/to/folder/%(title)s.%(ext)s" URL

# Don't overwrite (default)
yt-dlp --no-overwrites URL

# Force overwrite
yt-dlp --force-overwrites URL

# ASCII only
yt-dlp --restrict-filenames URL

# Windows-compatible
yt-dlp --windows-filenames URL

​
Post-Processing

# Merge to MP4 container
yt-dlp --merge-output-format mp4 URL

# Re-encode to MP4
yt-dlp --recode-video mp4 URL

yt-dlp -x --audio-format mp3 --embed-thumbnail URL
Requires mutagen (or AtomicParsley for M4A).
# Embed metadata and thumbnail
yt-dlp --embed-metadata --embed-thumbnail URL

# Add chapter markers
yt-dlp --embed-chapters URL

# Remove sponsor segments
yt-dlp --sponsorblock-remove sponsor URL

# Remove all SponsorBlock categories
yt-dlp --sponsorblock-remove all URL

# Just mark chapters (don't remove)
yt-dlp --sponsorblock-mark all URL

​
Advanced Usage

Create ~/.config/yt-dlp/config (Linux/macOS) or %APPDATA%/yt-dlp/config.txt (Windows):
# Format selection
-f bestvideo+bestaudio

# Output template
-o ~/Videos/%(title)s.%(ext)s

# Embed metadata
--embed-metadata
--embed-thumbnail

# SponsorBlock
--sponsorblock-mark all
Options in config file are used automatically.
Create a text file with one URL per line:
yt-dlp --batch-file urls.txt

# Or from stdin
cat urls.txt | yt-dlp --batch-file -

# Get direct URL
yt-dlp -g URL

# Use with aria2c
yt-dlp --downloader aria2c --downloader-args "-x 16 -s 16" URL

# Only videos shorter than 10 minutes
yt-dlp --match-filters "duration < 600" PLAYLIST_URL

# Only videos uploaded this year
yt-dlp --dateafter now-1year PLAYLIST_URL

# Exclude live streams
yt-dlp --match-filters "!is_live" PLAYLIST_URL
Yes! See the Embedding yt-dlp guide.
from yt_dlp import YoutubeDL

ydl_opts = {'format': 'best'}
with YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])

​
Troubleshooting

  1. Update to nightly: 
    yt-dlp --update-to nightly
  2. Check verbose output: 
    yt-dlp --verbose URL
  3. Try with cookies: 
    yt-dlp --cookies-from-browser firefox URL
See the Troubleshooting guide for more solutions.
  • Use external downloader: --downloader aria2c
  • Increase concurrent fragments: -N 10
  • Check your internet connection
  • Some sites have rate limiting

​
More Information

For more detailed information, see:

Build docs developers (and LLMs) love

Get started for freeTalk to us