Skip to main content

Command Line Options Reference

This comprehensive reference covers all available command line options in yt-dlp, organized by category for easy navigation.

General Options​

Help and Information​

Print help text and exit

-h

or

--help

Print program version and exit

--version

List all supported extractors and exit

--list-extractors

Output descriptions of all supported extractors

--extractor-descriptions

Display the current user-agent and exit

--dump-user-agent

Updates​

Update to latest version

-U

or

--update

Do not check for updates (default)

--no-update

Upgrade/downgrade to specific version CHANNEL: stable, nightly, master Example: --update-to nightly

--update-to [CHANNEL]@[TAG]

Error Handling​

Ignore download and postprocessing errors

-i

or

--ignore-errors

Continue with next video on download errors (default)

--no-abort-on-error

Abort downloading if error occurs

--abort-on-error

Extractors​

Extractors to use (comma-separated) Example: --use-extractors youtube,twitter

--use-extractors NAMES

Prefix for unqualified URLs Example: --default-search "ytsearch:"

--default-search PREFIX

Configuration​

Do not load configuration files

--ignore-config

Do not load custom configuration files

--no-config-locations

Location of configuration file

--config-locations PATH

Additional plugin directories

--plugin-dirs PATH

Clear plugin directories

--no-plugin-dirs

Playlist Options​

Do not extract playlist entries

--flat-playlist

Fully extract playlist videos (default)

--no-flat-playlist

Download livestreams from start

--live-from-start

Download livestreams from current time (default)

--no-live-from-start

Wait for scheduled streams

--wait-for-video MIN[-MAX]

Do not wait for scheduled streams (default)

--no-wait-for-video

Mark videos watched

--mark-watched

Do not mark videos watched (default)

--no-mark-watched

Appearance​

Color output policy Options: always, auto, never, no_color

--color [STREAM:]POLICY

Compatibility​

Compatibility options for youtube-dl

--compat-options OPTS

Create custom aliases

--alias ALIASES OPTIONS

Apply predefined aliases Presets: mp3, aac, mp4, mkv, sleep

-t

or

--preset-alias PRESET

Network Options​

Proxy and Connection​

Use specified HTTP/HTTPS/SOCKS proxy

--proxy URL

Time to wait before giving up

--socket-timeout SECONDS

Client-side IP address to bind to

--source-address IP

Client to impersonate for requests

--impersonate CLIENT[:OS]

List available impersonation targets

--list-impersonate-targets

Make all connections via IPv4

-4

or

 --force-ipv4

Make all connections via IPv6

-6

or

--force-ipv6

Enable file:// URLs

--enable-file-urls

Geo-restriction​

Proxy to verify IP for geo-restricted sites

--geo-verification-proxy URL

How to fake X-Forwarded-For HTTP header Options: default, never, IP_BLOCK, COUNTRY_CODE

--xff VALUE

Video Selection​

Playlist and Item Selection​

Comma separated playlist items to download Example: -I 1:3,7,-5::2

-I

or

--playlist-items ITEM_SPEC

Abort if filesize smaller than SIZE

--min-filesize SIZE

Abort if filesize larger than SIZE

--max-filesize SIZE

Download only videos uploaded on date

--date DATE

Download videos uploaded before date

--datebefore DATE

Download videos uploaded after date

--dateafter DATE

Filtering​

Generic video filter Example: --match-filters "like_count>100"

--match-filters FILTER

Do not use any match filters

--no-match-filters

Same as match-filters but stops download

--break-match-filters FILTER

Do not use break-match-filters

--no-break-match-filters

Playlist Behavior​

Download only the video, not playlist

--no-playlist

Download the playlist if URL refers to both

--yes-playlist

Download only videos suitable for age

--age-limit YEARS

Download only videos not listed in archive

--download-archive FILE

Do not use archive file

--no-download-archive

Abort after downloading NUMBER files

--max-downloads NUMBER

Stop when encountering file in archive

--break-on-existing

Reset break conditions per input URL

--break-per-input

Skip playlist after N failures

--skip-playlist-after-errors N

Download Options​

Performance and Concurrency​

Number of fragments to download concurrently

-N

or

--concurrent-fragments N

Maximum download rate (e.g., 50K, 4.2M)

-r

or

--limit-rate RATE

Minimum rate below which re-extract data

--throttled-rate RATE

Number of retries (default: 10, or "infinite")

-R

or

--retries RETRIES

Retries for file access errors

--file-access-retries RETRIES

Retries for fragments

--fragment-retries RETRIES

Sleep time between retries

--retry-sleep [TYPE:]EXPR

Fragment Handling​

Skip unavailable fragments (default)

--skip-unavailable-fragments

Abort if fragment unavailable

--abort-on-unavailable-fragments

Keep downloaded fragments on disk

--keep-fragments

Delete fragments after download (default)

--no-keep-fragments

HLS Options​

Use mpegts container for HLS videos

--hls-use-mpegts

Do not use mpegts container

--no-hls-use-mpegts

Download Behavior​

Download buffer size (default: 1024)

--buffer-size SIZE

Auto-resize buffer (default)

--resize-buffer

Do not auto-resize buffer

--no-resize-buffer

Chunk size for HTTP downloading

--http-chunk-size SIZE

Download playlist in random order

--playlist-random

Process playlist entries as received

--lazy-playlist

Process entire playlist first (default)

--no-lazy-playlist

Set file xattribute with expected size

--xattr-set-filesize

Sections and Chapters​

Download only matching chapters/time-ranges Example: --download-sections "*10:15-inf"

--download-sections REGEX

External Downloaders​

External downloader to use Example: --downloader aria2c

--downloader [PROTO:]NAME

Arguments for external downloader

--downloader-args NAME:ARGS

Filesystem Options​

Input and Output Paths​

File containing URLs to download

-a

or

 --batch-file FILE

Do not read URLs from batch file

--no-batch-file

Internet Shortcut Options​

Write internet shortcut file

--write-link

Write .url Windows shortcut

--write-url-link

Write .webloc macOS shortcut

--write-webloc-link

Write .desktop Linux shortcut

--write-desktop-link

Download paths for different file types

-P

or

--paths [TYPES:]PATH

Output filename template

-o

or

 --output [TYPES:]TEMPLATE

Placeholder for unavailable fields

--output-na-placeholder TEXT

Filename Handling​

Restrict to ASCII characters only

--restrict-filenames

Allow Unicode and special characters

--no-restrict-filenames

Force Windows-compatible filenames

--windows-filenames

Minimal filename sanitization

--no-windows-filenames

Limit filename length

--trim-filenames LENGTH

File Overwrite Behavior​

Do not overwrite any files

-w

or

--no-overwrites

Overwrite all files

--force-overwrites

Do not overwrite video files (default)

--no-force-overwrites

Resume partially downloaded files (default)

-c

or

--continue

Restart download entirely

--no-continue

Use .part files (default)

--part

Write directly to output file

--no-part

Use Last-modified header for file time

--mtime

Do not use Last-modified header

--no-mtime

Metadata Files​

Write video description to file

--write-description

Do not write description (default)

--no-write-description

Write video metadata to JSON file

--write-info-json

Do not write metadata (default)

--no-write-info-json

Write playlist metadata (default)

--write-playlist-metafiles

Do not write playlist metadata

--no-write-playlist-metafiles

Remove internal metadata from infojson (default)

--clean-info-json

Write all fields to infojson

--no-clean-info-json

Retrieve video comments

--write-comments

Do not retrieve comments

--no-write-comments

Load video info from JSON file

--load-info-json FILE

Cookies and Cache​

Read/write cookies from/to file

--cookies FILE

Do not read/dump cookies (default)

--no-cookies

Load cookies from browser

--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]

Do not load cookies from browser (default)

--no-cookies-from-browser

Filesystem cache directory

--cache-dir DIR

Disable filesystem caching

--no-cache-dir

Delete all cache files

--rm-cache-dir

Format Selection​

Basic Format Selection​

Video format code Examples: -f best, -f "best[height<=720]"

-f

or

--format FORMAT

Sort formats by specified fields

-S

or

--format-sort SORTORDER

Force user-specified sort order

--format-sort-force

Allow some fields to override sort order

--no-format-sort-force

List available formats

-F

or

 --list-formats

Multi-stream Options​

Allow multiple video streams

--video-multistreams

Only one video stream (default)

--no-video-multistreams

Allow multiple audio streams

--audio-multistreams

Only one audio stream (default)

--no-audio-multistreams

Format Preferences​

Prefer free containers over non-free

--prefer-free-formats

No special preference for free formats

--no-prefer-free-formats

Check if formats are downloadable

--check-formats

Check all formats for downloadability

--check-all-formats

Do not check format availability

--no-check-formats

Container for merging formats

--merge-output-format FORMAT

Subtitle Options​

Write subtitle file

--write-subs

Do not write subtitles (default)

--no-write-subs

Write automatically generated subtitles

--write-auto-subs

Do not write auto-generated subtitles

--no-write-auto-subs

List available subtitles

--list-subs

Subtitle format preference

--sub-format FORMAT

Languages of subtitles to download

--sub-langs LANGS

Thumbnail Options​

Write thumbnail image to disk

--write-thumbnail

Do not write thumbnail (default)

--no-write-thumbnail

Write all thumbnail formats

--write-all-thumbnails

List available thumbnails

--list-thumbnails

Authentication Options​

Login with account ID

-u

or

 --username USERNAME

Account password

-p

or

 --password PASSWORD

Two-factor authentication code

-2

or

--twofactor TWOFACTOR

Use .netrc authentication data

-n

or

 --netrc

Location of .netrc file

--netrc-location PATH

Command to get credentials

--netrc-cmd NETRC_CMD

Video-specific password

--video-password PASSWORD

Adobe Pass Options​

Adobe Pass MSO identifier

--ap-mso MSO

MSO account login

--ap-username USERNAME

MSO account password

--ap-password PASSWORD

List supported MSOs

--ap-list-mso

Client Certificate Options​

Path to client certificate

--client-certificate CERTFILE

Path to private key

--client-certificate-key KEYFILE

Private key password

--client-certificate-password PASSWORD

Post-Processing Options​

Audio Extraction​

Convert video files to audio-only

-x

or

--extract-audio

Audio format for conversion Formats: best, aac, alac, flac, m4a, mp3, opus, vorbis, wav

--audio-format FORMAT

Audio quality (0-10 or bitrate like 128K)

--audio-quality QUALITY

Video Processing​

Remux video to different container

--remux-video FORMAT

Re-encode video to different format

--recode-video FORMAT

Arguments for postprocessors

--postprocessor-args NAME:ARGS

Keep intermediate video file

-k

or

--keep-video

Delete intermediate video file (default)

--no-keep-video

Overwrite post-processed files (default)

--post-overwrites

Do not overwrite post-processed files

--no-post-overwrites

Embedding Options​

Embed subtitles in video

--embed-subs

Do not embed subtitles (default)

--no-embed-subs

Embed thumbnail as cover art

--embed-thumbnail

Do not embed thumbnail (default)

--no-embed-thumbnail

Embed metadata in video file

--embed-metadata

Do not embed metadata (default)

--no-embed-metadata

Add chapter markers

--embed-chapters

Do not add chapter markers (default)

--no-embed-chapters

Embed infojson as attachment

--embed-info-json

Do not embed infojson

--no-embed-info-json

Metadata Modification​

Parse additional metadata

--parse-metadata [WHEN:]FROM:TO

Replace metadata text

--replace-in-metadata [WHEN:]FIELDS REGEX REPLACE

Write metadata to xattrs

--xattrs

Advanced Processing​

Concatenate playlist videos Options: never, always, multi_video

--concat-playlist POLICY

Automatically correct file faults Options: never, warn, detect_or_warn, force

--fixup POLICY

Location of ffmpeg binary

--ffmpeg-location PATH

Execute command after processing

--exec [WHEN:]CMD

Remove previously defined exec commands

--no-exec

Enable plugin postprocessors

--use-postprocessor NAME[:ARGS]

Format Conversion​

Convert subtitles to format Formats: ass, lrc, srt, vtt

--convert-subs FORMAT

Convert thumbnails to format Formats: jpg, png, webp

--convert-thumbnails FORMAT

Split video by chapters

--split-chapters

Do not split by chapters (default)

--no-split-chapters

Remove chapters matching regex

--remove-chapters REGEX

Do not remove chapters (default)

--no-remove-chapters

Force keyframes when cutting

--force-keyframes-at-cuts

Do not force keyframes (default)

--no-force-keyframes-at-cuts

SponsorBlock Options​

Create chapters for SponsorBlock categories

--sponsorblock-mark CATS

Remove SponsorBlock categories from video

--sponsorblock-remove CATS

Title template for SponsorBlock chapters

--sponsorblock-chapter-title TEMPLATE

Disable SponsorBlock

--no-sponsorblock

SponsorBlock API location

--sponsorblock-api URL

Available Categories: sponsor, intro, outro, selfpromo, preview, filler, interaction, music_offtopic, poi_highlight, chapter, all, default

Verbosity and Simulation Options​

Output Control​

Activate quiet mode

-q

or

--quiet

Deactivate quiet mode (default)

--no-quiet

Ignore warnings

--no-warnings

Do not download, simulate only

-s

or

--simulate

Download even with print options

--no-simulate

Ignore "No video formats" error

--ignore-no-formats-error

Throw error when no formats (default)

--no-ignore-no-formats-error

Do not download but write related files

--skip-download

Information Output​

Print field/template to screen

-O

or

--print [WHEN:]TEMPLATE

Print template to file

--print-to-file [WHEN:]TEMPLATE FILE

Print JSON information for each video

-j

or

 --dump-json

Print JSON for entire playlist in single line

-J

or

 --dump-single-json

Force write archive entries

--force-write-archive

Progress Display​

Output progress as new lines

--newline

Do not print progress bar

--no-progress

Show progress bar in quiet mode

--progress

Display progress in console title

--console-title

Template for progress output

--progress-template [TYPES:]TEMPLATE

Time between progress outputs

--progress-delta SECONDS

Debug Options​

Print debugging information

-v

or

 --verbose

Print downloaded pages (base64 encoded)

--dump-pages

Write intermediary pages to files

--write-pages

Display HTTP traffic

--print-traffic

Workaround Options​

Network Workarounds​

Force specified encoding

--encoding ENCODING

Allow connections to legacy servers

--legacy-server-connect

Suppress HTTPS certificate validation

--no-check-certificates

Use HTTP instead of HTTPS when possible

--prefer-insecure

Add custom HTTP headers

--add-headers FIELD:VALUE

System Workarounds​

Work around bidirectional text issues

--bidi-workaround

Sleep between requests during extraction

--sleep-requests SECONDS

Sleep before each download

--sleep-interval SECONDS

Maximum sleep time

--max-sleep-interval SECONDS

Sleep before each subtitle download

--sleep-subtitles SECONDS

Extractor Options​

Retries for known extractor errors

--extractor-retries RETRIES

Process dynamic DASH manifests (default)

--allow-dynamic-mpd

Do not process dynamic DASH manifests

--ignore-dynamic-mpd

Split HLS at discontinuities

--hls-split-discontinuity

Do not split HLS (default)

--no-hls-split-discontinuity

Pass arguments to extractors

--extractor-args IE_KEY:ARGS

Preset Aliases​

Pre-configured option combinations for common use cases: Download best audio and convert to MP3

-t mp3

Download best audio and convert to AAC

-t aac

Download best video in MP4 container

-t mp4

Download best video in MKV container

-t mkv

Enable various sleep options

-t sleep

Preset Details​

mp3: -f "ba[acodec^=mp3]/ba/b" -x --audio-format mp3

aac: -f "ba[acodec^=aac]/ba[acodec^=mp4a.40.]/ba/b" -x --audio-format aac

mp4: --merge-output-format mp4 --remux-video mp4 -S vcodec:h264,lang,quality,res,fps,hdr:12,acodec:aac

mkv: --merge-output-format mkv --remux-video mkv

sleep: --sleep-subtitles 5 --sleep-requests 0.75 --sleep-interval 10 --max-sleep-interval 20

Practical Examples​

Basic Usage​

Download best quality

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

Download specific format

yt-dlp -f "best[height<=720]" URL

Download audio only as MP3

yt-dlp -x --audio-format mp3 URL

Download with custom output template

yt-dlp -o "%(uploader)s/%(title)s.%(ext)s" URL

Advanced Usage​

Download playlist with custom naming and archive

yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" \
       --download-archive archive.txt PLAYLIST_URL

Download with SponsorBlock integration and metadata

yt-dlp --sponsorblock-remove sponsor,intro,outro \
       --embed-metadata --embed-thumbnail URL

Download with specific quality and format preferences

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" \
       --merge-output-format mp4 URL

Download with proxy and rate limiting

yt-dlp --proxy socks5://127.0.0.1:1080 \
       --limit-rate 1M URL

Filtering Examples​

Download only videos longer than 5 minutes

yt-dlp --match-filters "duration > 300" PLAYLIST_URL

Download videos with more than 1000 views

yt-dlp --match-filters "view_count > 1000" URL

Download videos uploaded in the last week

yt-dlp --dateafter "today-1week" CHANNEL_URL

This reference covers the most commonly used options. For the complete list of options, run yt-dlp --help or visit the official documentation.