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 merges 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 program that downloads video and audio from YouTube, Vimeo, TikTok, Twitter, Instagram, Reddit, and more than a thousand other sites. That list includes plenty of small sites that browser extensions don't support. Before getting into how to use yt-dlp, it helps to know 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 and features piled up, so yt-dlp is now the version most people mean when they say youtube-dl. Old youtube-dl command lines mostly still work, but the two are no longer interchangeable. Guides written for youtube-dl miss most of what makes yt-dlp worth using, including SponsorBlock support, browser cookie import, and better format selection.

There is no graphical interface. You type a command in a terminal or command prompt and watch a progress bar. If you've never used a terminal, the learning curve is gentler than it looks: the shortest useful command is the program name followed by a URL. By default, yt-dlp grabs the best quality the site offers, so that one command already gets you a good result.

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 in the output along with thumbnails and metadata
• 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 required. FFmpeg does the joining. It also handles every format conversion, subtitle embed, and audio extraction.

Without FFmpeg, yt-dlp still runs, but it falls back to whatever pre-merged single file the site happens to publish, and that file sits well below the maximum available quality. Install FFmpeg alongside yt-dlp. The setup section below covers both.

How to use yt-dlp on Mac, Windows, and Linux

yt-dlp runs on Windows, macOS, and Linux, and the commands are the same on all three. Only the installation step and the app you type into differ.

• Mac: open the Terminal app (in Applications, then Utilities). Homebrew is the easiest install route because it can also install FFmpeg and keeps both updated. The official GitHub releases also include a standalone macOS build if you'd rather not use Homebrew.
• Windows: use Command Prompt or PowerShell. The official release includes a standalone .exe, and package managers such as winget can install it too.
• Linux: most distributions package yt-dlp, though distro packages can lag behind the latest release. Installing with pip or using the official binary gets you updates sooner.

Sites change their pages often enough to break downloads, and yt-dlp ships fixes frequently. On any platform, update regularly, especially when a download that used to work starts failing.

Is yt-dlp safe?

Yes, as long as you get it from an official source. The code is open source and public on GitHub, where it has a large contributor base and a long commit history, and anyone can inspect what it does. The official releases come from the yt-dlp/yt-dlp repository on GitHub, and the project publishes checksums and a public signing key so you can verify the file you downloaded. Installs through pip, Homebrew, winget, or your Linux distribution's package manager are also safe sources.

The real risk comes from copies hosted elsewhere. Unofficial download sites and repackaged installers with bundled extras can carry malware, and yt-dlp's popularity makes it an attractive name to imitate. If a site asks you to run an installer wizard or offers a premium version, close it: yt-dlp has neither.

Two other points belong under safety:

• Cookies give access to your account. When you pass browser cookies to yt-dlp, it can act as your logged-in session. Don't share exported cookie files, and don't paste them into online tools.
• Legal use is your responsibility. The software itself is legal to install and run, but downloading copyrighted content or breaking a site's terms of service can be a problem depending on what you download and where you live. Stick to content you own, content with a permissive license, or personal offline viewing where that is allowed.

Is there a yt-dlp extension for your browser?

There is no official yt-dlp browser extension. yt-dlp is a command-line program, and the project doesn't publish add-ons for Chrome, Firefox, or Safari. Anything in an extension store using the yt-dlp name was built by a third party.

If you want to avoid the terminal, you have three kinds of alternatives:

• Graphical frontends such as Tartube and yt-dlg run yt-dlp on your own machine behind buttons and menus.
• Web interfaces let you paste a yt-dlp command into a page and run it on someone else's server. They're convenient for one-off downloads, but your request and files pass through a service you don't control.
• Userscripts and helper extensions add a download button to video pages and hand the URL to a local yt-dlp install or a web service.

Apply the same caution to these that you would to any unofficial download. A frontend that runs your local yt-dlp is the lowest-risk option, because the downloading still happens in the official program. Learning the handful of commands in this guide keeps you independent of any wrapper, and those commands work the same way when a frontend breaks or disappears.

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"

It's 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.