The yt-dlp Guide

yt-dlp --version
yt-dlp -U              # Update to latest version

yt-dlp -s "URL"            # Simulate (no download)
yt-dlp --print filename "URL" # Show what file would be created
yt-dlp -j "URL"            # Print full JSON metadata

# Prefer H.264 codec (better device compatibility)
yt-dlp -f "bestvideo[vcodec^=avc1]+bestaudio/best" "URL"

# Prefer AV1 codec (better quality-to-size)
yt-dlp -f "bestvideo[vcodec^=av01]+bestaudio/best" "URL"

# Best quality under 100MB
yt-dlp -f "best[filesize<100M]" "URL"

# 60fps preferred
yt-dlp -f "bestvideo[fps>=50]+bestaudio/best" "URL"

yt-dlp --restrict-filenames -o "%(title)s.%(ext)s" "URL"
# Replaces spaces → underscores, removes special chars

# All videos from channel
yt-dlp "https://www.youtube.com/@ChannelName/videos"

# Only after a date
yt-dlp --dateafter 20240101 "CHANNEL_URL"

# Date range
yt-dlp --dateafter 20240601 --datebefore 20241231 "CHANNEL_URL"

# Skip already-downloaded (essential for recurring runs)
yt-dlp --download-archive archive.txt "CHANNEL_URL"

# Don't download playlist when URL has &list= param
yt-dlp --no-playlist "URL_WITH_PLAYLIST_PARAM"

# Force treat URL as playlist
yt-dlp --yes-playlist "URL"

yt-dlp -u USERNAME -p PASSWORD "URL"

# Limit speed
yt-dlp -r 5M "URL"             # Max 5 MB/s

# Multiple connections (faster!)
yt-dlp -N 4 "URL"               # 4 concurrent fragments

# Proxy
yt-dlp --proxy socks5://127.0.0.1:1080 "URL"

# Geo-bypass
yt-dlp --geo-bypass-country US "URL"

# Retry on failure
yt-dlp --retries 10 --fragment-retries 10 "URL"

# Resume partial download
yt-dlp -c "URL"

# Re-encode to MP4
yt-dlp --recode-video mp4 "URL"

# Merge output to specific container
yt-dlp --merge-output-format mkv "URL"

# Split by chapters
yt-dlp --split-chapters "URL"

# Split with naming
yt-dlp --split-chapters -o "chapter:%(section_title)s.%(ext)s" "URL"

# Only videos under 10 minutes
yt-dlp --match-filter "duration < 600" "PLAYLIST"

# Only 1M+ views
yt-dlp --match-filter "view_count >= 1000000" "CHANNEL"

# Skip live streams
yt-dlp --match-filter "!is_live" "CHANNEL"

# Title contains keyword
yt-dlp --match-filter "title ~= 'tutorial'" "CHANNEL"

yt-dlp --embed-metadata "URL"       # Embed tags
yt-dlp --embed-thumbnail "URL"      # Embed cover art
yt-dlp --write-thumbnail "URL"      # Save thumbnail file
yt-dlp --write-description "URL"    # Save description
yt-dlp --write-comments "URL"      # Save comments (JSON)
yt-dlp --write-info-json "URL"     # Save all metadata

# Full music archival combo
yt-dlp -x --audio-format mp3 --embed-metadata --embed-thumbnail "URL"

# Copy everything below and paste it into nano / Notepad.
# Remove or add lines to suit your needs.
# Lines starting with # are comments and are ignored.

# Save videos to your Downloads folder
--output ~/Downloads/%(title)s.%(ext)s

# Always output as MP4
--merge-output-format mp4

# Embed metadata (title, artist, date) into the file
--embed-metadata

# Embed the video thumbnail as cover art
--embed-thumbnail

# Download and embed English subtitles
--embed-subs
--sub-langs en

# Skip videos you've already downloaded
--download-archive ~/.config/yt-dlp/archive.txt

# Use 4 connections for faster downloads
--concurrent-fragments 4

# Remove special characters from filenames
--restrict-filenames

# macOS/Linux (nano editor):
#   1. Press  Ctrl + X   (exit)
#   2. Press  Y           (yes, save changes)
#   3. Press  Enter       (confirm the filename)
#
# You'll see something like:
#   File Name to Write: /Users/you/.config/yt-dlp/config
#   Just press Enter — that's the correct path.
#
# Windows (Notepad):
#   Just press Ctrl + S to save, then close Notepad.

# Just run this — your config defaults apply automatically:
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# You can still add extra flags on top of your defaults:
yt-dlp -f "bestvideo[height<=720]+bestaudio" "URL"

# Need to ignore your config for one download?
yt-dlp --ignore-config "URL"

# Want to use a completely different config file?
yt-dlp --config-location /path/to/other-config.txt "URL"

# To edit your config later, just run the nano command again:
nano $HOME/.config/yt-dlp/config