yt-dlp Command Wiki

A comprehensive guide to downloading videos and audio from YouTube and other sites using yt-dlp.

What is yt-dlp and Why Use It?

yt-dlp is a powerful command-line tool for downloading videos, audio, and playlists from YouTube and hundreds of other websites. It is a modern fork of the now-inactive youtube-dl, with numerous additional features, bug fixes, and better performance.

Why use yt-dlp?

• Actively maintained with frequent updates

• Supports more sites and modern streaming formats

• More powerful filtering options (e.g., resolution, codec, duration)

• Improved audio and subtitle support

• Faster and more reliable than youtube-dl

• Advanced customization for filenames, metadata, and output

Installation

Windows

Using pip (Python required):

pip install yt-dlp

Update:

pip install -U yt-dlp

Standalone Binary (No Python required):

1. Download yt-dlp.exe from: https://github.com/yt-dlp/yt-dlp/releases/latest
2. Move it to a folder in your PATH (e.g., C:\Windows)
3. Run from Command Prompt or PowerShell:

yt-dlp https://youtube.com/...

macOS

Using Homebrew:

brew install yt-dlp

Update:

brew upgrade yt-dlp

Using pip (Python required):

pip install yt-dlp

Linux

Universal (standalone binary for all distros):

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

Debian / Ubuntu / Linux Mint

sudo apt update
sudo apt install python3-pip
pip3 install --user yt-dlp

Fedora

sudo dnf install yt-dlp

If not available in your version, use the pip or binary method above.

Arch Linux / Manjaro

sudo pacman -S yt-dlp

Alpine Linux

apk add yt-dlp

Requires community repository enabled.

OpenSUSE

sudo zypper install yt-dlp

Using pip (portable, works on any distro)

pip install --user yt-dlp

Update:

pip install -U yt-dlp

Basic Usage

Download any video (default quality)

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

Download best quality available

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

Download specific quality (1080p max)

yt-dlp -f "best[height<=1080]" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Download 720p max

yt-dlp -f "best[height<=720]" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Audio Only Downloads

Download as MP3

yt-dlp -x --audio-format mp3 https://www.youtube.com/watch?v=dQw4w9WgXcQ

Download as MP3 with best quality

yt-dlp -x --audio-format mp3 --audio-quality 0 https://www.youtube.com/watch?v=dQw4w9WgXcQ

Download as WAV (lossless)

yt-dlp -x --audio-format wav https://www.youtube.com/watch?v=dQw4w9WgXcQ

Download as M4A (good for Apple devices)

yt-dlp -x --audio-format m4a https://www.youtube.com/watch?v=dQw4w9WgXcQ

File Naming

Clean filename (no video ID)

yt-dlp -o "%(title)s.%(ext)s" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Include uploader name

yt-dlp -o "%(uploader)s - %(title)s.%(ext)s" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Include upload date

yt-dlp -o "%(upload_date)s - %(title)s.%(ext)s" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Organize by uploader folder

yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" https://www.youtube.com/watch?v=dQw4w9WgXcQ

Playlist Downloads

Download entire playlist

yt-dlp https://www.youtube.com/playlist?list=...

Download playlist as MP3s

yt-dlp -x --audio-format mp3 https://www.youtube.com/playlist?list=...

Download only one video from playlist URL

yt-dlp --no-playlist https://www.youtube.com/watch?v=...&list=...

Download specific range from playlist (videos 1–5)

yt-dlp --playlist-start 1 --playlist-end 5 https://www.youtube.com/playlist?list=...

Download only new videos (skip already downloaded)

yt-dlp --download-archive downloaded.txt https://www.youtube.com/playlist?list=...

Metadata and Thumbnails

Add metadata to audio files

yt-dlp -x --audio-format mp3 --add-metadata https://www.youtube.com/watch?v=...

Embed thumbnail as album art

yt-dlp -x --audio-format mp3 --embed-thumbnail https://www.youtube.com/watch?v=...

Download thumbnail separately

yt-dlp --write-thumbnail https://www.youtube.com/watch?v=...

All metadata options combined

yt-dlp -x --audio-format mp3 --add-metadata --embed-thumbnail --write-thumbnail https://www.youtube.com/watch?v=...

Subtitles

Download video with subtitles

yt-dlp --write-subs https://www.youtube.com/watch?v=...

Download auto-generated subtitles

yt-dlp --write-auto-subs https://www.youtube.com/watch?v=...

Download specific language subtitles

yt-dlp --write-subs --sub-langs en https://www.youtube.com/watch?v=...

Embed subtitles in video

yt-dlp --embed-subs https://www.youtube.com/watch?v=...

Error Handling

Ignore errors and continue

yt-dlp -i https://www.youtube.com/playlist?list=...

Retry failed downloads

yt-dlp --retries 3 https://www.youtube.com/watch?v=...

Skip unavailable videos

yt-dlp --ignore-errors https://www.youtube.com/playlist?list=...

Advanced Options

Limit download speed (1MB/s)

yt-dlp --limit-rate 1M https://www.youtube.com/watch?v=...

Download only videos shorter than 10 minutes

yt-dlp --match-filter "duration < 600" https://www.youtube.com/playlist?list=...

Download only videos uploaded after specific date

yt-dlp --dateafter 20240101 https://www.youtube.com/playlist?list=...

Use proxy

yt-dlp --proxy http://proxy.example.com:8080 https://www.youtube.com/watch?v=...

Bash Tips and Tricks

Handle URLs with special characters

yt-dlp "https://www.youtube.com/watch?v=...&t=30s"

Escape special characters in filenames

yt-dlp -o '%(title)s.%(ext)s' https://www.youtube.com/watch?v=...

Download multiple URLs at once

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

Use a file with URLs

yt-dlp -a urls.txt

Background downloads

nohup yt-dlp https://www.youtube.com/playlist?list=... > download.log 2>&1 &

Check if command succeeded

if yt-dlp https://www.youtube.com/watch?v=...; then
    echo "Download successful"
else
    echo "Download failed"
fi

Common Issues and Solutions

"ERROR: unable to download video data"

pip install -U yt-dlp

Age-restricted videos

yt-dlp --cookies-from-browser chrome https://www.youtube.com/watch?v=...

Geo-blocked videos

yt-dlp --proxy socks5://127.0.0.1:1080 https://www.youtube.com/watch?v=...

Very long filenames

yt-dlp --trim-filenames 100 https://www.youtube.com/watch?v=...

Useful Combinations

Perfect MP3 download with metadata

yt-dlp -x --audio-format mp3 --audio-quality 0 --add-metadata --embed-thumbnail -o "%(title)s.%(ext)s" https://www.youtube.com/watch?v=...

Archive entire channel

yt-dlp -f "best[height<=1080]" --download-archive archive.txt -o "%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" https://www.youtube.com/@channelname

Download with subtitles and metadata

yt-dlp --write-subs --embed-subs --add-metadata --embed-thumbnail -o "%(title)s.%(ext)s" https://www.youtube.com/watch?v=...

Quick Reference