Skip to main content

​
Your first download

Once yt-dlp is installed, downloading a video is as simple as: 
yt-dlp "https://www.youtube.com/watch?v=BaW_jenozKc"
yt-dlp will automatically:
  • Select the best quality video and audio
  • Merge them into a single file
  • Save to your current directory
The URL should be in quotes to avoid issues with special characters in your shell.

​
Basic usage patterns

​
Download best quality

By default, yt-dlp downloads the best quality available: 
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
This selects the best video with the best audio and merges them using ffmpeg.

​
Download audio only

To download just the audio: 
yt-dlp -x "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
The -x (or --extract-audio) option extracts audio from the video.

​
Download audio in specific format

To download and convert audio to MP3: 
yt-dlp -x --audio-format mp3 "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
Supported audio formats: mp3, m4a, flac, opus, vorbis, wav

​
Download with custom output name

Specify where and how to save the file: 
yt-dlp -o "~/Videos/%(title)s.%(ext)s" "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
Common template variables:
  • %(title)s - Video title
  • %(id)s - Video ID
  • %(ext)s - File extension
  • %(uploader)s - Channel name
  • %(upload_date)s - Upload date (YYYYMMDD)

​
Common use cases

Download all videos from a playlist:
yt-dlp "https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf"
Download only specific items from a playlist:
# Download items 1, 2, 3, 7, and the last 5 items
yt-dlp -I 1:3,7,-5:: "https://www.youtube.com/playlist?list=PLAYLIST_ID"
Download playlist with numbered filenames:
yt-dlp -o "%(playlist_index)s-%(title)s.%(ext)s" "PLAYLIST_URL"
Download all uploads from a channel (including shorts and livestreams):
yt-dlp "https://www.youtube.com/@channelname"
Or using the channel URL:
yt-dlp "https://www.youtube.com/c/channelname/videos"
Download video with automatic English subtitles:
yt-dlp --write-auto-subs --sub-lang en "VIDEO_URL"
Download and embed subtitles in the video file:
yt-dlp --write-subs --embed-subs --sub-lang en "VIDEO_URL"
Download all available subtitles:
yt-dlp --write-subs --sub-lang all "VIDEO_URL"
Download 1080p video when available:
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "VIDEO_URL"
Download best video up to 720p:
yt-dlp -S "res:720" "VIDEO_URL"
List all available formats before downloading:
yt-dlp -F "VIDEO_URL"
yt-dlp supports thousands of sites. Just use the video URL:
yt-dlp "https://vimeo.com/123456789"
See the list of supported sites for all available extractors.
Create a text file with URLs (one per line):
urls.txt
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://www.youtube.com/watch?v=9bZkp7q19f0
https://vimeo.com/123456789
# Lines starting with # are comments
Then download all URLs:
yt-dlp -a urls.txt

​
Essential options

1

Format selection

Control video quality and format:
yt-dlp "VIDEO_URL"
Use -F to list all available formats first:
yt-dlp -F "VIDEO_URL"
2

Output template

Customize the output filename and location:
yt-dlp -o "~/Downloads/%(uploader)s/%(playlist)s/%(playlist_index)s-%(title)s.%(ext)s" "VIDEO_URL"
Common patterns:
  • %(title)s - Video title
  • %(uploader)s - Channel/uploader name
  • %(upload_date>%Y-%m-%d)s - Formatted date
  • %(playlist_index)s - Position in playlist
  • %(id)s - Video ID
3

Download archive

Avoid re-downloading videos you already have:
yt-dlp --download-archive downloaded.txt "PLAYLIST_URL"
This creates/updates downloaded.txt with IDs of downloaded videos. On subsequent runs, videos already in the archive are skipped.
4

Simulate and preview

Preview what would be downloaded without actually downloading:
yt-dlp -s "VIDEO_URL"
Get video info as JSON:
yt-dlp -j "VIDEO_URL"
Print specific fields:
yt-dlp --print "%(title)s - %(uploader)s" "VIDEO_URL"

​
Practical examples

​
Download music album from YouTube

yt-dlp \
  -x --audio-format mp3 \
  -o "%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" \
  --embed-thumbnail \
  --add-metadata \
  "PLAYLIST_URL"
This:
  • Extracts audio only (-x)
  • Converts to MP3 (--audio-format mp3)
  • Organizes by playlist with numbering
  • Embeds album art (--embed-thumbnail)
  • Adds ID3 tags (--add-metadata)

​
Download video lecture series

yt-dlp \
  -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  -o "%(playlist_title)s/Lecture %(playlist_index)s - %(title)s.%(ext)s" \
  --write-subs --embed-subs --sub-lang en \
  --download-archive archive.txt \
  "PLAYLIST_URL"
This:
  • Limits quality to 720p (smaller file size)
  • Numbers lectures sequentially
  • Downloads and embeds English subtitles
  • Tracks downloaded videos to avoid duplicates

​
Download with SponsorBlock integration

yt-dlp \
  --sponsorblock-mark all \
  --embed-chapters \
  "VIDEO_URL"
Or remove sponsor segments entirely: 
yt-dlp \
  --sponsorblock-remove sponsor,intro,outro \
  "VIDEO_URL"

​
Download livestream from the start

yt-dlp --live-from-start "LIVESTREAM_URL"
This feature is experimental and currently only supports YouTube, Twitch, and TVer.

​
Tips and tricks

Rate limiting

Limit download speed to avoid throttling:
yt-dlp -r 50K "VIDEO_URL"
-r 50K limits to 50 KB/s. Use M for MB/s.

Geo-restriction bypass

Use a proxy for geo-restricted content:
yt-dlp --proxy socks5://127.0.0.1:1080 "VIDEO_URL"

Cookies from browser

Download videos requiring login:
yt-dlp --cookies-from-browser chrome "VIDEO_URL"
Supported browsers: chrome, firefox, safari, edge, opera, brave

Thumbnail embedding

Embed video thumbnail as cover art:
yt-dlp --embed-thumbnail --convert-thumbnails jpg "VIDEO_URL"

​
Getting help

View all available options: 
yt-dlp --help
Check version and loaded dependencies: 
yt-dlp --version
yt-dlp --verbose
List all supported extractors: 
yt-dlp --list-extractors

​
Next steps

Format selection

Learn advanced format selection and sorting

Output templates

Master powerful output template syntax

Configuration files

Set up default options in config files

Post-processing

Convert, merge, and modify downloaded videos

Build docs developers (and LLMs) love

Get started for freeTalk to us