yt-dlp flag reference

Format and quality

What actually gets downloaded. If a command produces the wrong resolution, the answer is in this group.

-F, --list-formats

Print every format the site offers for this URL and exit. The first thing to run when a download comes out at the wrong quality.

-f, --format FORMAT

Which format to download, as a selector expression. Accepts fallbacks separated by /, and combinations joined by +.

-S, --format-sort SORTORDER

Rank the available formats instead of naming one. -S "res:1080,codec:h264" is easier to get right than an equivalent -f.

--merge-output-format FORMAT

Container to merge separate video and audio into. mp4 for compatibility, mkv for anything.

--format-sort-force

Apply --format-sort even where yt-dlp would normally defer to the site's own ordering.

--video-multistreams

Allow more than one video stream to be merged into a single file.

--audio-multistreams

Allow more than one audio stream — the usual reason is keeping two language tracks.

--prefer-free-formats

Break ties in favour of VP9/Opus over H.264/AAC at the same quality.

--check-formats

Verify each format is actually downloadable before choosing it. Slow, but ends "the format exists and 403s".

Audio extraction

Getting sound out without the picture. Every one of these needs ffmpeg.

-x, --extract-audio

Discard the video stream and keep the audio.

--audio-format FORMAT

Convert the extracted audio: mp3, m4a, opus, flac, wav, or best to leave it as-is.

--audio-quality QUALITY

0 (best) to 10 (worst) for VBR, or a bitrate like 192K. Ignored when --audio-format is best.

--remux-video FORMAT

Change the container without re-encoding. Instant, lossless, and the right answer far more often than --recode.

--recode-video FORMAT

Re-encode into another format. Slow and lossy — reach for --remux-video first.

--postprocessor-args ARGS

Pass arguments straight through to ffmpeg. The escape hatch when yt-dlp has no flag for what you need.

Subtitles

Real subtitles and machine captions are different things, and the flags for them are too.

--list-subs

Show which subtitle languages exist for this video, and whether they are real or auto-generated.

--write-subs

Download subtitles the uploader actually provided.

--write-auto-subs

Also accept YouTube's machine-generated captions. Without this, --write-subs on most videos silently produces nothing.

--sub-langs LANGS

Which languages: en, en.*, all, or a comma-separated list. Combine with -en to exclude.

--embed-subs

Put the subtitles inside the video file rather than beside it. mkv and mp4 only.

--convert-subs FORMAT

Convert to srt, ass, vtt or lrc. YouTube hands out vtt and plenty of players cannot read it.

--sub-format FORMAT

Preferred subtitle format to download, with the same fallback syntax as -f.

Playlists and channels

Everything that turns one command into a bulk job.

--no-playlist

When the URL is a video inside a playlist, take only the video. Worth setting permanently in your config.

--yes-playlist

The opposite: take the whole playlist even when a single video was named.

-I, --playlist-items ITEMSPEC

A subset: 1-5, 8, 10-, or ::-1 to reverse. Counts positions in the playlist, not video ids.

--download-archive FILE

Record what has been downloaded and skip it next time. The flag that makes a scheduled job safe to re-run.

--max-downloads NUMBER

Stop after N videos. Useful for testing a command against a 900-video channel.

--playlist-random

Download in random order.

--lazy-playlist

Start downloading before the whole playlist has been enumerated.

--flat-playlist

List the entries without resolving each one. Fast way to see what is in a channel.

--break-on-existing

Stop the whole run at the first video already in the archive, rather than skipping past it.

--min-filesize SIZE

Skip anything smaller. --max-filesize is the mirror image.

--dateafter DATE

Only videos uploaded after this date. Accepts now-1month and similar.

--match-filters FILTER

Arbitrary conditions: "duration < 600 & view_count > 1000".

Output and filenames

Where files land and what they are called. The difference between a download folder and a library.

-o, --output TEMPLATE

The filename template. Fields go in %(field)s; directories in the template are created as needed.

-P, --paths TYPE:PATH

Base directory, optionally per file type — temp:/fast/disk keeps partial files off a network share.

--restrict-filenames

ASCII only, no spaces. Prevents most "file not found" problems on Windows and network shares.

--batch-file FILE

Read URLs from a text file, one per line, # for comments.

--windows-filenames

Apply Windows' character restrictions even on Linux and macOS. For files headed to a shared drive.

--trim-filenames LENGTH

Cap the filename length. Long titles plus a deep path hit the filesystem limit surprisingly often.

--output-na-placeholder TEXT

What to write when a template field is empty, instead of the literal NA.

--no-overwrites

Never replace an existing file.

-c, --continue

Resume a partially downloaded file. On by default; --no-continue restarts.

Metadata, thumbnails and chapters

Everything that makes the file recognisable to a media library instead of a filename.

--embed-metadata

Write title, uploader, date and description into the file's tags.

--embed-thumbnail

Attach the thumbnail as cover art. What Plex, Jellyfin and every music player display.

--embed-chapters

Write chapter markers into the file so a player can seek by them.

--write-thumbnail

Save the thumbnail as a separate image file as well.

--write-info-json

Dump everything yt-dlp knows about the video as JSON beside it.

--write-description

Save the video description to a .description file.

--parse-metadata FROM:TO

Copy or rewrite metadata fields with a regex. How you turn "Artist - Track" in a title into real tags.

--split-chapters

Write each chapter out as its own file.

SponsorBlock

Community-marked segments — sponsors, intros, self-promotion — marked or removed at download time.

--sponsorblock-mark CATS

Write the segments in as chapters so you can skip them yourself. Lossless: the file is not re-cut.

--sponsorblock-remove CATS

Cut the segments out of the file. Re-encodes, takes longer, and cannot be undone.

--sponsorblock-chapter-title TEMPLATE

How marked segments are named in the chapter list.

--no-sponsorblock

Disable both, overriding anything set in a config file.

Authentication and cookies

Proving you are allowed to see something — and, increasingly, proving you are a person.

--cookies-from-browser BROWSER

Read cookies straight from an installed browser. Add a profile with a colon: firefox:work.

--cookies FILE

Use a Netscape-format cookies.txt. Survives browser updates; goes stale on its own schedule.

-u, --username / -p, --password

Site login where the site supports it. Rarely what YouTube needs.

--netrc

Read credentials from ~/.netrc instead of the command line, where they would land in your shell history.

--video-password PASSWORD

For password-protected videos — Vimeo's private links, mostly.

--extractor-args KEY:ARGS

Per-extractor settings. youtube:player_client=web_safari and friends live here.

Network, proxies and rate limits

The group you end up in after a 429, and the one that decides whether a big job finishes.

-r, --limit-rate RATE

Cap the download speed: 500K, 2M. The most effective single defence against rate limiting.

--sleep-requests SECONDS

Pause between metadata requests. Playlists trip limits on extraction, before any downloading starts.

--sleep-interval SECONDS

Pause before each download. --max-sleep-interval adds jitter, which looks less mechanical.

-N, --concurrent-fragments N

Download N fragments at once. Faster on fragmented formats; more likely to be throttled.

--proxy URL

Route through a proxy: http://, https://, socks5:// all accepted.

--source-address IP

Bind to a specific local address. For a machine with more than one route out.

-4, --force-ipv4

IPv4 only. Fixes a surprising number of geo and rate-limit oddities.

--geo-bypass

Send a plausible X-Forwarded-For for the target country. Works on some sites, not on YouTube.

-R, --retries N

Retries per download. infinite is accepted.

--file-access-retries N

Retries when the filesystem itself refuses — an antivirus scanner holding the file, usually.

--throttled-rate RATE

Re-extract and restart if the speed drops below this. Recovers from a mid-download throttle.

--downloader NAME

Use an external downloader such as aria2c.

Diagnostics

What to run before asking anyone what went wrong.

-v, --verbose

Full debug output including the version and every extractor decision. Required in any bug report.

--simulate

Do everything except write a file. Confirms a format selector matches before a 4 GB download.

-i, --ignore-errors

Keep going when one video in a playlist fails. --no-abort-on-error is the gentler version.

-U, --update

Update yt-dlp in place. Only works on the standalone binary, not a pip or package-manager install.

--update-to nightly

Switch to the nightly channel, where extractor fixes land days before a release.

-g, --get-url

Print the direct media URL and exit.

-j, --dump-json

Print all extracted metadata as JSON. --dump-single-json for a playlist as one object.

--print TEMPLATE

Print specific fields during the run: --print "%(title)s %(duration)s".

--no-warnings

Silence warnings. Reach for it last — most yt-dlp warnings are telling you something real.

Configuration

Making a setting permanent, and turning it off again when it turns out to be wrong.

--ignore-config

Ignore every config file. The first thing to try when a command behaves differently on your machine.

--config-locations PATH

Load an additional config file, or a directory of them.

--no-config-locations

Drop config paths accumulated so far, keeping later ones.

Frequently asked