Basic downloads
With no options at all, yt-dlp picks the best combination it can merge and names the file after the title. This is the right command surprisingly often.
yt-dlp URL
Before downloading something large, it is worth seeing what is actually on offer. This prints the format table and exits without downloading anything.
yt-dlp -F URL
The left column of that table is the format id, which you can then request directly. Two ids joined with + means "download both and merge them".
yt-dlp -f 137+140 URL
Quality and format selection
Hard-coded format ids break as soon as a site changes its encoding ladder. A selector expression is the durable version: ask for the properties you want and let yt-dlp find the best match.
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" URL
Read it as: the best video stream no taller than 1080 plus the best audio, and if that pair does not exist, the best single file no taller than 1080. That fallback after the slash is what stops the command failing on sites that publish only progressive streams.
Merging two streams produces a container yt-dlp has to choose. MP4 plays everywhere; MKV accepts anything you throw at it, which matters once subtitles and chapters are involved.
yt-dlp -f "bv*+ba" --merge-output-format mp4 URL
To express a preference rather than a hard limit, sort instead of filter. This prefers 1080p and MP4 but still downloads something when neither is available.
yt-dlp -S "res:1080,ext:mp4" URL
Audio and MP3
Extracting audio needs ffmpeg — this is the single most common reason the command below fails on a fresh install.
yt-dlp -x --audio-format mp3 URL
Adding cover art and tags takes two more flags and makes the result usable in a music library rather than a folder of anonymous files.
yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --embed-metadata URL
--audio-quality 0 is variable bitrate at the best setting, not "zero quality". If you need a fixed bitrate, give it one: --audio-quality 320K.
When the source is already AAC or Opus, converting to MP3 re-encodes and loses quality for nothing. Keeping the original is both faster and better.
yt-dlp -x --audio-format best URL
Subtitles
Embedded subtitles travel with the file; separate .srt files are easier to edit and to feed to something else.
yt-dlp --embed-subs --sub-langs en URL yt-dlp --write-subs --sub-langs en,vi --convert-subs srt URL
Machine-generated captions are a separate switch. Without it, a video with no human subtitles produces nothing at all and no error.
yt-dlp --write-auto-subs --sub-langs en --convert-subs srt --skip-download URL
Playlists and channels
A YouTube URL often belongs to both a video and a playlist, and yt-dlp has to guess which you meant. Say so explicitly.
yt-dlp --no-playlist URL yt-dlp --yes-playlist URL
For anything long, the archive file matters more than any other option here: it records what has been downloaded so a re-run picks up where it stopped instead of starting over.
yt-dlp --yes-playlist -i \ --download-archive archive.txt \ -o "%(playlist_index)02d - %(title)s.%(ext)s" \ URL
Combined with -i, one region-locked or deleted video no longer aborts the other two hundred. To grab a slice rather than everything, -I takes ranges and lists: -I 1:10, -I "1,3,7-10".
Clips, chapters and sponsors
You can download part of a video instead of all of it. The leading asterisk marks a timestamp rather than a chapter name, and the quotes are mandatory — bash expands a bare * against your filenames.
yt-dlp --download-sections "*00:01:30-00:03:00" URL
SponsorBlock uses community-submitted markers to cut segments out entirely, or to leave them in as chapters you can skip yourself.
yt-dlp --sponsorblock-remove default URL yt-dlp --sponsorblock-mark all --embed-chapters URL
File names and folders
The output template controls both. A slash creates a directory, so one template can lay out an entire archive.
yt-dlp -o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" URL
Titles routinely contain characters some filesystems reject. --restrict-filenames reduces everything to plain ASCII, which is worth it for anything that will be moved between machines.
In a Windows .bat file every % must be doubled — %%(title)s — or the batch interpreter eats the template before yt-dlp sees it. The generator does this for you when you download a .bat.
Errors you will actually hit
ffmpeg not found
Anything that merges, converts, embeds or cuts needs ffmpeg on your PATH. Install it, then confirm with ffmpeg -version.
Sign in to confirm you are not a bot
Try --impersonate chrome first, then --cookies-from-browser. If both fail, update yt-dlp — this particular check changes often and the fix usually arrives in a release within days.
Unable to extract player response
Almost always an out-of-date yt-dlp. Update it before changing anything else: yt-dlp -U, or your package manager if you installed it that way.
Requested format is not available
Your selector matched nothing. Run -F to see what exists, and prefer a sort (-S) over a hard filter so there is always a fallback.
HTTP Error 403
The URL was signed for a different session or region. Re-run with fresh cookies, add --impersonate chrome, or try --geo-bypass.
Keeping yt-dlp current
More reported bugs are fixed by updating than by any flag. If you installed the standalone binary:
yt-dlp -U
Installed through a package manager, update it the same way you installed it — -U will refuse, and it is right to.