yt-dlp Cheat-sheet

yt-dlp, command-line, youtube

A practical yt-dlp cheat sheet based on the official yt-dlp README Usage and Options section (syntax, option names, and behavior). The CLI syntax is yt-dlp [OPTIONS] [--] URL [URL...].

Core command shape

yt-dlp [OPTIONS] URL
yt-dlp [OPTIONS] URL1 URL2 URL3
  • -- separates options from URLs if needed.

Most useful “daily use” commands

1) Download best default

yt-dlp "URL"

2) List formats first (inspect before choosing)

yt-dlp -F "URL"
  • -F, --list-formats lists available formats.

3) Pick a specific format / format selector

yt-dlp -f "FORMAT" "URL"
  • -f, --format FORMAT chooses format selector expression.

4) Save with custom filename

yt-dlp -o "%(title)s [%(id)s].%(ext)s" "URL"
  • -o, --output [TYPES:]TEMPLATE sets output template.

5) Extract audio (mp3, m4a, opus, etc.)

yt-dlp -x --audio-format mp3 "URL"
  • -x converts to audio-only (requires ffmpeg and ffprobe).

6) Download subtitles

yt-dlp --write-subs --sub-langs "en.*" "URL"
  • --write-subs, --sub-langs, --list-subs, and --write-auto-subs are supported.

7) Print metadata / inspect without download

yt-dlp -O "%(title)s | %(uploader)s | %(duration)s" "URL"
yt-dlp -j "URL"
  • -O/--print prints fields/templates and implies quiet/simulate in many cases. -j dumps JSON.

High-value options by category

General

yt-dlp -h
yt-dlp --version
yt-dlp -U
yt-dlp -i "URL"
  • -h, --help help text
  • --version version
  • -U, --update update
  • -i, --ignore-errors keep going on download/postprocessing errors

Playlist control

yt-dlp -I "1,3,5-10" "PLAYLIST_URL"
  • -I, --playlist-items ITEM_SPEC supports comma-separated indices and ranges ([START]:[STOP][:STEP], negative indices too).

Output & paths (very handy)

yt-dlp -P "/downloads" -o "%(uploader)s/%(title)s.%(ext)s" "URL"
yt-dlp -P "temp:/tmp/yt" -P "subtitle:subs" --write-subs "URL"
  • -P, --paths [TYPES:]PATH sets download paths (supports home, temp, and type-specific paths like subtitles).
  • -o supports type-specific templates like subtitle:....

Default filename template (if you do nothing):

  • %(title)s [%(id)s].%(ext)s

Format selection & sorting (important)

yt-dlp -F "URL"
yt-dlp -f "bestvideo+bestaudio/best" "URL"
yt-dlp -S "res,fps,codec" "URL"
  • -f chooses format selector expression.
  • -S, --format-sort sorts candidate formats before selecting.
  • yt-dlp notes that worst is often not what people actually want; size-based sorting can be better in many cases.

Download performance / reliability

yt-dlp -N 4 -R infinite --fragment-retries infinite "URL"
yt-dlp -r 2M "URL"
  • -N, --concurrent-fragments N parallel fragment downloads (HLS/DASH/native fragments)
  • -r, --limit-rate RATE
  • -R, --retries RETRIES
  • --fragment-retries RETRIES

Simulation / dry-run / debugging

yt-dlp -s "URL"
yt-dlp -q "URL"
yt-dlp --no-warnings "URL"
  • -s, --simulate no download / no writes
  • -q, --quiet
  • --no-warnings

Cookies / auth (common for restricted content)

yt-dlp --cookies cookies.txt "URL"
yt-dlp --cookies-from-browser firefox "URL"
yt-dlp --cookies-from-browser chrome "URL"
  • --cookies FILE uses Netscape cookie file
  • --cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER] supports browsers like Chrome/Firefox/Edge/etc., with Linux keyring options for Chromium cookie decryption.

Network / proxy / region-related

yt-dlp --proxy "socks5://127.0.0.1:1080" "URL"
yt-dlp --geo-verification-proxy "http://..." "URL"
  • --proxy URL supports HTTP/HTTPS/SOCKS; empty string disables proxy (--proxy "").
  • --geo-verification-proxy URL is separate for geo-checking on some sites.
  • --xff VALUE can fake X-Forwarded-For in supported scenarios.

Subtitles

yt-dlp --list-subs "URL"
yt-dlp --write-subs --sub-langs "en,es" "URL"
yt-dlp --write-auto-subs --sub-langs "en.*" "URL"
yt-dlp --sub-format "srt/best" --write-subs "URL"
  • --write-subs, --write-auto-subs, --list-subs, --sub-format, --sub-langs are all in the Video Format/Subtitles options area.

Audio extraction / conversion

yt-dlp -x --audio-format m4a "URL"
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"
  • -x extracts audio and converts via ffmpeg/ffprobe.
  • --audio-format supports best, aac, alac, flac, m4a, mp3, opus, vorbis, wav.

Metadata / thumbnails / embedding

yt-dlp --write-thumbnail "URL"
yt-dlp --embed-thumbnail "URL"
yt-dlp --embed-metadata --embed-chapters "URL"
  • --embed-thumbnail embeds cover art
  • --embed-metadata embeds metadata (and chapters/infojson unless disabled)
  • --embed-chapters, --embed-info-json available too

Partial download / chapters / sections

yt-dlp --download-sections "*00:30-01:45" "URL"
yt-dlp --download-sections "intro" "URL"
  • --download-sections REGEX can match chapter names or use * time-ranges (ffmpeg needed). Supports multiple uses.

Batch mode (multiple URLs from file)

yt-dlp -a urls.txt
cat urls.txt | yt-dlp -a -
  • -a, --batch-file FILE reads URLs (supports - for stdin; comment lines are ignored).

Output template mini-reference (the one you actually need)

-o "%(title)s.%(ext)s"
-o "%(uploader)s/%(title)s [%(id)s].%(ext)s"
-o "%(upload_date>%Y)s/%(title)s.%(ext)s"
-o -

What these do:

  • %(field)s inserts metadata field
  • %(upload_date>%Y)s applies date formatting to a field
  • -o - outputs media to stdout
  • % literal becomes %% in templates
  • hierarchical paths are allowed and directories are auto-created
yt-dlp -j "URL" > info.json
yt-dlp -F "URL"
yt-dlp -O "%(title)s [%(id)s].%(ext)s" "URL"

Why:

  • -j shows available metadata keys
  • -F shows formats
  • -O tests output template before downloading

Config file tip (for recurring defaults)

yt-dlp supports configuration files and options like --ignore-config, --config-locations, and documents standard config locations in the README’s configuration section.

Example idea (not exact file path recommendation here):

  • Put your common defaults (-x, --proxy, -o, etc.) into a config file so you don’t retype them. The README includes an example config snippet.

Copy/paste starter presets

Clean video download with readable filenames

yt-dlp --restrict-filenames -o "%(uploader)s/%(title)s [%(id)s].%(ext)s" "URL"
  • --restrict-filenames helps avoid problematic characters; README explicitly notes this use case.

Best audio + embedded metadata + thumbnail

yt-dlp -x --audio-format m4a --embed-metadata --embed-thumbnail "URL"
  • Uses audio extraction and metadata/thumbnail embedding options from the official usage docs.

Use thumbnail as a separate file (skip embedding)

yt-dlp -x --audio-format m4a --embed-metadata --write-thumbnail "URL"
  • Writes thumbnail as a separate file (sometimes --embed-thumbnail fails)

Playlist subset only

yt-dlp -I "1:10" "PLAYLIST_URL"
  • Downloads only a slice of playlist items.