How to use yt-dlp in 2026: Complete Step-by-step guide

Want to download videos from YouTube, TikTok, or hundreds of other sites without shady websites full of ads? yt-dlp is the answer.

It's a free command-line tool that downloads video and audio from over 1,700 websites. This guide walks you through installing yt-dlp, using basic commands, and mastering advanced features like format selection and audio extraction.

What Is yt-dlp?

yt-dlp is a command-line video downloader that works with YouTube, Vimeo, TikTok, Twitter, Instagram, Reddit, and hundreds of other platforms. It's a fork of the older youtube-dl project, with faster development and more features.

The tool runs on Windows, macOS, and Linux. There's no graphical interface—you type commands in a terminal or command prompt. This might sound intimidating if you've never used a terminal before, but the basic commands are simple.

Here's what yt-dlp can do:

• Download videos in any available quality (including 4K and 8K)
• Extract audio from videos as MP3, AAC, or other formats
• Download entire playlists and channels
• Embed subtitles, thumbnails, and metadata
• Resume interrupted downloads
• Bypass geo-restrictions when combined with proxies

The tool requires FFmpeg for certain operations like merging video and audio streams or converting formats. We'll cover FFmpeg installation in the setup section.

Step 1: Install yt-dlp on Your System

Installation varies by operating system. Choose your platform below.

Windows Installation

The easiest method on Windows is downloading the executable directly.

First, go to the yt-dlp releases page on GitHub. Download the file named yt-dlp.exe.

Create a folder for yt-dlp. A good location is C:\yt-dlp. Move the downloaded executable into this folder.

Next, add this folder to your system PATH so you can run yt-dlp from any directory. Open the Windows search bar and type "environment variables." Click "Edit the system environment variables."

In the System Properties window, click "Environment Variables." Under "System variables," find the "Path" variable and click "Edit." Click "New" and add C:\yt-dlp (or whatever folder you chose).

Click OK to save changes. Open a new Command Prompt window and type yt-dlp --version to verify the installation worked.

macOS Installation

On macOS, use Homebrew for the simplest installation. If you don't have Homebrew installed, open Terminal and run:

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

Once Homebrew is ready, install yt-dlp:

brew install yt-dlp

Homebrew automatically adds yt-dlp to your PATH. Verify the installation:

yt-dlp --version

Linux Installation

Most Linux distributions offer yt-dlp in their package managers, though versions may be outdated.

For the latest version, download directly:

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

Alternatively, use pip (Python's package manager):

pip install yt-dlp

The pip method works on all platforms and makes updating easy with pip install -U yt-dlp.

Install FFmpeg (Required for Most Operations)

FFmpeg handles video/audio merging and format conversion. Without it, yt-dlp can only download pre-merged formats.

Windows: Download FFmpeg from gyan.dev. Get the "git full" build (win64-gpl.zip). Extract it and copy ffmpeg.exe from the bin folder to your yt-dlp directory.

macOS: Install via Homebrew:

brew install ffmpeg

Linux: Use your package manager:

# Debian/Ubuntu
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

# Arch
sudo pacman -S ffmpeg

Step 2: Download Your First Video

Open your terminal or command prompt. Navigate to the folder where you want to save downloads:

cd ~/Downloads

To download a video, use this basic syntax:

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

Replace VIDEO_ID with the actual video identifier from the URL. Always wrap URLs in quotes to avoid issues with special characters.

The command downloads the best available quality by default. yt-dlp automatically selects the best video and audio streams, then merges them using FFmpeg.

Here's what happens when you run this command:

1. yt-dlp connects to the website and extracts video information
2. It identifies all available formats and quality options
3. It selects the best video and audio streams
4. It downloads both streams (you'll see two progress bars)
5. FFmpeg merges them into a single file
6. The temporary files are deleted

The final file appears in your current directory with the video title as the filename.

Handling Common Download Issues

Sometimes downloads fail or behave unexpectedly. Here are common problems and solutions.

"Unable to extract" errors: The website may have changed their format. Update yt-dlp:

yt-dlp -U

Slow downloads: Some sites throttle download speeds. Try using concurrent fragment downloads:

yt-dlp -N 4 "URL"

This downloads 4 fragments simultaneously, often improving speed.

Geo-restricted content: Use a proxy or VPN. With Roundproxies residential proxies, you can access content from different regions:

yt-dlp --proxy "http://proxy-server:port" "URL"

Step 3: Control Video Quality and Format

yt-dlp's default format selection works well for most cases, but you often want specific quality or format.

List Available Formats

See what formats a video offers:

yt-dlp -F "URL"

This displays a table showing all available streams. The output includes format codes, resolutions, codecs, and file sizes. Here's example output:

ID  EXT   RESOLUTION FPS │   FILESIZE   TBR PROTO │ VCODEC          VBR ACODEC      ABR
─────────────────────────────────────────────────────────────────────────────────────────
sb0 mhtml 48x27        1 │                  mhtml │ images                              
sb1 mhtml 80x45        1 │                  mhtml │ images                              
139 m4a   audio only      │    1.58MiB   49k https │ audio only          mp4a.40.5   49k
140 m4a   audio only      │    4.19MiB  130k https │ audio only          mp4a.40.2  130k
137 mp4   1920x1080   30 │   43.11MiB 1344k https │ avc1.640028   1344k video only
248 webm  1920x1080   30 │   28.08MiB  875k https │ vp9            875k video only

Download Specific Formats

Use the format code from the list:

yt-dlp -f 137+140 "URL"

This downloads format 137 (1080p video) and format 140 (audio), then merges them.

Common Format Selection Patterns

Download the best quality up to 1080p:

yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" "URL"

This command breaks down as follows:

• bv*[height<=1080] - best video with height 1080 or less
• ba - best audio
• /b[height<=1080] - fallback to best combined format under 1080p

Download as MP4 specifically:

yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]" --merge-output-format mp4 "URL"

Download smallest file size (useful for mobile or slow connections):

yt-dlp -S "+size" "URL"

The -S flag sorts formats. The + prefix means ascending order (smallest first).

Step 4: Extract Audio Only

Converting videos to audio files is one of yt-dlp's most popular uses. The -x flag extracts audio.

Basic audio extraction:

yt-dlp -x "URL"

This downloads the best audio stream in its original format (usually Opus or AAC).

Convert to MP3:

yt-dlp -x --audio-format mp3 "URL"

Set audio quality for MP3:

yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

Audio quality ranges from 0 (best) to 10 (worst). The default is 5.

Extract audio in FLAC (lossless):

yt-dlp -x --audio-format flac "URL"

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

Step 5: Download Playlists and Channels

yt-dlp handles playlists the same way as single videos. Just provide the playlist URL:

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

Control Playlist Downloads

Download only the first 5 videos:

yt-dlp --playlist-end 5 "URL"

Download videos 10 through 20:

yt-dlp --playlist-start 10 --playlist-end 20 "URL"

Download every other video (useful for testing):

yt-dlp -I 1::2 "URL"

The -I flag uses Python slice notation: start:end:step.

Download in reverse order:

yt-dlp --playlist-reverse "URL"

Avoid Re-downloading Videos

When downloading large playlists over time, use an archive file:

yt-dlp --download-archive archive.txt "URL"

yt-dlp records downloaded video IDs in archive.txt. Future runs skip videos already in the archive. This is perfect for subscribing to channels and periodically grabbing new content.

Download Entire YouTube Channels

Channel URLs work like playlists:

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

This downloads all public videos from the channel. Combine with --download-archive for ongoing channel backups.

Step 6: Customize Output Filenames

The default filename pattern is %(title)s [%(id)s].%(ext)s. Customize it with the -o flag.

Use video title only:

yt-dlp -o "%(title)s.%(ext)s" "URL"

Include upload date:

yt-dlp -o "%(upload_date)s - %(title)s.%(ext)s" "URL"

Organize playlists into folders:

yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "URL"

This creates a folder named after the playlist and numbers files by their position.

Useful Template Variables

Common variables for output templates:

• %(title)s - Video title
• %(id)s - Video ID
• %(ext)s - File extension
• %(upload_date)s - Upload date (YYYYMMDD format)
• %(uploader)s - Channel name
• %(playlist)s - Playlist title
• %(playlist_index)s - Position in playlist
• %(resolution)s - Video resolution
• %(duration)s - Video length in seconds

Format dates nicely:

yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" "URL"

This outputs dates like "2025-01-15" instead of "20250115".

Step 7: Add Subtitles and Metadata

Download Subtitles

List available subtitles:

yt-dlp --list-subs "URL"

Download subtitles in specific languages:

yt-dlp --write-subs --sub-lang en "URL"

Download auto-generated subtitles:

yt-dlp --write-auto-subs --sub-lang en "URL"

Embed subtitles into the video file (works with MP4 and MKV):

yt-dlp --embed-subs --sub-lang en "URL"

Embed Metadata

Add video information to the file's metadata:

yt-dlp --embed-metadata "URL"

This embeds title, description, upload date, and other information that media players can display.

Download Thumbnails

Save the video thumbnail:

yt-dlp --write-thumbnail "URL"

Embed thumbnail as album art (useful for audio files):

yt-dlp -x --audio-format mp3 --embed-thumbnail "URL"

Step 8: Create a Configuration File

Typing the same options repeatedly gets tedious. Create a configuration file to set defaults.

The config file location varies by platform:

• Windows: %APPDATA%\yt-dlp\config.txt
• macOS/Linux: ~/.config/yt-dlp/config

Example configuration file:

# Output format and location
-o ~/Videos/%(uploader)s/%(title)s.%(ext)s

# Prefer MP4 format
-f bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]
--merge-output-format mp4

# Embed metadata and subtitles
--embed-metadata
--embed-thumbnail
--embed-subs
--sub-lang en

# Use archive to avoid re-downloads
--download-archive ~/.yt-dlp-archive.txt

# Concurrent fragment downloads for speed
-N 4

Lines starting with # are comments. Each option goes on its own line.

With this config, running yt-dlp "URL" automatically applies all these settings.

Step 9: Use yt-dlp With Proxies

Geo-restricted content requires accessing the site from a different location. Proxies route your connection through servers in other countries.

HTTP/HTTPS Proxy

yt-dlp --proxy "http://username:password@proxy-server:port" "URL"

SOCKS5 Proxy

yt-dlp --proxy "socks5://username:password@proxy-server:port" "URL"

When using Roundproxies residential proxies, replace the proxy details with your credentials. Residential proxies work better than datacenter proxies for video sites because they're less likely to be blocked.

Rotating Proxies for Large Downloads

When downloading many videos, rotate through multiple proxies to avoid rate limiting. Create a script that cycles through a proxy list:

#!/bin/bash
PROXIES=("proxy1:port" "proxy2:port" "proxy3:port")

for url in $(cat urls.txt); do
    PROXY=${PROXIES[$RANDOM % ${#PROXIES[@]}]}
    yt-dlp --proxy "http://$PROXY" "$url"
done

Step 10: Download From Authenticated Sites

Some content requires logging in. yt-dlp can use browser cookies for authentication.

Use Cookies From Your Browser

yt-dlp --cookies-from-browser chrome "URL"

Supported browsers: chrome, chromium, firefox, edge, opera, safari, brave, vivaldi.

This extracts cookies from your browser's profile, allowing yt-dlp to access member-only or age-restricted content you can view in the browser.

Export Cookies Manually

Alternatively, export cookies to a Netscape format file using a browser extension, then:

yt-dlp --cookies cookies.txt "URL"

Advanced Tips and Tricks

Limit Download Speed

Prevent yt-dlp from saturating your connection:

yt-dlp --limit-rate 2M "URL"

This limits downloads to 2 megabytes per second.

Resume Interrupted Downloads

yt-dlp automatically resumes partial downloads. Just run the same command again.

Download Only New Videos From a Playlist

Combine the archive feature with playlist downloads:

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

Run this command periodically (via cron job or Task Scheduler) to automatically grab new uploads.

Extract Video Metadata Without Downloading

Get video information as JSON:

yt-dlp -j --no-download "URL"

This returns metadata including title, description, duration, view count, and available formats.

Download Age-Restricted Content

Age-restricted videos require authentication:

yt-dlp --cookies-from-browser chrome "URL"

Your browser cookies prove to YouTube that you've verified your age.

Split Long Videos by Chapters

Some videos have chapters. Split them into separate files:

yt-dlp --split-chapters -o "%(title)s - %(chapter)s.%(ext)s" "URL"

Download Specific Time Ranges

Extract only a portion of a video (requires FFmpeg):

yt-dlp --download-sections "*00:01:00-00:05:00" "URL"

This downloads from 1:00 to 5:00. The asterisk indicates a time range rather than chapter name.

Troubleshooting Common Problems

"Video unavailable" Errors

The video might be region-locked. Try a proxy from a different country.

Downloads Are Slow

Enable concurrent fragment downloads:

yt-dlp -N 8 "URL"

Or try an external downloader:

yt-dlp --downloader aria2c "URL"

aria2c must be installed separately and supports multiple connections per download.

"Requested format not available"

The format you specified doesn't exist. List available formats with -F and choose a valid one.

yt-dlp Is Outdated

Sites change frequently. Keep yt-dlp updated:

yt-dlp -U

If using pip:

pip install -U yt-dlp

FFmpeg Not Found

Ensure FFmpeg is in your PATH or specify its location:

yt-dlp --ffmpeg-location /path/to/ffmpeg "URL"

Quick Reference: Essential yt-dlp Commands

Final Thoughts

yt-dlp is the most powerful tool for downloading web videos. The learning curve is minimal once you understand the basic command structure.

Start with simple downloads, then gradually incorporate format selection, output templates, and automation. The configuration file eliminates repetitive typing and ensures consistent downloads.

For geo-restricted content, pair yt-dlp with quality proxies. Residential proxies from services like Roundproxies work better than datacenter proxies because video platforms are less likely to block them.

Keep yt-dlp updated regularly. Website changes break downloaders frequently, and the yt-dlp team pushes fixes quickly.

FAQ

Is yt-dlp legal to use?

yt-dlp itself is legal software. Downloading copyrighted content without permission may violate copyright law in your jurisdiction. Use yt-dlp responsibly for content you have rights to access.

What's the difference between yt-dlp and youtube-dl?

yt-dlp is a fork of youtube-dl with faster development, more features, and quicker fixes for site changes. Most youtube-dl commands work with yt-dlp.

Can yt-dlp download from any website?

yt-dlp supports over 1,700 sites, but not every video site works. Check the supported sites list for your target platform.

Why do I need FFmpeg?

FFmpeg merges separate video and audio streams (common on YouTube) and handles format conversion. Without it, you're limited to pre-merged formats which are often lower quality.

How do I download private or unlisted videos?

Use browser cookies for authentication:

yt-dlp --cookies-from-browser chrome "URL"

You must have access to the video in your browser first.

Can I download live streams?

Yes, yt-dlp can download ongoing live streams. Use --live-from-start to capture from the beginning rather than joining mid-stream.