Quick start guide

Learn how to download your first video and master basic yt-dlp commands

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 a playlist

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 entire YouTube channel

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 with subtitles

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 specific quality

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"

Download from multiple sites

yt-dlp supports thousands of sites. Just use the video URL:

Vimeo

yt-dlp "https://vimeo.com/123456789"

yt-dlp "https://twitter.com/user/status/1234567890"

yt-dlp "https://www.tiktok.com/@user/video/1234567890"

yt-dlp "https://www.twitch.tv/videos/1234567890"

See the list of supported sites for all available extractors.

Batch download from file

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:

   Best quality (default)

   yt-dlp "VIDEO_URL"
   

   yt-dlp -f 137+140 "VIDEO_URL"
   

   yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" "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