Dec 15, 2022

yt-dlp: Download Videos from YouTube and 1000+ Sites from the Command Line

Need to download a video for offline viewing, extract audio from a lecture, or archive an entire playlist? yt-dlp is the most powerful command-line tool for downloading media from YouTube and over 1,000 other websites. It’s a fork of the now-unmaintained youtube-dl, with more features, faster downloads, and active development.

This guide covers installation, common commands, format selection, audio extraction, playlist downloading, and advanced configuration.

What is yt-dlp?

yt-dlp is a free, open-source command-line tool for downloading video and audio from websites. It supports:

YouTube (videos, playlists, channels, live streams)
Vimeo, Dailymotion, Twitch, Twitter/X, Reddit
SoundCloud, Bandcamp, Spotify (metadata only)
News sites, educational platforms, and 1,000+ more

Installing yt-dlp

macOS (Homebrew)

brew install yt-dlp

Linux

# Using pip (recommended)
pip install yt-dlp

# Or download the binary
sudo curl -L 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

# Using winget
winget install yt-dlp

# Or using pip
pip install yt-dlp

Update yt-dlp

yt-dlp -U
# or
pip install --upgrade yt-dlp

Install ffmpeg (Required for Merging)

yt-dlp needs ffmpeg to merge video and audio streams and for format conversion:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (with winget)
winget install ffmpeg

Basic Usage

Download a Video

# Download best quality
yt-dlp "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Always quote URLs to prevent shell interpretation of special characters

By default, yt-dlp downloads the best available video + audio quality and merges them into a single file.

List Available Formats

yt-dlp -F "https://www.youtube.com/watch?v=VIDEO_ID"

This shows all available formats with their resolution, codec, file size, and format code:

ID   EXT  RESOLUTION  FPS  FILESIZE   CODEC
137  mp4  1920x1080   30   ~150MiB    avc1
248  webm 1920x1080   30   ~120MiB    vp9
313  webm 3840x2160   30   ~500MiB    vp9
140  m4a  audio only       ~3.5MiB    mp4a (128k)
251  webm audio only       ~4.0MiB    opus (160k)

Download Specific Format

# Download by format ID
yt-dlp -f 137+140 "URL"

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

# Download best quality up to 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "URL"

# Download best quality up to 720p as MP4
yt-dlp -f "bestvideo[height<=720][ext=mp4]+bestaudio[ext=m4a]/best[height<=720]" "URL"

Downloading Audio Only

Extract Audio as MP3

# Download and convert to MP3
yt-dlp -x --audio-format mp3 "URL"

# Specify quality (0=best, 9=worst)
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

Other Audio Formats

# FLAC
yt-dlp -x --audio-format flac "URL"

# WAV
yt-dlp -x --audio-format wav "URL"

# AAC
yt-dlp -x --audio-format aac "URL"

# Opus (smallest file size, great quality)
yt-dlp -x --audio-format opus "URL"

Downloading Playlists

# Download entire playlist
yt-dlp "https://www.youtube.com/playlist?list=PLxxxxxx"

# Download specific items from playlist
yt-dlp --playlist-items 1-5 "PLAYLIST_URL"    # First 5 videos
yt-dlp --playlist-items 3,7,10 "PLAYLIST_URL"  # Specific videos

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

# Skip already downloaded videos
yt-dlp --download-archive archive.txt "PLAYLIST_URL"

The --download-archive flag keeps a record of downloaded videos in a text file, so re-running the command only downloads new additions.

File Naming and Organization

Custom Output Templates

# Default: video title
yt-dlp -o "%(title)s.%(ext)s" "URL"

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

# Organize by channel
yt-dlp -o "%(channel)s/%(title)s.%(ext)s" "URL"

# Organize playlists into folders
yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"

# Number files in playlist
yt-dlp -o "%(playlist_index)03d - %(title)s.%(ext)s" "PLAYLIST_URL"

Available template variables:

Variable	Description
`%(title)s`	Video title
`%(ext)s`	File extension
`%(id)s`	Video ID
`%(uploader)s`	Uploader name
`%(channel)s`	Channel name
`%(upload_date)s`	Upload date (YYYYMMDD)
`%(duration)s`	Duration in seconds
`%(resolution)s`	Video resolution
`%(playlist)s`	Playlist name
`%(playlist_index)s`	Position in playlist

Subtitles

# Download with subtitles
yt-dlp --write-subs "URL"

# Download auto-generated subtitles
yt-dlp --write-auto-subs "URL"

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

# Download specific subtitle language
yt-dlp --write-subs --sub-langs en "URL"

# Download multiple languages
yt-dlp --write-subs --sub-langs "en,es,fr" "URL"

# List available subtitles
yt-dlp --list-subs "URL"

# Convert subtitles to SRT format
yt-dlp --write-subs --convert-subs srt "URL"

Thumbnails and Metadata

# Embed thumbnail in file
yt-dlp --embed-thumbnail "URL"

# Write thumbnail to separate file
yt-dlp --write-thumbnail "URL"

# Embed metadata (title, description, etc.)
yt-dlp --embed-metadata "URL"

# Write video description to a text file
yt-dlp --write-description "URL"

# Write info JSON
yt-dlp --write-info-json "URL"

Speed and Download Control

# Limit download speed
yt-dlp --limit-rate 5M "URL"   # 5 MB/s

# Use multiple connections (faster)
yt-dlp -N 4 "URL"   # 4 concurrent fragments

# Resume interrupted downloads
yt-dlp -c "URL"

# Retry on error
yt-dlp --retries 10 "URL"

# Sleep between downloads (avoid rate limiting)
yt-dlp --sleep-interval 5 "PLAYLIST_URL"

Configuration File

Instead of typing long commands, save your preferred options in a config file:

Location:

Linux/macOS: ~/.config/yt-dlp/config
Windows: %APPDATA%\yt-dlp\config

mkdir -p ~/.config/yt-dlp
nano ~/.config/yt-dlp/config

Example config:

# Default format: best up to 1080p
-f bestvideo[height<=1080]+bestaudio/best[height<=1080]

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

# Embed subtitles and metadata
--embed-subs
--embed-metadata
--embed-thumbnail

# Use archive file
--download-archive ~/.config/yt-dlp/archive.txt

# Concurrent fragments
-N 4

# Convert subtitles to SRT
--convert-subs srt

Now just run:

yt-dlp "URL"

And all your preferences are applied automatically.

Downloading from Other Sites

yt-dlp works with hundreds of sites using the same commands:

# Twitter/X
yt-dlp "https://twitter.com/user/status/123456789"

# Reddit
yt-dlp "https://www.reddit.com/r/videos/comments/xxxxx/"

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

# Twitch clips
yt-dlp "https://clips.twitch.tv/ClipName"

# Twitch VOD
yt-dlp "https://www.twitch.tv/videos/123456789"

# SoundCloud
yt-dlp "https://soundcloud.com/artist/track"

# Instagram
yt-dlp "https://www.instagram.com/p/xxxxx/"

Useful Command Combinations

Download Best Quality MP4

yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" --merge-output-format mp4 "URL"

Download Audio Playlist as MP3

yt-dlp -x --audio-format mp3 --audio-quality 0 \
  -o "%(playlist)s/%(playlist_index)03d - %(title)s.%(ext)s" \
  "PLAYLIST_URL"

Archive a YouTube Channel

yt-dlp --download-archive archive.txt \
  -o "%(channel)s/%(upload_date)s - %(title)s.%(ext)s" \
  --embed-metadata --embed-thumbnail --write-subs \
  "https://www.youtube.com/@ChannelName/videos"

Download Only New Videos (Cron Job)

# Add to crontab
0 2 * * * yt-dlp --download-archive ~/archive.txt -o "~/Videos/%(title)s.%(ext)s" "PLAYLIST_URL"

Troubleshooting

# Update yt-dlp (fixes most issues)
yt-dlp -U

# Verbose output for debugging
yt-dlp -v "URL"

# Use cookies for age-restricted content
yt-dlp --cookies-from-browser firefox "URL"

# Skip unavailable videos in playlist
yt-dlp --ignore-errors "PLAYLIST_URL"

# Force IPv4 (if IPv6 causes issues)
yt-dlp --force-ipv4 "URL"

Summary

yt-dlp is the Swiss Army knife of video downloading. Whether you need a single video, an entire channel archive, or just the audio — it handles everything from the command line with precise control over quality, format, and organization.

Key resources:

GitHub: https://github.com/yt-dlp/yt-dlp
Supported sites: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
Wiki: https://github.com/yt-dlp/yt-dlp/wiki

Install it, create a config file, and you’ll never need a sketchy web-based video downloader again.