article thumbnail
A Master Class on YT-DLP
The definitive tool of choice for downloading videos
#ytdlp, #commandlinetools

In the ever-changing landscape of online media, yt-dlp has emerged as the definitive tool for downloading videos from YouTube and over 1,000 other websites. This powerful command-line utility offers capabilities far beyond simple video downloads, enabling users to automate workflows, customize output formats, and efficiently manage large media collections. Whether you're an educator archiving educational material, a researcher collecting video data, or simply someone who wants to watch videos offline, yt-dlp provides the robust functionality you need.

The Origins of YT-DLP

YT-DLP (YouTube DownLoader Plus) began as a fork of youtube-dlc (community edition), which itself was a fork of the original youtube-dl. Created in 2021, yt-dlp has rapidly evolved to become the go-to solution for media downloads, distinguished by active development, frequent updates, and an impressive feature set that extends well beyond its predecessors.

By 2025, yt-dlp has been officially integrated into many major Linux distributions, including Ubuntu and Debian, replacing the now-stagnant youtube-dl. This widespread adoption is a testament to its reliability and continuing development.

Installation Guide

Let's start by getting yt-dlp installed on your system of choice:

Windows Installation

Windows users have several installation options:

Using Chocolatey (recommended)

The easiest approach is using the Chocolatey package manager:

  1. Open a PowerShell window with administrator privileges
  2. Run the following command to install Chocolatey if you don't already have it:
    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
  1. Install yt-dlp and its dependencies:
    choco install yt-dlp ffmpeg

Direct Download

Alternatively, you can:

  1. Download the latest executable from the official GitHub releases page
  2. Place it in a directory of your choice (e.g., C:\Program Files\yt-dlp\)
  3. Add that directory to your system PATH environment variable
  4. Install FFmpeg separately for full functionality

macOS Installation

For Mac users, Homebrew provides the simplest installation method:

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

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

Linux Installation

Debian/Ubuntu and derivatives

For Ubuntu 22.04 or newer, yt-dlp is available in the official repositories:

sudo apt update
sudo apt install yt-dlp ffmpeg

For older versions, you can use a PPA:

sudo add-apt-repository ppa:tomtomtom/yt-dlp
sudo apt update
sudo apt install yt-dlp ffmpeg

Using pip (all Linux distributions)

python3 -m pip install -U yt-dlp

Android Installation via Termux

Android users can install yt-dlp through Termux:

# Set up storage access
termux-setup-storage
# Update packages
pkg update && pkg upgrade
# Install Python and pip
pkg install python python-pip
# Install yt-dlp
pip install -U "yt-dlp[default]"
# Install ffmpeg for format conversion
pkg install ffmpeg

Basic Usage

Now that yt-dlp is installed, let's explore its core functionality:

Downloading a Video

The simplest command downloads a video at its default quality:

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

Listing Available Formats

To see all available formats for a video:

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

This will display a table showing format codes, extensions, resolution, and other details.

Selecting a Specific Format

To download a specific format, use the -f option followed by the format code:

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

Common Format Selectors

Instead of specific format codes, you can use these practical selectors:

  • best: Best quality that includes both video and audio
  • worst: Lowest quality with both video and audio
  • bestvideo: Best video-only format
  • bestaudio: Best audio-only format

  • bestvideo+bestaudio: Best video and best audio downloaded separately and merged

    For example:

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

This command selects the best video format with height less than or equal to 1080p and the best audio format, merging them together.

Advanced Features

YT-DLP's power lies in its advanced features that cater to specific needs:

Downloading Playlists

Download an entire playlist:

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

Download a specific range of videos in a playlist:

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

Extracting Audio

Extract audio in your preferred format:

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

Available audio formats include mp3, aac, flac, m4a, opus, vorbis, and wav.

Custom Output Templates

Control how files are named using output templates:

yt-dlp -o "%(uploader)s/%(playlist_title)s/%(playlist_index)s - %(title)s.%(ext)s" https://www.youtube.com/playlist?list=example

Common template variables include:

  • %(title)s: Video title
  • %(id)s: Video ID
  • %(uploader)s: Channel name
  • %(upload_date)s: Upload date (YYYYMMDD)
  • %(playlist_index)s: Position in playlist
  • %(playlist_title)s: Playlist title
  • %(ext)s: File extension

Embedding Metadata and Thumbnails

Add metadata to your downloads:

# Add metadata
yt-dlp --embed-metadata https://www.youtube.com/watch?v=example

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

Downloading Subtitles

Download video subtitles:

# Download all available subtitles
yt-dlp --all-subs https://www.youtube.com/watch?v=example

# Download only English subtitles
yt-dlp --sub-lang en https://www.youtube.com/watch?v=example

# Convert subtitles to SRT format
yt-dlp --convert-subs srt --sub-lang en https://www.youtube.com/watch?v=example

Unique YT-DLP Features

YT-DLP introduces several innovative features not available in its predecessors:

SponsorBlock Integration

Skip or remove sponsored segments, intros, outros, and more using the SponsorBlock API:

# Mark sponsor segments
yt-dlp --sponsorblock-mark sponsor https://www.youtube.com/watch?v=example

# Remove sponsor segments
yt-dlp --sponsorblock-remove sponsor,intro,outro https://www.youtube.com/watch?v=example

Chapter Handling

Split videos by chapters into separate files:

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

Partial Downloads

Download specific sections of a video:

# Download from 1 minute to 2 minutes
yt-dlp --download-sections "*1:00-2:00" https://www.youtube.com/watch?v=example

Live Stream and Scheduled Video Support

Wait for scheduled streams to become available:

yt-dlp --wait-for-video 300 https://www.youtube.com/watch?v=example

Download live streams from the current time:

yt-dlp --live-from-start https://www.youtube.com/watch?v=example

Improved Format Selection

YT-DLP offers advanced format sorting to prioritize higher resolutions and better codecs:

yt-dlp --format-sort res,codec:h264 https://www.youtube.com/watch?v=example

Configuration and Automation

Configuration File

Create a configuration file to set default options. The file can be placed at:

  • Windows: %APPDATA%\yt-dlp\config or C:\Users\<user>\yt-dlp.conf

  • Linux/macOS: ~/.config/yt-dlp/config or ~/.yt-dlp.conf

    Example configuration:

# Always extract audio
-x
# Use mp3 format for audio
--audio-format mp3
# Add metadata
--embed-metadata
# Save all videos under Videos directory
-o ~/Videos/%(title)s.%(ext)s

Practical Workflows

Archiving a YouTube Channel

To archive an entire YouTube channel:

yt-dlp -f "bestvideo+bestaudio/best" -o "%(uploader)s/%(upload_date)s - %(title)s.%(ext)s" --download-archive archive.txt https://www.youtube.com/c/ChannelName/videos

The --download-archive option tracks downloaded videos in a text file, allowing you to run the command periodically without re-downloading existing videos.

Creating a Music Library

To build a music library from YouTube Music:

yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --embed-metadata -o "Music/%(artist)s/%(album)s/%(track_number)s - %(title)s.%(ext)s" https://music.youtube.com/playlist?list=example

Educational Video Collection

For educators collecting course materials:

yt-dlp -f "bestvideo[height<=720]+bestaudio/best" --write-auto-sub --sub-lang en --embed-subs -o "Courses/%(playlist)s/%(chapter_number)s - %(chapter)s/%(playlist_index)s - %(title)s.%(ext)s" --embed-thumbnail --embed-metadata https://www.youtube.com/playlist?list=example

Best Practices

  1. Respect copyright and terms of service - Only download content you have the right to access and store
  2. Use reasonable rate limiting - Avoid aggressive downloading that may trigger anti-abuse measures
  3. Keep the tool updated - Run yt-dlp -U regularly to maintain compatibility with site changes
  4. Use specific format selectors - Download only the quality you need to save bandwidth and storage
  5. Implement download archives - Track downloaded files to avoid duplicates in large archiving projects

Conclusion

YT-DLP stands as the definitive solution for media downloads in 2025, offering unparalleled flexibility, powerful features, and exceptional reliability. From simple video downloads to sophisticated media archiving workflows, yt-dlp provides the tools necessary to efficiently manage online content for offline use.

By mastering yt-dlp, you gain control over your media consumption, enabling access to content on your terms, in your preferred format, and on any device. Whether you're backing up your own content, creating an educational resource library, or simply enjoying videos offline, yt-dlp offers a solution that's both powerful and adaptable to your specific needs.

Continue exploring yt-dlp's extensive documentation and community resources to discover even more capabilities and refine your workflows. Happy downloading!

Wow, thanks for reading! See you next week. As a bonus for reading this far, here is a table of the most common arguments of yt-dlp and how to use them

Argument Description Example
-f or --format Select video and/or audio format yt-dlp -f bestvideo+bestaudio URL
-o or --output Set output filename template yt-dlp -o "%(title)s.%(ext)s" URL
-P or --paths Set custom download directories yt-dlp -P "~/Videos" URL
--merge-output-format Force final file format after merging yt-dlp --merge-output-format mp4 URL
-S Format sorting, prioritization of qualities yt-dlp -S "+res,+fps" URL
--download-sections Download specific time ranges yt-dlp --download-sections "*00:01:00-00:02:00"
--embed-subs Embed subtitles into video yt-dlp --embed-subs URL
--write-subs Download subtitles (if available) yt-dlp --write-subs URL
--sub-langs Choose subtitle languages yt-dlp --write-subs --sub-langs "en.*" URL
--embed-metadata Embed metadata into media file yt-dlp --embed-metadata URL
--embed-thumbnail Embed thumbnail image yt-dlp --embed-thumbnail URL
--add-metadata Add additional metadata (e.g., title, uploader) yt-dlp --add-metadata URL
--no-mtime Don't use the Last-Modified time as file mtime yt-dlp --no-mtime URL
--write-info-json Save video metadata in a JSON file yt-dlp --write-info-json URL
--download-archive Keep track of downloaded videos to skip duplicates yt-dlp --download-archive archive.txt URL
--no-playlist Download only the video, not the whole playlist yt-dlp --no-playlist URL
--playlist-items Download specific videos in a playlist yt-dlp --playlist-items 1,3,5 URL
--cookies Use cookies from a file (for private content) yt-dlp --cookies cookies.txt URL
--username / --password Login credentials for sites requiring authentication yt-dlp --username user --password pass URL
-N or --concurrent-fragments Number of threads for fragmented downloads yt-dlp -N 8 URL
--limit-rate Limit download speed yt-dlp --limit-rate 1M URL
--user-agent Custom user agent string yt-dlp --user-agent "Mozilla/5.0" URL
--referer Set HTTP referer header yt-dlp --referer https://example.com URL
--no-check-certificate Ignore SSL certificate verification yt-dlp --no-check-certificate URL