How to Use yt-dlp: A Practical Guide (2026)

yt-dlp is the most capable command-line YouTube (and 1,000+ other sites) downloader — a maintained fork of the discontinued youtube-dl. This guide covers the commands you'll actually use day to day: installing, downloading, choosing formats, extracting audio, and dealing with the errors that inevitably come up.

Install yt-dlp

python3 -m pip install -U "yt-dlp[default]"

yt-dlp needs ffmpeg for merging high-quality video+audio and for audio conversion — install it too (brew install ffmpeg, apt install ffmpeg, or grab a build for Windows). Full details in our install guide.

Download a video

The simplest possible command downloads the best available quality:

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

Choose the format and quality

List everything available for a video, then pick by format ID:

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

More often you just want to cap the resolution. Use the -S (sort) flag:

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

Extract audio (MP3)

To grab just the audio and convert it to MP3 (needs ffmpeg):

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

More audio options in the audio-only guide.

Handy options you'll reuse

# Name files predictably
yt-dlp -o "%(title)s.%(ext)s" URL

# Download subtitles (and auto-generated captions)
yt-dlp --write-subs --write-auto-subs --sub-lang en URL

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

# Download just a section
yt-dlp --download-sections "*00:01:30-00:02:45" URL

A fuller list lives in the commands cheat sheet.

Keep it updated

YouTube changes constantly and breaks older yt-dlp builds, so update often:

yt-dlp -U   # or: pip install -U "yt-dlp[default]"

See the update guide if -U doesn't work for your install method.

When it stops working

Two errors dominate, and both are YouTube's bot defenses rather than a mistake in your command:

• Sign in to confirm you're not a bot → see the fix guide
• HTTP Error 403: Forbidden → see the 403 fix guide

Both usually come down to updating yt-dlp, passing cookies, or getting off a flagged IP.

When to use an API instead

yt-dlp is excellent for local, one-off, and hobby use. But running it in production means owning a moving target: re-updating every couple of weeks, rotating cookies, managing proxies, and patching around YouTube's changes. If downloading YouTube is a feature of your product, a managed API removes that maintenance entirely.

Frequently asked questions