The Complete Guide to yt-dlp: Download YouTube Videos Easily and for Free

In a world that’s always online, saving videos for offline viewing is super handy. yt-dlp steps in as a fast, powerful, and free way to do it.

yt-dlp is an open-source command-line tool based on youtube-dl that can download video and audio from 1,700+ websites. It’s not just for YouTube — it also supports TikTok, Instagram, Twitter (X), Vimeo, BBC iPlayer, and hundreds more.

From youtube-dl to yt-dlp

yt-dlp began as a community fork when development on youtube-dl slowed. It set out to fix limitations and quickly became the go-to choice thanks to:

Faster downloads with multi-threading
Frequent releases (often weekly or biweekly)
Better error handling and auto-retries
Built-in SponsorBlock to skip sponsored segments

Standout Features

Broad site support: With coverage for 1,700+ sites, yt-dlp is one of the most capable downloaders around.

Advanced format control: Pick exact video resolutions, codecs, and containers; download video-only or audio-only.

Smart playlist handling: Grab entire playlists, full channels, or just specific items.

Subtitle workflow: Download, embed, or convert multilingual subtitles.

Why use yt-dlp?

Free and open source: No paywalls, no ads, no hidden caps.

Fast updates: Keeps pace with site changes.

Highly flexible: Tweak every step of the download pipeline.

Private and safe: No need to hand data to third-party web services.

Installation Guide

System Requirements

Python 3.6+ (Python 3.8+ recommended)
FFmpeg (for muxing/remuxing and audio/video processing)
A stable internet connection

Windows

Method 1: Chocolatey (recommended)

choco install yt-dlp

Method 2: Scoop

scoop install yt-dlp

Method 3: Direct download

Visit the GitHub Releases
Download yt-dlp.exe
Put it somewhere on your PATH or run it directly

Method 4: pip

python -m pip install -U yt-dlp

macOS

Method 1: Homebrew (recommended)

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install yt-dlp and FFmpeg
brew install yt-dlp
brew install ffmpeg

Method 2: MacPorts

sudo port install yt-dlp

Method 3: Download binary

curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos -o yt-dlp
chmod +x yt-dlp
sudo mv yt-dlp /usr/local/bin/

Linux

Ubuntu/Debian

sudo apt update
sudo apt install yt-dlp

Arch/Manjaro

sudo pacman -S yt-dlp

Fedora

sudo dnf install yt-dlp

Universal method (any distro)

# Using curl
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

# Or using wget
sudo wget 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

Update yt-dlp

# Self-update
yt-dlp -U

# Or via pip
python -m pip install -U yt-dlp

Common Issues

“command not found”: Ensure yt-dlp is on your PATH or call it with the full path.

Python errors: Verify Python 3.6+ is installed and selected.

FFmpeg errors: Install FFmpeg so yt-dlp can process media correctly.

Using yt-dlp: From Basics to Pro

Basic Commands

Download a single video

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

Audio-only (MP3)

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

Download a playlist

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

List available formats without downloading

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

Advanced Options

Choose specific quality

# 1080p video + best audio
yt-dlp -f 'bv*[height=1080]+ba' https://www.youtube.com/watch?v=VIDEO_ID

# Best available video + best audio
yt-dlp -f 'bv*+ba' https://www.youtube.com/watch?v=VIDEO_ID

Download with subtitles

# All available subtitles
yt-dlp --write-sub --all-subs https://www.youtube.com/watch?v=VIDEO_ID

# Vietnamese subtitles only
yt-dlp --write-sub --sub-lang vi https://www.youtube.com/watch?v=VIDEO_ID

Custom output filename

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

Batch download from a URL list

# urls.txt contains one URL per line
yt-dlp -a urls.txt

Playlist Superpowers

Grab specific items

# Only the 5th video
yt-dlp --playlist-items 5 PLAYLIST_URL

# Items 2,3,7,10
yt-dlp --playlist-items 2,3,7,10 PLAYLIST_URL

# From item 10 to the end
yt-dlp --playlist-start 10 PLAYLIST_URL

Integrations

GUI options

yt-dlp-gui — simple desktop front end
Tartube — feature-rich manager
Media Downloader — cross-platform

Use in a Python script

import yt_dlp

ydl_opts = {
    'format': 'best[height<=720]',
    'outtmpl': '%(title)s.%(ext)s',
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=VIDEO_ID'])

Configuration File

Create a config file to store your defaults:

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

Windows: %APPDATA%/yt-dlp/config

# Example config
--extract-audio
--audio-format mp3
--output "~/Downloads/%(title)s.%(ext)s"
--write-thumbnail
--embed-metadata

Final Thoughts: A Must-Have Tool

yt-dlp isn’t just a downloader — it’s a full toolbox for managing online media. With support for thousands of sites, speedy downloads, and deep customization, it’s a top pick for:

Creators: Safely back up and archive videos
Educators: Save learning materials for offline use
Researchers: Collect datasets for analysis
Everyday users: Watch favorites anytime, anywhere