Overview yt-dlp makes it easy to download videos from thousands of supported sites. This guide covers the fundamental workflows for downloading videos effectively.
Basic Download The simplest way to download a video is to provide the URL:
yt-dlp "https://www.youtube.com/watch?v=BaW_jenozKc"
By default, yt-dlp downloads the best available quality, equivalent to using -f bestvideo*+bestaudio/best.
yt-dlp will automatically merge video and audio streams when ffmpeg is available, giving you the best quality output.
Selecting Video Quality
List available formats
View all available quality options before downloading: yt-dlp -F "https://www.youtube.com/watch?v=BaW_jenozKc"
This displays a table showing format codes, resolutions, codecs, and file sizes.
Choose a specific format
Download using a format code from the list: yt-dlp -f 22 "https://www.youtube.com/watch?v=BaW_jenozKc"
Use format selectors
Select formats using criteria instead of specific codes: # Best video + audio, or best combined format yt-dlp -f "bv+ba/b" URL # Best MP4 format yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]" URL # Best video up to 720p yt-dlp -f "bv*[height<=720]+ba/b" URL
Quality Preferences Download best quality up to a limit Resolution Limit
File Size Limit
Codec Preference
# No better than 480p yt-dlp -S "res:480" URL # No better than 720p yt-dlp -S "height:720" URL
Download Multiple Videos From a file Create a text file with URLs (one per line):
https://www.youtube.com/watch?v=BaW_jenozKc https://www.youtube.com/watch?v=dQw4w9WgXcQ # Lines starting with # are comments
Then download all:
Multiple URLs directly Output Location Customize where files are saved:
Custom Directory
Custom Filename
Separate Paths
# Save to specific folder yt-dlp -P ~/Downloads/Videos URL
Common Download Scenarios Download for offline viewing # Best quality MP4 (most compatible) yt-dlp --merge-output-format mp4 --remux-video mp4 \ -S "vcodec:h264,acodec:aac" URL
Quick download (smallest file) # Smallest file size yt-dlp -S "+size,+br" URL
High quality archival # Best possible quality with metadata yt-dlp -f "bv*+ba" --embed-metadata --embed-thumbnail \ --embed-subs --write-description URL
Download with Retries Network issues can interrupt downloads. Configure retry behavior for reliability.
# Retry up to 10 times (default) yt-dlp --retries 10 URL # Infinite retries yt-dlp --retries infinite URL # With exponential backoff yt-dlp --retry-sleep exp=1:60 URL
Resume Interrupted Downloads yt-dlp automatically resumes partially downloaded files:
# Continue partial downloads (default) yt-dlp -c URL # Force restart from beginning yt-dlp --no-continue URL
Speed Limiting Control download speed to avoid network congestion:
# Limit to 1 MB/s yt-dlp -r 1M URL # Limit to 500 KB/s yt-dlp --limit-rate 500K URL
Batch Download Best Practices When downloading many videos, use these options to be respectful to servers:
yt-dlp \ --sleep-interval 5 \ --max-sleep-interval 15 \ --sleep-requests 1 \ --download-archive archive.txt \ -a urls.txt
This configuration:
Waits 5-15 seconds between downloads
Waits 1 second between requests
Tracks downloaded videos to avoid duplicates
Troubleshooting Video unavailable or private # Ignore errors and continue yt-dlp --ignore-errors -a urls.txt
Age-restricted content # Use cookies from browser yt-dlp --cookies-from-browser firefox URL
Geo-restricted content # Use proxy yt-dlp --proxy socks5://127.0.0.1:1080 URL # Fake X-Forwarded-For header yt-dlp --xff "US" URL
Next Steps
Audio Extraction Extract audio from videos in various formats
Playlists Download entire playlists and channels
Format Selection Advanced format selection options
Output Templates Customize file naming and organization