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

yt-dlp is a free command-line downloader that pulls video and audio from over 1,700 websites, YouTube and TikTok included. It's a fork of youtube-dl, it's still actively maintained, and it's what I use instead of the ad-choked "online downloader" sites that re-encode your file and hide the real button behind three redirects.

The trade-off is that there's nothing to click. You type a command, and the tool does exactly what you asked. That feels like a wall on day one and like a superpower a week later, once you know the handful of flags that actually matter: pick a specific resolution, strip out just the audio as MP3, queue an entire playlist, or re-run a channel and skip everything you already have.

This guide covers how to use yt-dlp from a cold start: installing it on Windows, macOS, and Linux; adding FFmpeg, which yt-dlp needs to merge the separate video and audio streams that sites like YouTube serve; your first download; listing and choosing formats instead of accepting the default; extracting audio; naming files with output templates; and fixing the errors that show up when a site changes something.

If you only ever learn one command, learn the plain one with a URL after it. Everything else in this guide is refinement on top of that.

What is yt-dlp?

yt-dlp is a free, open-source command-line downloader for video and audio. It handles YouTube, Vimeo, TikTok, Twitter, Instagram, Reddit, and thousands of other sites, including plenty of small ones that browser extensions never support. Before getting into how to use yt-dlp, it's worth knowing what you're installing: one program written in Python, released under the Unlicense, with no ads, no paywalled tier, and no daily download cap.

It began as a fork of youtube-dl. Development on the fork moved faster, features piled up, and yt-dlp is now the version almost everyone means when they talk about "youtube-dl". Old youtube-dl command lines mostly still work, but the two are no longer interchangeable, and guides written for youtube-dl will miss most of what makes yt-dlp worth using.

The tool runs on Windows, macOS, and Linux. There is no graphical interface. You type a command in a terminal or command prompt and watch a progress bar. If you have never touched a terminal, that sounds worse than it is, because the shortest useful command is the program name followed by a URL.

What yt-dlp can do

• Download video in any format the site offers, including 4K and 8K where the source has it
• Extract audio only and convert it to mp3, m4a, flac, opus, vorbis, or wav
• Pull entire playlists and channels, with an archive file so a repeat run only fetches what's new
• Write subtitles to a separate file or embed them, along with thumbnails and metadata, directly into the output
• Resume interrupted downloads instead of starting over
• Record livestreams in a container that survives a dropped connection
• Authenticate with browser cookies for private, members-only, or age-restricted content
• Skip sponsor segments using SponsorBlock data
• Reach region-locked videos when routed through a proxy

Why you also need FFmpeg

Left to its own devices, yt-dlp picks the best video stream and the best audio stream and joins them into one file. YouTube and most large platforms serve high-resolution video and audio as separate downloads, so that join is not optional. FFmpeg does the joining, and it also does every format conversion, subtitle embed, and audio extraction.

Skip FFmpeg and yt-dlp still runs, but it falls back to whatever pre-merged single file the site happens to publish, which sits well below the maximum available quality. Install it. We cover how in the setup section below.

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 its 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

After plain downloads, pulling out the audio track is the most common thing people want from yt-dlp. The -x flag (long form --extract-audio) keeps the audio stream and discards the video.

yt-dlp -x "URL"

This downloads the best audio stream in its original format (usually Opus or AAC). Nothing is re-encoded, so it finishes about as fast as the download itself and loses nothing relative to the source. The extension you end up with depends on what the site served: .webm for Opus, .m4a for AAC.

Choosing an audio format

MP3 is the format everything plays, from car stereos to a decade-old MP3 player:

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

Worth understanding what that command actually does. The audio on YouTube and most video sites is already lossy, so converting it to MP3 means re-encoding lossy audio into another lossy codec. You lose a little quality and gain compatibility. That trade is fine if some device or app in your chain only speaks MP3. If nothing forces your hand, I'd use --audio-format best instead, which keeps the original stream and skips the conversion entirely.

Controlling quality

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

Audio quality ranges from 0 (best) to 10 (worst). The default is 5. The flag only has an effect when yt-dlp is genuinely re-encoding, so pairing it with --audio-format best does nothing at all.

FLAC and lossless output

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

FLAC is lossless, but it cannot recover detail the source never had. Encoding a compressed YouTube stream to FLAC gives you a much larger file that sounds exactly like the Opus you started with. The one good reason to do it is a downstream tool that refuses anything but lossless input, such as a mastering or transcription pipeline.

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

Useful companions to -x

-k (or --keep-video) leaves the original video file next to the extracted audio, which saves a second download if you decide later that you wanted both.

--embed-thumbnail writes the video thumbnail in as cover art, and --embed-metadata fills in title, uploader, and upload date as tags. For anything landing in a music library this is worth adding by default, because retagging dozens of files by hand afterwards is miserable.

For a whole playlist of tracks, combine extraction with an output template such as -o "%(playlist_index)s - %(title)s.%(ext)s" so the files sort in the original order rather than alphabetically.

If extraction fails

Every conversion here is done by ffmpeg, not by yt-dlp itself. If you get an error mentioning ffmpeg, or -x hands you a video file, install ffmpeg and put it on your PATH before you start changing flags. Plain -x with no --audio-format is also the fastest thing to test with, since it needs the least post-processing.

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 a 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

That covers the commands that handle the vast majority of real downloads.

The configuration file eliminates repetitive typing.

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. Site changes break extractors often, and the team usually ships a fix within days.

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.