yt-dlp: The Ultimate Open-Source Powerhouse for Video & Audio Downloads (2026 Guide)

If you have ever needed to save a video, extract audio, or archive an entire YouTube playlist, you have likely heard of youtube-dl. Its active fork, yt-dlp, has become the gold standard for open-source media downloading. Unlike browser extensions or shady online converters, yt-dlp is transparent, scriptable, and works with over 1,700 websites — from YouTube and Vimeo to Twitter, Twitch, and even educational platforms.

In this comprehensive guide, you will master every essential concept — from basic downloads to advanced cookie authentication, SponsorBlock integration, proxy configuration, and output templating.

Official Repository: github.com/yt-dlp/yt-dlp

Installation Across All Platforms

Before running any commands, you need yt-dlp installed on your system. Choose your platform:

Linux (Ubuntu / Debian)

The fastest method is through pip, Python’s package manager:

sudo apt update && sudo apt install python3-pip ffmpeg
pip install yt-dlp

Alternatively, install from the official Debian repositories:

sudo apt install yt-dlp

macOS (Homebrew)

Homebrew automatically handles all dependencies including ffmpeg:

brew install yt-dlp ffmpeg

Windows (winget)

The recommended approach for Windows users:

winget install yt-dlp ffmpeg

You can also download the standalone .exe from the official GitHub releases page.

Important: ffmpeg is a critical dependency. Without it, yt-dlp cannot merge separate video and audio streams or convert formats. Always install ffmpeg alongside yt-dlp.

After installation, verify everything is working:

yt-dlp --version

Understanding Format Selection

yt-dlp does not just grab one file — modern video platforms serve video and audio as separate streams. Understanding format selection gives you full control over the quality and size of your downloads.

Listing All Available Formats

To see every available stream for a video, run:

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

This outputs a table showing format codes, extensions, resolutions, file sizes, and codecs for every available stream.

Downloading a Specific Format

Once you identify the format codes you want (e.g., 137 for 1080p video and 140 for high-quality audio), combine them:

yt-dlp -f 137+140 "https://www.youtube.com/watch?v=VIDEO_ID"

Smart Format Selection

Instead of remembering format codes, you can describe what you want in plain language:

# Best video + best audio (default behavior)
yt-dlp -f "bv*+ba/b" "URL"

# Best video up to 720p with best audio
yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" "URL"

# Best video with a maximum file size of 100MB
yt-dlp -f "bv*[filesize<100M]+ba/b" "URL"

Extracting Audio (MP3, FLAC, WAV)

For podcasts, music, and interviews where you only need the audio:

# Extract as MP3 at the highest quality
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

# Extract as lossless FLAC
yt-dlp -x --audio-format flac "URL"

# Extract as WAV (uncompressed)
yt-dlp -x --audio-format wav "URL"

The --audio-quality flag accepts values from 0 (best) to 9 (worst). For MP3, 0 corresponds to a 320 kbps bitrate.

Cookies and Authentication: Accessing Restricted Content

This is one of the most important and frequently asked topics. Many websites serve different content (or block access entirely) depending on whether you are logged in. yt-dlp provides two powerful methods to handle this.

Method 1: Extract Cookies from Your Browser (Recommended)

yt-dlp can automatically read cookies directly from your browser’s cookie storage. This is the easiest and most secure approach:

# Extract cookies from Firefox
yt-dlp --cookies-from-browser firefox "URL"

# Extract cookies from Chrome
yt-dlp --cookies-from-browser chrome "URL"

# Extract cookies from Brave
yt-dlp --cookies-from-browser brave "URL"

# Extract cookies from Edge
yt-dlp --cookies-from-browser edge "URL"

Method 2: Using a Cookies File (Netscape Format)

If you prefer, you can export your cookies to a file and pass it to yt-dlp:

yt-dlp --cookies /path/to/cookies.txt "URL"

You can export cookies from your browser using extensions like “Get cookies.txt LOCALLY” for Chrome or Firefox.

Method 3: Username and Password

For sites that support direct login:

yt-dlp -u "your_username" -p "your_password" "URL"

Authentication with netrc

For a more secure approach that avoids typing passwords on the command line, you can store credentials in a .netrc file:

# Create or edit ~/.netrc
echo "machine youtube login your_email password your_password" >> ~/.netrc
chmod 600 ~/.netrc

# Then simply run
yt-dlp --netrc "URL"

Security Tip: Always set restrictive file permissions on your .netrc file using chmod 600 to prevent other users on your system from reading your credentials.

Configuration Files: Save Your Preferred Settings

Instead of typing the same flags every time, you can store your preferred options in a configuration file. yt-dlp reads from these locations automatically:

Example Configuration File

# Always download best quality video + audio
-f bv*+ba/b

# Embed subtitles, metadata, and thumbnail into the file
--embed-subs
--embed-metadata
--embed-thumbnail

# Use cookies from Firefox
--cookies-from-browser firefox

# Save files in organized folders
-o ~/Downloads/yt-dlp/%(uploader)s/%(title)s.%(ext)s

# Skip sponsored segments automatically
--sponsorblock-remove default

# Be polite to servers
--sleep-interval 2
--max-sleep-interval 5

Once saved, every yt-dlp command you run will automatically use these settings. You can override any option on the command line, and you can disable the configuration file entirely with --ignore-config.

Output Templates: Organize Your Downloads

The -o flag accepts powerful template strings that let you organize downloads into clean folder structures:

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

# Organize playlists with numbered files
yt-dlp -o "%(playlist)s/%(playlist_index)03d - %(title)s.%(ext)s" "PLAYLIST_URL"

# Include upload date in filename
yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" "URL"

Commonly Used Template Variables

SponsorBlock Integration: Skip Ads Automatically

yt-dlp has built-in integration with SponsorBlock, a community-driven database that identifies sponsored segments, intros, outros, and filler content in YouTube videos.

Remove Sponsored Segments from Downloaded Videos

# Remove all default sponsor segments
yt-dlp --sponsorblock-remove default "URL"

# Remove specific categories
yt-dlp --sponsorblock-remove sponsor,intro,outro "URL"

# Mark segments as chapters instead of removing them
yt-dlp --sponsorblock-mark default "URL"

Available SponsorBlock Categories

Network, Proxy, and Geo-Bypass Options

Using a Proxy

Route your traffic through a proxy server to bypass network restrictions:

# HTTP proxy
yt-dlp --proxy "http://proxy_address:port" "URL"

# SOCKS5 proxy
yt-dlp --proxy "socks5://proxy_address:port" "URL"

Geo-Restriction Bypass

Some videos are locked to specific countries. yt-dlp offers a built-in geo-bypass:

# Automatic geo-bypass
yt-dlp --geo-bypass "URL"

# Spoof a specific country
yt-dlp --geo-bypass-country US "URL"

Rate Limiting and Throttle Prevention

Prevent your ISP from throttling your downloads or avoid being rate-limited by the server:

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

# Add random delays between playlist downloads
yt-dlp --sleep-interval 3 --max-sleep-interval 10 "PLAYLIST_URL"

# Use concurrent fragment downloads for faster speeds
yt-dlp --concurrent-fragments 4 "URL"

Subtitles and Metadata

Downloading Subtitles

# Download English subtitles
yt-dlp --write-subs --sub-lang en "URL"

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

# Download all available subtitle languages
yt-dlp --all-subs "URL"

# Embed subtitles directly into the video file
yt-dlp --embed-subs --sub-lang en "URL"

Embedding Metadata and Thumbnails

Embed rich metadata directly into your downloaded files — perfect for media servers like Jellyfin or Plex:

# Embed metadata (title, uploader, date, description)
yt-dlp --embed-metadata "URL"

# Embed the video thumbnail as cover art
yt-dlp --embed-thumbnail "URL"

# Embed chapters (if available)
yt-dlp --embed-chapters "URL"

# All-in-one: embed everything
yt-dlp --embed-metadata --embed-thumbnail --embed-subs --embed-chapters "URL"

Playlist and Channel Downloads

Download an Entire Playlist

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

Download Only Specific Items from a Playlist

# Download only videos 1 through 5
yt-dlp --playlist-items 1-5 "PLAYLIST_URL"

# Download videos 1, 3, 5, and 7
yt-dlp --playlist-items 1,3,5,7 "PLAYLIST_URL"

# Download the last 3 videos
yt-dlp --playlist-items -3: "PLAYLIST_URL"

Download an Entire Channel

yt-dlp "https://www.youtube.com/@ChannelName/videos"

Archive Mode: Never Download the Same Video Twice

When archiving large channels over time, use --download-archive to track what has already been downloaded:

yt-dlp --download-archive archive.txt "https://www.youtube.com/@ChannelName"

This creates an archive.txt file that logs every downloaded video ID. On subsequent runs, yt-dlp will skip videos already in the archive.

Downloading from Non-YouTube Platforms

yt-dlp supports over 1,700 websites natively. Here are examples for popular platforms:

# Twitter / X
yt-dlp "https://x.com/user/status/1234567890"

# Instagram Reels
yt-dlp --cookies-from-browser firefox "https://www.instagram.com/reel/xyz"

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

# Reddit Videos
yt-dlp "https://www.reddit.com/r/subreddit/comments/abc123/"

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

Note: Some platforms like Instagram require authentication via cookies to access content. Use --cookies-from-browser as shown above.

Troubleshooting Common Errors

Pro Tip: The single most effective fix for any yt-dlp error is to update to the latest version. The developers push bug fixes and new site extractors multiple times per week: pip install -U yt-dlp

Quick Reference Cheat Sheet

Here is a compact reference of the most commonly used commands:

Conclusion

yt-dlp is far more than a simple video downloader — it is a complete media acquisition toolkit that puts you in full control of your content. From extracting browser cookies for authenticated downloads, to automatically removing sponsored segments, to organizing thousands of files with custom output templates, yt-dlp handles it all from a single command line.

The project is actively maintained by a passionate open-source community, with new site extractors and bug fixes added every single week. Bookmark the official yt-dlp GitHub repository and keep it updated to ensure you always have access to the latest features.

“Learn it once, use it forever — no subscriptions required.”

Found this guide helpful? Subscribe to our newsletter for more weekly open-source tool tutorials and self-hosting guides!