yt-dlp Video Downloader

yt-dlp is a powerful command-line tool that downloads videos/audio from thousands of websites.

Prerequisites

Check if yt-dlp is installed:

yt-dlp --version

If not installed, install with:

# Using pip
pip install yt-dlp

# Or using package managers
# Windows: winget install yt-dlp
# macOS: brew install yt-dlp
# Linux: See https://github.com/yt-dlp/yt-dlp#installation

Quick Start

Basic Video Download

Download a video in best quality:

yt-dlp "VIDEO_URL"

Download to specific directory with custom filename:

yt-dlp -o "downloads/%(title)s.%(ext)s" "VIDEO_URL"

Audio Only

Extract audio (MP3/Opus/etc):

yt-dlp -x --audio-format mp3 "VIDEO_URL"

Format Selection

Select specific quality:

# Best quality up to 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio" "VIDEO_URL"

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

# Worst quality (for testing)
yt-dlp -f "worst" "VIDEO_URL"

Playlist Download

Download entire playlist:

yt-dlp "PLAYLIST_URL"

Download specific range from playlist:

yt-dlp --playlist-start 5 --playlist-end 10 "PLAYLIST_URL"

Subtitles

Download subtitles:

# Download available subtitles
yt-dlp --write-subs --sub-langs en "VIDEO_URL"

# Embed subtitles into video
yt-dlp --embed-subs --convert-subs srt "VIDEO_URL"

# Download auto-generated subs
yt-dlp --write-auto-subs "VIDEO_URL"

Common Options

Python Script

For more complex operations, use the bundled Python script:

.claude/skills/yt-dlp/scripts/download.py URL [options]

The script provides a simple interface with progress bars and error handling.

Output Templates

Common output template variables:

Example templates:

# Organize by uploader
-o "downloads/%(uploader)s/%(title)s.%(ext)s"

# Include date
-o "downloads/%(upload_date)s - %(title)s.%(ext)s"

# Flat directory with ID
-o "downloads/%(id)s.%(ext)s"

Troubleshooting

Format not available: Try different format selector or use -f "best"

Download fails: Check network connection, try --retry-sleep

Subtitle not available: Video may not have subtitles, try --list-subs first

Rate limiting: Use --rate-limit to avoid being blocked

Age restricted: Use --cookies-from-browser chrome to pass authentication

Supported Sites

yt-dlp supports 1000+ websites including:

• YouTube (all features)
• Bilibili
• Vimeo
• Twitter/X
• Instagram
• TikTok
• Twitch
• And many more...

See https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md for full list.