Command-Line Options Reference
This comprehensive reference covers all command-line options available in yt-dlp, organized by category for easy navigation.
General Options
Help and Version
-h, --help Print help text and exit
--version Print program version and exit
Updates
-U, --update Update this program to the latest version
--no-update Do not check for updates (default)
--update-to [CHANNEL]@[TAG] Upgrade/downgrade to a specific version
Update Channels: stable, nightly, master
Error Handling
-i, --ignore-errors Ignore download and postprocessing errors
--no-abort-on-error Continue with next video on download errors (default)
--abort-on-error Abort downloading of further videos if an error occurs
Extractor Control
--dump-user-agent Display the current user-agent and exit
--list-extractors List all supported extractors and exit
--extractor-descriptions Output descriptions of all supported extractors and exit
--use-extractors NAMES Extractor names to use separated by commas
--default-search PREFIX Use this prefix for unqualified URLs
Configuration
--ignore-config Don't load any more configuration files
--no-config-locations Do not load any custom configuration files (default)
--config-locations PATH Location of the main configuration file
Network Options
Proxy and Connection
--proxy URL Use the specified HTTP/HTTPS/SOCKS proxy
--socket-timeout SECONDS Time to wait before giving up, in seconds
--source-address IP Client-side IP address to bind to
--impersonate CLIENT[:OS] Client to impersonate for requests
--list-impersonate-targets List available clients to impersonate
-4, --force-ipv4 Make all connections via IPv4
-6, --force-ipv6 Make all connections via IPv6
--enable-file-urls Enable file:// URLs
Geo-restriction
--geo-verification-proxy URL Use this proxy to verify the IP address
--xff VALUE How to fake X-Forwarded-For HTTP header
Video Selection
Playlist Control
-I, --playlist-items ITEM_SPEC Comma separated playlist_index of items to download
--no-playlist Download only the video, if URL refers to video and playlist
--yes-playlist Download the playlist, if URL refers to video and playlist
Size and Date Filters
--min-filesize SIZE Abort download if filesize is smaller than SIZE
--max-filesize SIZE Abort download if filesize is larger than SIZE
--date DATE Download only videos uploaded on this date
--datebefore DATE Download only videos uploaded on or before this date
--dateafter DATE Download only videos uploaded on or after this date
Advanced Filtering
--match-filters FILTER Generic video filter using OUTPUT TEMPLATE fields
--no-match-filters Do not use any --match-filters (default)
--break-match-filters FILTER Same as --match-filters but stops download process when rejected
--age-limit YEARS Download only videos suitable for the given age
Archive and Download Control
--download-archive FILE Download only videos not listed in the archive file
--no-download-archive Do not use archive file (default)
--max-downloads NUMBER Abort after downloading NUMBER files
--break-on-existing Stop download process when encountering archived file
--break-per-input Reset limits per input URL
Download Options
Performance
-N, --concurrent-fragments N Number of fragments to download concurrently (default: 1)
-r, --limit-rate RATE Maximum download rate in bytes per second
--throttled-rate RATE Minimum download rate before re-extraction
Retry Control
-R, --retries RETRIES Number of retries (default: 10), or "infinite"
--file-access-retries RETRIES Number of times to retry on file access error (default: 3)
--fragment-retries RETRIES Number of retries for a fragment (default: 10)
--retry-sleep [TYPE:]EXPR Time to sleep between retries in seconds
Fragment Handling
--skip-unavailable-fragments Skip unavailable fragments (default)
--abort-on-unavailable-fragments Abort download if a fragment is unavailable
--keep-fragments Keep downloaded fragments on disk after downloading
--no-keep-fragments Delete downloaded fragments after downloading (default)
Buffer and Chunking
--buffer-size SIZE Size of download buffer (default: 1024)
--resize-buffer Automatically resize buffer (default)
--no-resize-buffer Do not automatically adjust buffer size
--http-chunk-size SIZE Size of chunk for chunk-based HTTP downloading
External Downloaders
--downloader [PROTO:]NAME Name or path of external downloader to use
--downloader-args NAME:ARGS Give arguments to the external downloader
Filesystem Options
Input and Output
-a, --batch-file FILE File containing URLs to download
--no-batch-file Do not read URLs from batch file (default)
-P, --paths [TYPES:]PATH The paths where files should be downloaded
-o, --output [TYPES:]TEMPLATE Output filename template
--output-na-placeholder TEXT Placeholder for unavailable fields (default: "NA")
Filename Control
--restrict-filenames Restrict filenames to only ASCII characters
--no-restrict-filenames Allow Unicode characters and spaces (default)
--windows-filenames Force filenames to be Windows-compatible
--no-windows-filenames Sanitize filenames only minimally
--trim-filenames LENGTH Limit filename length to specified characters
Overwrite Control
-w, --no-overwrites Do not overwrite any files
--force-overwrites Overwrite all video and metadata files
--no-force-overwrites Do not overwrite video, but overwrite related files (default)
-c, --continue Resume partially downloaded files (default)
--no-continue Do not resume partially downloaded fragments
Metadata Files
--write-description Write video description to .description file
--write-info-json Write video metadata to .info.json file
--write-playlist-metafiles Write playlist metadata (default)
--write-comments Retrieve video comments for infojson
--load-info-json FILE JSON file containing video information
Cookies and Cache
--cookies FILE Netscape formatted file to read cookies from
--no-cookies Do not read/dump cookies (default)
--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER] Load cookies from browser
--cache-dir DIR Location where yt-dlp can store downloaded information
--no-cache-dir Disable filesystem caching
--rm-cache-dir Delete all filesystem cache files
Format Selection
Basic Format Selection
-f, --format FORMAT Video format code
-S, --format-sort SORTORDER Sort formats by specified fields
--format-sort-force Force user specified sort order precedence
--no-format-sort-force Some fields have precedence over user order (default)
Multistream Control
--video-multistreams Allow multiple video streams to be merged
--no-video-multistreams Only one video stream per output file (default)
--audio-multistreams Allow multiple audio streams to be merged
--no-audio-multistreams Only one audio stream per output file (default)
Format Preferences
--prefer-free-formats Prefer video formats with free containers
--no-prefer-free-formats Don't give special preference to free containers (default)
--check-formats Make sure formats are selected only from downloadable ones
--check-all-formats Check all formats for downloadability
-F, --list-formats List available formats of each video
--merge-output-format FORMAT Containers for merging formats
Post-Processing Options
Audio Processing
-x, --extract-audio Convert video files to audio-only files
--audio-format FORMAT Format to convert audio to when -x is used
--audio-quality QUALITY Specify ffmpeg audio quality (0-10 or bitrate)
Video Processing
--remux-video FORMAT Remux video into another container if necessary
--recode-video FORMAT Re-encode video into another format if necessary
--postprocessor-args NAME:ARGS Give arguments to the postprocessors
File Management
-k, --keep-video Keep intermediate video file on disk after post-processing
--no-keep-video Delete intermediate video file after post-processing (default)
--post-overwrites Overwrite post-processed files (default)
--no-post-overwrites Do not overwrite post-processed files
Embedding and Metadata
--embed-subs Embed subtitles in the video
--no-embed-subs Do not embed subtitles (default)
--embed-thumbnail Embed thumbnail in the video as cover art
--no-embed-thumbnail Do not embed thumbnail (default)
--embed-metadata Embed metadata to the video file
--no-embed-metadata Do not add metadata to file (default)
--embed-chapters Add chapter markers to the video file
--no-embed-chapters Do not add chapter markers (default)
Advanced Processing
--parse-metadata [WHEN:]FROM:TO Parse additional metadata from other fields
--replace-in-metadata [WHEN:]FIELDS REGEX REPLACE Replace text in metadata field
--xattrs Write metadata to the video file's xattrs
--concat-playlist POLICY Concatenate videos in a playlist
--fixup POLICY Automatically correct known faults of the file
--ffmpeg-location PATH Location of the ffmpeg binary
--exec [WHEN:]CMD Execute a command after download
--convert-subs FORMAT Convert subtitles to another format
--convert-thumbnails FORMAT Convert thumbnails to another format
--split-chapters Split video into multiple files based on chapters
--remove-chapters REGEX Remove chapters whose title matches regex
--force-keyframes-at-cuts Force keyframes at cuts when downloading/splitting
--use-postprocessor NAME[:ARGS] Enable plugin postprocessors
Verbosity and Simulation
Output Control
-q, --quiet Activate quiet mode
--no-quiet Deactivate quiet mode (default)
--no-warnings Ignore warnings
-s, --simulate Do not download video and do not write anything to disk
--no-simulate Download video even if printing/listing options are used
--skip-download Do not download video but write all related files
Information Output
-O, --print [WHEN:]TEMPLATE Field name or output template to print to screen
--print-to-file [WHEN:]TEMPLATE FILE Append given template to file
-j, --dump-json Print JSON information for each video
-J, --dump-single-json Print JSON information for each URL in a single line
--force-write-archive Force download archive entries to be written
Progress Display
--newline Output progress bar as new lines
--no-progress Do not print progress bar
--progress Show progress bar, even if in quiet mode
--console-title Display progress in console titlebar
--progress-template [TYPES:]TEMPLATE Template for progress outputs
--progress-delta SECONDS Time between progress output (default: 0)
Debug Output
-v, --verbose Print various debugging information
--dump-pages Print downloaded pages encoded using base64
--write-pages Write downloaded intermediary pages to files
--print-traffic Display sent and read HTTP traffic
Authentication Options
Basic Authentication
-u, --username USERNAME Login with this account ID
-p, --password PASSWORD Account password
-2, --twofactor TWOFACTOR Two-factor authentication code
-n, --netrc Use .netrc authentication data
--netrc-location PATH Location of .netrc authentication data
--netrc-cmd NETRC_CMD Command to execute to get credentials
--video-password PASSWORD Video-specific password
Advanced Authentication
--ap-mso MSO Adobe Pass multiple-system operator identifier
--ap-username USERNAME Multiple-system operator account login
--ap-password PASSWORD Multiple-system operator account password
--ap-list-mso List all supported multiple-system operators
--client-certificate CERTFILE Path to client certificate file in PEM format
--client-certificate-key KEYFILE Path to private key file for client certificate
--client-certificate-password PASSWORD Password for client certificate private key
Workarounds
Connection Issues
--encoding ENCODING Force the specified encoding (experimental)
--legacy-server-connect Allow HTTPS connection to servers without RFC 5746
--no-check-certificates Suppress HTTPS certificate validation
--prefer-insecure Use unencrypted connection to retrieve information
--add-headers FIELD:VALUE Specify custom HTTP header and value
Rate Limiting
--sleep-requests SECONDS Number of seconds to sleep between requests
--sleep-interval SECONDS Number of seconds to sleep before each download
--max-sleep-interval SECONDS Maximum number of seconds to sleep
--sleep-subtitles SECONDS Number of seconds to sleep before each subtitle download
Other Workarounds
--bidi-workaround Work around terminals that lack bidirectional text support
Extractor Options
--extractor-retries RETRIES Number of retries for known extractor errors (default: 3)
--allow-dynamic-mpd Process dynamic DASH manifests (default)
--ignore-dynamic-mpd Do not process dynamic DASH manifests
--hls-split-discontinuity Split HLS playlists at discontinuities
--no-hls-split-discontinuity Do not split HLS playlists at discontinuities (default)
--extractor-args IE_KEY:ARGS Pass ARGS arguments to the IE_KEY extractor