Skip to main content

Getting Started

Your First Download​

Once yt-dlp is installed, downloading a video is as simple as providing a URL:

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

This command will:

  • Analyze the URL and detect the appropriate extractor
  • Select the best available video+audio format
  • Download the file to the current directory
  • Use the video title as the filename

Understanding Basic Concepts​

URL Handling​

yt-dlp accepts various URL formats:

# Direct video URLs
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# Playlist URLs
yt-dlp "https://www.youtube.com/playlist?list=PLAYLIST_ID"

# Channel URLs (downloads all videos)
yt-dlp "https://www.youtube.com/@ChannelName"

# Multiple URLs
yt-dlp "URL1" "URL2" "URL3"

Default Behavior​

By default, yt-dlp will:

  • Download the best quality video with audio
  • Use the video title as filename
  • Save files to the current directory
  • Continue on errors (won't stop for one failed video)
  • Show progress information

Essential Options​

Choosing Output Location​

# Specify output directory
yt-dlp -P "/path/to/downloads" "URL"

# Custom filename template
yt-dlp -o "%(title)s.%(ext)s" "URL"

# Organized downloads
yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" "URL"

Quality Control​

# Download best available quality
yt-dlp -f "best" "URL"

# Download specific format
yt-dlp -f "720p" "URL"

# Audio only
yt-dlp -f "bestaudio" "URL"

# Extract audio to MP3
yt-dlp -x --audio-format mp3 "URL"

Information Without Downloading​

# List available formats
yt-dlp -F "URL"

# Show video information
yt-dlp -j "URL"

# Simulate download (don't actually download)
yt-dlp -s "URL"

Common Use Cases​

Music Downloads​

# Extract best quality audio
yt-dlp -x --audio-format best "URL"

# Convert to MP3 with specific quality
yt-dlp -x --audio-format mp3 --audio-quality 192K "URL"

# Download entire playlist as audio
yt-dlp -x --audio-format mp3 "PLAYLIST_URL"

Video Downloads​

# Download 1080p video if available
yt-dlp -f "best[height<=1080]" "URL"

# Download video and subtitles
yt-dlp --write-subs --sub-langs en "URL"

# Download with thumbnail
yt-dlp --write-thumbnail "URL"

Playlist Management​

# Download specific range of videos
yt-dlp -I 1-10 "PLAYLIST_URL"

# Download playlist in reverse order
yt-dlp -I ::-1 "PLAYLIST_URL"

# Skip first 5 videos
yt-dlp -I 6: "PLAYLIST_URL"

Configuration Basics​

Using Configuration Files​

Create a configuration file to avoid typing common options:

~/.config/yt-dlp/config (Linux/macOS):

# Always extract audio
-x
--audio-format mp3

# Use proxy
--proxy http://127.0.0.1:8080

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

# Continue on errors
--ignore-errors

%APPDATA%/yt-dlp/config (Windows):

-x
--audio-format mp3
-o C:\Downloads\%(title)s.%(ext)s
--ignore-errors

Environment Variables​

Set common options via environment variables:

export YTDLP_OPTIONS="--extract-audio --audio-format mp3"
yt-dlp "URL"  # Will use the options from environment

Error Handling​

Common Issues and Solutions​

Video Unavailable:

# Try different format
yt-dlp -f "worst" "URL"

# Use cookies from browser
yt-dlp --cookies-from-browser chrome "URL"

Slow Downloads:

# Use multiple connections
yt-dlp --concurrent-fragments 5 "URL"

# Limit rate to avoid throttling
yt-dlp --limit-rate 1M "URL"

Format Not Available:

# List available formats first
yt-dlp -F "URL"

# Use format selection with fallback
yt-dlp -f "720p/best" "URL"

Getting Help​

Built-in Help​

# General help
yt-dlp --help

# List all options
yt-dlp --help | grep -A1 "\-\-"

# Check version
yt-dlp --version

# List supported sites
yt-dlp --list-extractors

Debugging​

# Verbose output for troubleshooting
yt-dlp --verbose "URL"

# Simulate to test options
yt-dlp --simulate --verbose "URL"

# Print extracted information
yt-dlp --print-json "URL"