* **Output template improvements**: Output templates can now have date-time formatting, numeric offsets, object traversal etc. See [output template](#output-template) for details. Even more advanced operations can also be done with the help of `--parse-metadata` and `--replace-in-metadata`
-* **Other new options**: Many new options have been added such as `--concat-playlist`, `--print`, `--wait-for-video`, `--sleep-requests`, `--convert-thumbnails`, `--write-link`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
+* **Other new options**: Many new options have been added such as `--alias`, `--print`, `--concat-playlist`, `--wait-for-video`, `--retry-sleep`, `--sleep-requests`, `--convert-thumbnails`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
* **Improvements**: Regex and other operators in `--format`/`--match-filter`, multiple `--postprocessor-args` and `--downloader-args`, faster archive checking, more [format selection options](#format-selection), merge multi-video/audio, multiple `--config-locations`, `--exec` at different stages, etc
* Thumbnail embedding in `mp4` is done with mutagen if possible. Use `--compat-options embed-thumbnail-atomicparsley` to force the use of AtomicParsley instead
* Some private fields such as filenames are removed by default from the infojson. Use `--no-clean-infojson` or `--compat-options no-clean-infojson` to revert this
* When `--embed-subs` and `--write-subs` are used together, the subtitles are written to disk and also embedded in the media file. You can use just `--embed-subs` to embed the subs and automatically delete the separate file. See [#630 (comment)](https://github.com/yt-dlp/yt-dlp/issues/630#issuecomment-893659460) for more info. `--compat-options no-keep-subs` can be used to revert this
-* `certifi` will be used for SSL root certificates, if installed. If you want to use system certificates (e.g. self-signed), use `--compat-options no-certifi`
+* `certifi` will be used for SSL root certificates, if installed. If you want to use only system certificates, use `--compat-options no-certifi`
* youtube-dl tries to remove some superfluous punctuations from filenames. While this can sometimes be helpfull, it is often undesirable. So yt-dlp tries to keep the fields in the filenames as close to their original values as possible. You can use `--compat-options filename-sanitization` to revert to youtube-dl's behavior
For ease of use, a few more compat options are available:
-* `--compat-options all`: Use all compat options
+* `--compat-options all`: Use all compat options (Do NOT use)
* `--compat-options youtube-dl`: Same as `--compat-options all,-multistreams`
* `--compat-options youtube-dlc`: Same as `--compat-options all,-no-live-chat,-no-youtube-channel-redirect`
<!-- Auto generated -->
## General Options:
- -h, --help Print this help text and exit
- --version Print program version and exit
- -U, --update Update this program to latest version
- -i, --ignore-errors Ignore download and postprocessing errors.
- The download will be considered successful
- even if the postprocessing fails
- --no-abort-on-error Continue with next video on download
- errors; e.g. to skip unavailable videos in
- a playlist (default)
- --abort-on-error Abort downloading of further videos if an
- error occurs (Alias: --no-ignore-errors)
- --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
- --force-generic-extractor Force extraction to use the generic
- extractor
- --default-search PREFIX Use this prefix for unqualified URLs. For
- example "gvsearch2:" downloads two videos
- from google videos for the search term
- "large apple". Use the value "auto" to let
- yt-dlp guess ("auto_warning" to emit a
- warning when guessing). "error" just throws
- an error. The default value "fixup_error"
- repairs broken URLs, but emits an error if
- this is not possible instead of searching
- --ignore-config Don't load any more configuration files
- except those given by --config-locations.
- For backward compatibility, if this option
- is found inside the system configuration
- file, the user configuration is not loaded.
- (Alias: --no-config)
- --no-config-locations Do not load any custom configuration files
- (default). When given inside a
- configuration file, ignore all previous
- --config-locations defined in the current
- file
- --config-locations PATH Location of the main configuration file;
- either the path to the config or its
- containing directory. Can be used multiple
- times and inside other configuration files
- --flat-playlist Do not extract the videos of a playlist,
- only list them
- --no-flat-playlist Extract the videos of a playlist
- --live-from-start Download livestreams from the start.
- Currently only supported for YouTube
- (Experimental)
- --no-live-from-start Download livestreams from the current time
- (default)
- --wait-for-video MIN[-MAX] Wait for scheduled streams to become
- available. Pass the minimum number of
- seconds (or range) to wait between retries
- --no-wait-for-video Do not wait for scheduled streams (default)
- --mark-watched Mark videos watched (even with --simulate)
- --no-mark-watched Do not mark videos watched (default)
- --no-colors Do not emit color codes in output
- --compat-options OPTS Options that can help keep compatibility
- with youtube-dl or youtube-dlc
- configurations by reverting some of the
- changes made in yt-dlp. See "Differences in
- default behavior" for details
- --alias ALIASES OPTIONS Create aliases for an option string. Unless
- an alias starts with a dash "-", it is
- prefixed with "--". Arguments are parsed
- according to the Python string formatting
- mini-language. Eg: --alias get-audio,-X
- "-S=aext:{0},abr -x --audio-format {0}"
- creates options "--get-audio" and "-X" that
- takes an argument (ARG0) and expands to
- "-S=aext:ARG0,abr -x --audio-format ARG0".
- All defined aliases are listed in the
- --help output. Alias options can trigger
- more aliases; so be carefull to avoid
- defining recursive options. As a safety
- measure, each alias may be triggered a
- maximum of 100 times. This option can be
- used multiple times
+ -h, --help Print this help text and exit
+ --version Print program version and exit
+ -U, --update Update this program to latest version
+ -i, --ignore-errors Ignore download and postprocessing errors.
+ The download will be considered successful
+ even if the postprocessing fails
+ --no-abort-on-error Continue with next video on download errors;
+ e.g. to skip unavailable videos in a
+ playlist (default)
+ --abort-on-error Abort downloading of further videos if an
+ error occurs (Alias: --no-ignore-errors)
+ --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
+ --force-generic-extractor Force extraction to use the generic
+ extractor
+ --default-search PREFIX Use this prefix for unqualified URLs. Eg:
+ "gvsearch2:python" downloads two videos from
+ google videos for the search term "python".
+ Use the value "auto" to let yt-dlp guess
+ ("auto_warning" to emit a warning when
+ guessing). "error" just throws an error. The
+ default value "fixup_error" repairs broken
+ URLs, but emits an error if this is not
+ possible instead of searching
+ --ignore-config Don't load any more configuration files
+ except those given by --config-locations.
+ For backward compatibility, if this option
+ is found inside the system configuration
+ file, the user configuration is not loaded.
+ (Alias: --no-config)
+ --no-config-locations Do not load any custom configuration files
+ (default). When given inside a configuration
+ file, ignore all previous --config-locations
+ defined in the current file
+ --config-locations PATH Location of the main configuration file;
+ either the path to the config or its
+ containing directory ("-" for stdin). Can be
+ used multiple times and inside other
+ configuration files
+ --flat-playlist Do not extract the videos of a playlist,
+ only list them
+ --no-flat-playlist Extract the videos of a playlist
+ --live-from-start Download livestreams from the start.
+ Currently only supported for YouTube
+ (Experimental)
+ --no-live-from-start Download livestreams from the current time
+ (default)
+ --wait-for-video MIN[-MAX] Wait for scheduled streams to become
+ available. Pass the minimum number of
+ seconds (or range) to wait between retries
+ --no-wait-for-video Do not wait for scheduled streams (default)
+ --mark-watched Mark videos watched (even with --simulate)
+ --no-mark-watched Do not mark videos watched (default)
+ --no-colors Do not emit color codes in output
+ --compat-options OPTS Options that can help keep compatibility
+ with youtube-dl or youtube-dlc
+ configurations by reverting some of the
+ changes made in yt-dlp. See "Differences in
+ default behavior" for details
+ --alias ALIASES OPTIONS Create aliases for an option string. Unless
+ an alias starts with a dash "-", it is
+ prefixed with "--". Arguments are parsed
+ according to the Python string formatting
+ mini-language. Eg: --alias get-audio,-X
+ "-S=aext:{0},abr -x --audio-format {0}"
+ creates options "--get-audio" and "-X" that
+ takes an argument (ARG0) and expands to
+ "-S=aext:ARG0,abr -x --audio-format ARG0".
+ All defined aliases are listed in the --help
+ output. Alias options can trigger more
+ aliases; so be carefull to avoid defining
+ recursive options. As a safety measure, each
+ alias may be triggered a maximum of 100
+ times. This option can be used multiple
+ times
## Network Options:
- --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
- To enable SOCKS proxy, specify a proper
- scheme. For example
- socks5://user:pass@127.0.0.1:1080/. Pass in
- an empty string (--proxy "") for direct
- connection
- --socket-timeout SECONDS Time to wait before giving up, in seconds
- --source-address IP Client-side IP address to bind to
- -4, --force-ipv4 Make all connections via IPv4
- -6, --force-ipv6 Make all connections via IPv6
+ --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy. To
+ enable SOCKS proxy, specify a proper scheme.
+ Eg: socks5://user:pass@127.0.0.1:1080/. Pass
+ in an empty string (--proxy "") for direct
+ connection
+ --socket-timeout SECONDS Time to wait before giving up, in seconds
+ --source-address IP Client-side IP address to bind to
+ -4, --force-ipv4 Make all connections via IPv4
+ -6, --force-ipv6 Make all connections via IPv6
## Geo-restriction:
- --geo-verification-proxy URL Use this proxy to verify the IP address for
- some geo-restricted sites. The default
- proxy specified by --proxy (or none, if the
- option is not present) is used for the
- actual downloading
- --geo-bypass Bypass geographic restriction via faking
- X-Forwarded-For HTTP header (default)
- --no-geo-bypass Do not bypass geographic restriction via
- faking X-Forwarded-For HTTP header
- --geo-bypass-country CODE Force bypass geographic restriction with
- explicitly provided two-letter ISO 3166-2
- country code
- --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
- explicitly provided IP block in CIDR
- notation
+ --geo-verification-proxy URL Use this proxy to verify the IP address for
+ some geo-restricted sites. The default proxy
+ specified by --proxy (or none, if the option
+ is not present) is used for the actual
+ downloading
+ --geo-bypass Bypass geographic restriction via faking
+ X-Forwarded-For HTTP header (default)
+ --no-geo-bypass Do not bypass geographic restriction via
+ faking X-Forwarded-For HTTP header
+ --geo-bypass-country CODE Force bypass geographic restriction with
+ explicitly provided two-letter ISO 3166-2
+ country code
+ --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
+ explicitly provided IP block in CIDR
+ notation
## Video Selection:
- --playlist-start NUMBER Playlist video to start at (default is 1)
- --playlist-end NUMBER Playlist video to end at (default is last)
- --playlist-items ITEM_SPEC Playlist video items to download. Specify
- indices of the videos in the playlist
- separated by commas like: "--playlist-items
- 1,2,5,8" if you want to download videos
- indexed 1, 2, 5, 8 in the playlist. You can
- specify range: "--playlist-items
- 1-3,7,10-13", it will download the videos
- at index 1, 2, 3, 7, 10, 11, 12 and 13
- --min-filesize SIZE Do not download any videos smaller than
- SIZE (e.g. 50k or 44.6m)
- --max-filesize SIZE Do not download any videos larger than SIZE
- (e.g. 50k or 44.6m)
- --date DATE Download only videos uploaded on this date.
- The date can be "YYYYMMDD" or in the format
- [now|today|yesterday][-N[day|week|month|year]].
- Eg: --date today-2weeks
- --datebefore DATE Download only videos uploaded on or before
- this date. The date formats accepted is the
- same as --date
- --dateafter DATE Download only videos uploaded on or after
- this date. The date formats accepted is the
- same as --date
- --match-filters FILTER Generic video filter. Any field (see
- "OUTPUT TEMPLATE") can be compared with a
- number or a string using the operators
- defined in "Filtering formats". You can
- also simply specify a field to match if the
- field is present, use "!field" to check if
- the field is not present, and "&" to check
- multiple conditions. Use a "\" to escape
- "&" or quotes if needed. If used multiple
- times, the filter matches if atleast one of
- the conditions are met. Eg: --match-filter
- !is_live --match-filter "like_count>?100 &
- description~='(?i)\bcats \& dogs\b'"
- matches only videos that are not live OR
- those that have a like count more than 100
- (or the like field is not available) and
- also has a description that contains the
- phrase "cats & dogs" (ignoring case). Use
- "--match-filter -" to interactively ask
- whether to download each video
- --no-match-filter Do not use generic video filter (default)
- --no-playlist Download only the video, if the URL refers
- to a video and a playlist
- --yes-playlist Download the playlist, if the URL refers to
- a video and a playlist
- --age-limit YEARS Download only videos suitable for the given
- age
- --download-archive FILE Download only videos not listed in the
- archive file. Record the IDs of all
- downloaded videos in it
- --no-download-archive Do not use archive file (default)
- --max-downloads NUMBER Abort after downloading NUMBER files
- --break-on-existing Stop the download process when encountering
- a file that is in the archive
- --break-on-reject Stop the download process when encountering
- a file that has been filtered out
- --break-per-input Make --break-on-existing, --break-on-reject
- and --max-downloads act only on the current
- input URL
- --no-break-per-input --break-on-existing and similar options
- terminates the entire download queue
- --skip-playlist-after-errors N Number of allowed failures until the rest
- of the playlist is skipped
+ --playlist-start NUMBER Playlist video to start at (default is 1)
+ --playlist-end NUMBER Playlist video to end at (default is last)
+ --playlist-items ITEM_SPEC Playlist video items to download. Specify
+ indices of the videos in the playlist
+ separated by commas like: "--playlist-items
+ 1,2,5,8" if you want to download videos
+ indexed 1, 2, 5, 8 in the playlist. You can
+ specify range: "--playlist-items
+ 1-3,7,10-13", it will download the videos at
+ index 1, 2, 3, 7, 10, 11, 12 and 13
+ --min-filesize SIZE Do not download any videos smaller than SIZE
+ (e.g. 50k or 44.6m)
+ --max-filesize SIZE Do not download any videos larger than SIZE
+ (e.g. 50k or 44.6m)
+ --date DATE Download only videos uploaded on this date.
+ The date can be "YYYYMMDD" or in the format
+ [now|today|yesterday][-N[day|week|month|year]].
+ Eg: --date today-2weeks
+ --datebefore DATE Download only videos uploaded on or before
+ this date. The date formats accepted is the
+ same as --date
+ --dateafter DATE Download only videos uploaded on or after
+ this date. The date formats accepted is the
+ same as --date
+ --match-filters FILTER Generic video filter. Any "OUTPUT TEMPLATE"
+ field can be compared with a number or a
+ string using the operators defined in
+ "Filtering formats". You can also simply
+ specify a field to match if the field is
+ present, use "!field" to check if the field
+ is not present, and "&" to check multiple
+ conditions. Use a "\" to escape "&" or
+ quotes if needed. If used multiple times,
+ the filter matches if atleast one of the
+ conditions are met. Eg: --match-filter
+ !is_live --match-filter "like_count>?100 &
+ description~='(?i)\bcats \& dogs\b'" matches
+ only videos that are not live OR those that
+ have a like count more than 100 (or the like
+ field is not available) and also has a
+ description that contains the phrase "cats &
+ dogs" (caseless). Use "--match-filter -" to
+ interactively ask whether to download each
+ video
+ --no-match-filter Do not use generic video filter (default)
+ --no-playlist Download only the video, if the URL refers
+ to a video and a playlist
+ --yes-playlist Download the playlist, if the URL refers to
+ a video and a playlist
+ --age-limit YEARS Download only videos suitable for the given
+ age
+ --download-archive FILE Download only videos not listed in the
+ archive file. Record the IDs of all
+ downloaded videos in it
+ --no-download-archive Do not use archive file (default)
+ --max-downloads NUMBER Abort after downloading NUMBER files
+ --break-on-existing Stop the download process when encountering
+ a file that is in the archive
+ --break-on-reject Stop the download process when encountering
+ a file that has been filtered out
+ --break-per-input Make --break-on-existing, --break-on-reject
+ and --max-downloads act only on the current
+ input URL
+ --no-break-per-input --break-on-existing and similar options
+ terminates the entire download queue
+ --skip-playlist-after-errors N Number of allowed failures until the rest of
+ the playlist is skipped
## Download Options:
- -N, --concurrent-fragments N Number of fragments of a dash/hlsnative
- video that should be downloaded
- concurrently (default is 1)
- -r, --limit-rate RATE Maximum download rate in bytes per second
- (e.g. 50K or 4.2M)
- --throttled-rate RATE Minimum download rate in bytes per second
- below which throttling is assumed and the
- video data is re-extracted (e.g. 100K)
- -R, --retries RETRIES Number of retries (default is 10), or
- "infinite"
- --file-access-retries RETRIES Number of times to retry on file access
- error (default is 3), or "infinite"
- --fragment-retries RETRIES Number of retries for a fragment (default
- is 10), or "infinite" (DASH, hlsnative and
- ISM)
- --skip-unavailable-fragments Skip unavailable fragments for DASH,
- hlsnative and ISM (default)
- (Alias: --no-abort-on-unavailable-fragment)
- --abort-on-unavailable-fragment Abort downloading if a fragment is unavailable
- (Alias: --no-skip-unavailable-fragments)
- --keep-fragments Keep downloaded fragments on disk after
- downloading is finished
- --no-keep-fragments Delete downloaded fragments after
- downloading is finished (default)
- --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
- (default is 1024)
- --resize-buffer The buffer size is automatically resized
- from an initial value of --buffer-size
- (default)
- --no-resize-buffer Do not automatically adjust the buffer size
- --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
- downloading (e.g. 10485760 or 10M) (default
- is disabled). May be useful for bypassing
- bandwidth throttling imposed by a webserver
- (experimental)
- --playlist-reverse Download playlist videos in reverse order
- --no-playlist-reverse Download playlist videos in default order
- (default)
- --playlist-random Download playlist videos in random order
- --xattr-set-filesize Set file xattribute ytdl.filesize with
- expected file size
- --hls-use-mpegts Use the mpegts container for HLS videos;
- allowing some players to play the video
- while downloading, and reducing the chance
- of file corruption if download is
- interrupted. This is enabled by default for
- live streams
- --no-hls-use-mpegts Do not use the mpegts container for HLS
- videos. This is default when not
- downloading live streams
- --downloader [PROTO:]NAME Name or path of the external downloader to
- use (optionally) prefixed by the protocols
- (http, ftp, m3u8, dash, rstp, rtmp, mms) to
- use it for. Currently supports native,
- aria2c, avconv, axel, curl, ffmpeg, httpie,
- wget. You can use this option multiple
- times to set different downloaders for
- different protocols. For example,
- --downloader aria2c --downloader
- "dash,m3u8:native" will use aria2c for
- http/ftp downloads, and the native
- downloader for dash/m3u8 downloads (Alias:
- --external-downloader)
- --downloader-args NAME:ARGS Give these arguments to the external
- downloader. Specify the downloader name and
- the arguments separated by a colon ":". For
- ffmpeg, arguments can be passed to
- different positions using the same syntax
- as --postprocessor-args. You can use this
- option multiple times to give different
- arguments to different downloaders (Alias:
- --external-downloader-args)
+ -N, --concurrent-fragments N Number of fragments of a dash/hlsnative
+ video that should be downloaded concurrently
+ (default is 1)
+ -r, --limit-rate RATE Maximum download rate in bytes per second
+ (e.g. 50K or 4.2M)
+ --throttled-rate RATE Minimum download rate in bytes per second
+ below which throttling is assumed and the
+ video data is re-extracted (e.g. 100K)
+ -R, --retries RETRIES Number of retries (default is 10), or
+ "infinite"
+ --file-access-retries RETRIES Number of times to retry on file access
+ error (default is 3), or "infinite"
+ --fragment-retries RETRIES Number of retries for a fragment (default is
+ 10), or "infinite" (DASH, hlsnative and ISM)
+ --retry-sleep [TYPE:]EXPR An expression for the time to sleep between
+ retries in seconds (optionally) prefixed by
+ the type of retry (file_access, fragment,
+ http (default)) to apply the sleep to. EXPR
+ can be a number, linear=START[:END[:STEP=1]]
+ or exp=START[:END[:BASE=2]]. This option can
+ be used multiple times to set the sleep for
+ the different retry types. Eg: --retry-sleep
+ linear=1::2 --retry-sleep fragment:exp=1:20
+ --skip-unavailable-fragments Skip unavailable fragments for DASH,
+ hlsnative and ISM downloads (default)
+ (Alias: --no-abort-on-unavailable-fragment)
+ --abort-on-unavailable-fragment
+ Abort download if a fragment is unavailable
+ (Alias: --no-skip-unavailable-fragments)
+ --keep-fragments Keep downloaded fragments on disk after
+ downloading is finished
+ --no-keep-fragments Delete downloaded fragments after
+ downloading is finished (default)
+ --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
+ (default is 1024)
+ --resize-buffer The buffer size is automatically resized
+ from an initial value of --buffer-size
+ (default)
+ --no-resize-buffer Do not automatically adjust the buffer size
+ --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
+ downloading (e.g. 10485760 or 10M) (default
+ is disabled). May be useful for bypassing
+ bandwidth throttling imposed by a webserver
+ (experimental)
+ --playlist-reverse Download playlist videos in reverse order
+ --no-playlist-reverse Download playlist videos in default order
+ (default)
+ --playlist-random Download playlist videos in random order
+ --xattr-set-filesize Set file xattribute ytdl.filesize with
+ expected file size
+ --hls-use-mpegts Use the mpegts container for HLS videos;
+ allowing some players to play the video
+ while downloading, and reducing the chance
+ of file corruption if download is
+ interrupted. This is enabled by default for
+ live streams
+ --no-hls-use-mpegts Do not use the mpegts container for HLS
+ videos. This is default when not downloading
+ live streams
+ --downloader [PROTO:]NAME Name or path of the external downloader to
+ use (optionally) prefixed by the protocols
+ (http, ftp, m3u8, dash, rstp, rtmp, mms) to
+ use it for. Currently supports native,
+ aria2c, avconv, axel, curl, ffmpeg, httpie,
+ wget. You can use this option multiple times
+ to set different downloaders for different
+ protocols. For example, --downloader aria2c
+ --downloader "dash,m3u8:native" will use
+ aria2c for http/ftp downloads, and the
+ native downloader for dash/m3u8 downloads
+ (Alias: --external-downloader)
+ --downloader-args NAME:ARGS Give these arguments to the external
+ downloader. Specify the downloader name and
+ the arguments separated by a colon ":". For
+ ffmpeg, arguments can be passed to different
+ positions using the same syntax as
+ --postprocessor-args. You can use this
+ option multiple times to give different
+ arguments to different downloaders (Alias:
+ --external-downloader-args)
## Filesystem Options:
- -a, --batch-file FILE File containing URLs to download ("-" for
- stdin), one URL per line. Lines starting
- with "#", ";" or "]" are considered as
- comments and ignored
- --no-batch-file Do not read URLs from batch file (default)
- -P, --paths [TYPES:]PATH The paths where the files should be
- downloaded. Specify the type of file and
- the path separated by a colon ":". All the
- same TYPES as --output are supported.
- Additionally, you can also provide "home"
- (default) and "temp" paths. All
- intermediary files are first downloaded to
- the temp path and then the final files are
- moved over to the home path after download
- is finished. This option is ignored if
- --output is an absolute path
- -o, --output [TYPES:]TEMPLATE Output filename template; see "OUTPUT
- TEMPLATE" for details
- --output-na-placeholder TEXT Placeholder value for unavailable meta
- fields in output filename template
- (default: "NA")
- --restrict-filenames Restrict filenames to only ASCII
- characters, and avoid "&" and spaces in
- filenames
- --no-restrict-filenames Allow Unicode characters, "&" and spaces in
- filenames (default)
- --windows-filenames Force filenames to be Windows-compatible
- --no-windows-filenames Make filenames Windows-compatible only if
- using Windows (default)
- --trim-filenames LENGTH Limit the filename length (excluding
- extension) to the specified number of
- characters
- -w, --no-overwrites Do not overwrite any files
- --force-overwrites Overwrite all video and metadata files.
- This option includes --no-continue
- --no-force-overwrites Do not overwrite the video, but overwrite
- related files (default)
- -c, --continue Resume partially downloaded files/fragments
- (default)
- --no-continue Do not resume partially downloaded
- fragments. If the file is not fragmented,
- restart download of the entire file
- --part Use .part files instead of writing directly
- into output file (default)
- --no-part Do not use .part files - write directly
- into output file
- --mtime Use the Last-modified header to set the
- file modification time (default)
- --no-mtime Do not use the Last-modified header to set
- the file modification time
- --write-description Write video description to a .description
- file
- --no-write-description Do not write video description (default)
- --write-info-json Write video metadata to a .info.json file
- (this may contain personal information)
- --no-write-info-json Do not write video metadata (default)
- --write-playlist-metafiles Write playlist metadata in addition to the
- video metadata when using --write-info-json,
- --write-description etc. (default)
- --no-write-playlist-metafiles Do not write playlist metadata when using
- --write-info-json, --write-description etc.
- --clean-info-json Remove some private fields such as
- filenames from the infojson. Note that it
- could still contain some personal
- information (default)
- --no-clean-info-json Write all fields to the infojson
- --write-comments Retrieve video comments to be placed in the
- infojson. The comments are fetched even
- without this option if the extraction is
- known to be quick (Alias: --get-comments)
- --no-write-comments Do not retrieve video comments unless the
- extraction is known to be quick (Alias:
- --no-get-comments)
- --load-info-json FILE JSON file containing the video information
- (created with the "--write-info-json"
- option)
- --cookies FILE Netscape formatted file to read cookies
- from and dump cookie jar in
- --no-cookies Do not read/dump cookies from/to file
- (default)
+ -a, --batch-file FILE File containing URLs to download ("-" for
+ stdin), one URL per line. Lines starting
+ with "#", ";" or "]" are considered as
+ comments and ignored
+ --no-batch-file Do not read URLs from batch file (default)
+ -P, --paths [TYPES:]PATH The paths where the files should be
+ downloaded. Specify the type of file and the
+ path separated by a colon ":". All the same
+ TYPES as --output are supported.
+ Additionally, you can also provide "home"
+ (default) and "temp" paths. All intermediary
+ files are first downloaded to the temp path
+ and then the final files are moved over to
+ the home path after download is finished.
+ This option is ignored if --output is an
+ absolute path
+ -o, --output [TYPES:]TEMPLATE Output filename template; see "OUTPUT
+ TEMPLATE" for details
+ --output-na-placeholder TEXT Placeholder for unavailable fields in
+ "OUTPUT TEMPLATE" (default: "NA")
+ --restrict-filenames Restrict filenames to only ASCII characters,
+ and avoid "&" and spaces in filenames
+ --no-restrict-filenames Allow Unicode characters, "&" and spaces in
+ filenames (default)
+ --windows-filenames Force filenames to be Windows-compatible
+ --no-windows-filenames Make filenames Windows-compatible only if
+ using Windows (default)
+ --trim-filenames LENGTH Limit the filename length (excluding
+ extension) to the specified number of
+ characters
+ -w, --no-overwrites Do not overwrite any files
+ --force-overwrites Overwrite all video and metadata files. This
+ option includes --no-continue
+ --no-force-overwrites Do not overwrite the video, but overwrite
+ related files (default)
+ -c, --continue Resume partially downloaded files/fragments
+ (default)
+ --no-continue Do not resume partially downloaded
+ fragments. If the file is not fragmented,
+ restart download of the entire file
+ --part Use .part files instead of writing directly
+ into output file (default)
+ --no-part Do not use .part files - write directly into
+ output file
+ --mtime Use the Last-modified header to set the file
+ modification time (default)
+ --no-mtime Do not use the Last-modified header to set
+ the file modification time
+ --write-description Write video description to a .description
+ file
+ --no-write-description Do not write video description (default)
+ --write-info-json Write video metadata to a .info.json file
+ (this may contain personal information)
+ --no-write-info-json Do not write video metadata (default)
+ --write-playlist-metafiles Write playlist metadata in addition to the
+ video metadata when using --write-info-json,
+ --write-description etc. (default)
+ --no-write-playlist-metafiles Do not write playlist metadata when using
+ --write-info-json, --write-description etc.
+ --clean-info-json Remove some private fields such as filenames
+ from the infojson. Note that it could still
+ contain some personal information (default)
+ --no-clean-info-json Write all fields to the infojson
+ --write-comments Retrieve video comments to be placed in the
+ infojson. The comments are fetched even
+ without this option if the extraction is
+ known to be quick (Alias: --get-comments)
+ --no-write-comments Do not retrieve video comments unless the
+ extraction is known to be quick (Alias:
+ --no-get-comments)
+ --load-info-json FILE JSON file containing the video information
+ (created with the "--write-info-json"
+ option)
+ --cookies FILE Netscape formatted file to read cookies from
+ and dump cookie jar in
+ --no-cookies Do not read/dump cookies from/to file
+ (default)
--cookies-from-browser BROWSER[+KEYRING][:PROFILE]
- The name of the browser and (optionally)
- the name/path of the profile to load
- cookies from, separated by a ":". Currently
- supported browsers are: brave, chrome,
- chromium, edge, firefox, opera, safari,
- vivaldi. By default, the most recently
- accessed profile is used. The keyring used
- for decrypting Chromium cookies on Linux
- can be (optionally) specified after the
- browser name separated by a "+". Currently
- supported keyrings are: basictext,
- gnomekeyring, kwallet
- --no-cookies-from-browser Do not load cookies from browser (default)
- --cache-dir DIR Location in the filesystem where youtube-dl
- can store some downloaded information (such
- as client ids and signatures) permanently.
- By default $XDG_CACHE_HOME/yt-dlp or
- ~/.cache/yt-dlp
- --no-cache-dir Disable filesystem caching
- --rm-cache-dir Delete all filesystem cache files
+ The name of the browser and (optionally) the
+ name/path of the profile to load cookies
+ from, separated by a ":". Currently
+ supported browsers are: brave, chrome,
+ chromium, edge, firefox, opera, safari,
+ vivaldi. By default, the most recently
+ accessed profile is used. The keyring used
+ for decrypting Chromium cookies on Linux can
+ be (optionally) specified after the browser
+ name separated by a "+". Currently supported
+ keyrings are: basictext, gnomekeyring,
+ kwallet
+ --no-cookies-from-browser Do not load cookies from browser (default)
+ --cache-dir DIR Location in the filesystem where youtube-dl
+ can store some downloaded information (such
+ as client ids and signatures) permanently.
+ By default $XDG_CACHE_HOME/yt-dlp or
+ ~/.cache/yt-dlp
+ --no-cache-dir Disable filesystem caching
+ --rm-cache-dir Delete all filesystem cache files
## Thumbnail Options:
- --write-thumbnail Write thumbnail image to disk
- --no-write-thumbnail Do not write thumbnail image to disk
- (default)
- --write-all-thumbnails Write all thumbnail image formats to disk
- --list-thumbnails List available thumbnails of each video.
- Simulate unless --no-simulate is used
+ --write-thumbnail Write thumbnail image to disk
+ --no-write-thumbnail Do not write thumbnail image to disk
+ (default)
+ --write-all-thumbnails Write all thumbnail image formats to disk
+ --list-thumbnails List available thumbnails of each video.
+ Simulate unless --no-simulate is used
## Internet Shortcut Options:
- --write-link Write an internet shortcut file, depending
- on the current platform (.url, .webloc or
- .desktop). The URL may be cached by the OS
- --write-url-link Write a .url Windows internet shortcut. The
- OS caches the URL based on the file path
- --write-webloc-link Write a .webloc macOS internet shortcut
- --write-desktop-link Write a .desktop Linux internet shortcut
+ --write-link Write an internet shortcut file, depending
+ on the current platform (.url, .webloc or
+ .desktop). The URL may be cached by the OS
+ --write-url-link Write a .url Windows internet shortcut. The
+ OS caches the URL based on the file path
+ --write-webloc-link Write a .webloc macOS internet shortcut
+ --write-desktop-link Write a .desktop Linux internet shortcut
## Verbosity and Simulation Options:
- -q, --quiet Activate quiet mode. If used with
- --verbose, print the log to stderr
- --no-warnings Ignore warnings
- -s, --simulate Do not download the video and do not write
- anything to disk
- --no-simulate Download the video even if printing/listing
- options are used
- --ignore-no-formats-error Ignore "No video formats" error. Useful for
- extracting metadata even if the videos are
- not actually available for download
- (experimental)
- --no-ignore-no-formats-error Throw error when no downloadable video
- formats are found (default)
- --skip-download Do not download the video but write all
- related files (Alias: --no-download)
- -O, --print [WHEN:]TEMPLATE Field name or output template to print to
- screen, optionally prefixed with when to
- print it, separated by a ":". Supported
- values of "WHEN" are the same as that of
- --use-postprocessor, and "video" (default).
- Implies --quiet. Implies --simulate unless
- --no-simulate or later stages of WHEN are
- used. This option can be used multiple
- times
+ -q, --quiet Activate quiet mode. If used with --verbose,
+ print the log to stderr
+ --no-warnings Ignore warnings
+ -s, --simulate Do not download the video and do not write
+ anything to disk
+ --no-simulate Download the video even if printing/listing
+ options are used
+ --ignore-no-formats-error Ignore "No video formats" error. Useful for
+ extracting metadata even if the videos are
+ not actually available for download
+ (experimental)
+ --no-ignore-no-formats-error Throw error when no downloadable video
+ formats are found (default)
+ --skip-download Do not download the video but write all
+ related files (Alias: --no-download)
+ -O, --print [WHEN:]TEMPLATE Field name or output template to print to
+ screen, optionally prefixed with when to
+ print it, separated by a ":". Supported
+ values of "WHEN" are the same as that of
+ --use-postprocessor, and "video" (default).
+ Implies --quiet. Implies --simulate unless
+ --no-simulate or later stages of WHEN are
+ used. This option can be used multiple times
--print-to-file [WHEN:]TEMPLATE FILE
- Append given template to the file. The
- values of WHEN and TEMPLATE are same as
- that of --print. FILE uses the same syntax
- as the output template. This option can be
- used multiple times
- -j, --dump-json Quiet, but print JSON information for each
- video. Simulate unless --no-simulate is
- used. See "OUTPUT TEMPLATE" for a
- description of available keys
- -J, --dump-single-json Quiet, but print JSON information for each
- url or infojson passed. Simulate unless
- --no-simulate is used. If the URL refers to
- a playlist, the whole playlist information
- is dumped in a single line
- --force-write-archive Force download archive entries to be
- written as far as no errors occur, even if
- -s or another simulation option is used
- (Alias: --force-download-archive)
- --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
+ Append given template to the file. The
+ values of WHEN and TEMPLATE are same as that
+ of --print. FILE uses the same syntax as the
+ output template. This option can be used
+ multiple times
+ -j, --dump-json Quiet, but print JSON information for each
+ video. Simulate unless --no-simulate is
+ used. See "OUTPUT TEMPLATE" for a
+ description of available keys
+ -J, --dump-single-json Quiet, but print JSON information for each
+ url or infojson passed. Simulate unless
+ --no-simulate is used. If the URL refers to
+ a playlist, the whole playlist information
+ is dumped in a single line
+ --force-write-archive Force download archive entries to be written
+ as far as no errors occur, even if -s or
+ another simulation option is used (Alias:
+ --force-download-archive)
+ --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, optionally
- prefixed with one of "download:" (default),
- "download-title:" (the console title),
- "postprocess:", or "postprocess-title:".
- The video's fields are accessible under the
- "info" key and the progress attributes are
- accessible under "progress" key. E.g.:
- --console-title --progress-template
- "download-title:%(info.id)s-%(progress.eta)s"
- -v, --verbose Print various debugging information
- --dump-pages Print downloaded pages encoded using base64
- to debug problems (very verbose)
- --write-pages Write downloaded intermediary pages to
- files in the current directory to debug
- problems
- --print-traffic Display sent and read HTTP traffic
+ Template for progress outputs, optionally
+ prefixed with one of "download:" (default),
+ "download-title:" (the console title),
+ "postprocess:", or "postprocess-title:".
+ The video's fields are accessible under the
+ "info" key and the progress attributes are
+ accessible under "progress" key. E.g.:
+ --console-title --progress-template
+ "download-title:%(info.id)s-%(progress.eta)s"
+ -v, --verbose Print various debugging information
+ --dump-pages Print downloaded pages encoded using base64
+ to debug problems (very verbose)
+ --write-pages Write downloaded intermediary pages to files
+ in the current directory to debug problems
+ --print-traffic Display sent and read HTTP traffic
## Workarounds:
- --encoding ENCODING Force the specified encoding (experimental)
- --legacy-server-connect Explicitly allow HTTPS connection to
- servers that do not support RFC 5746 secure
- renegotiation
- --no-check-certificates Suppress HTTPS certificate validation
- --prefer-insecure Use an unencrypted connection to retrieve
- information about the video (Currently
- supported only for YouTube)
- --add-header FIELD:VALUE Specify a custom HTTP header and its value,
- separated by a colon ":". You can use this
- option multiple times
- --bidi-workaround Work around terminals that lack
- bidirectional text support. Requires bidiv
- or fribidi executable in PATH
- --sleep-requests SECONDS Number of seconds to sleep between requests
- during data extraction
- --sleep-interval SECONDS Number of seconds to sleep before each
- download. This is the minimum time to sleep
- when used along with --max-sleep-interval
- (Alias: --min-sleep-interval)
- --max-sleep-interval SECONDS Maximum number of seconds to sleep. Can
- only be used along with --min-sleep-interval
- --sleep-subtitles SECONDS Number of seconds to sleep before each
- subtitle download
+ --encoding ENCODING Force the specified encoding (experimental)
+ --legacy-server-connect Explicitly allow HTTPS connection to servers
+ that do not support RFC 5746 secure
+ renegotiation
+ --no-check-certificates Suppress HTTPS certificate validation
+ --prefer-insecure Use an unencrypted connection to retrieve
+ information about the video (Currently
+ supported only for YouTube)
+ --add-header FIELD:VALUE Specify a custom HTTP header and its value,
+ separated by a colon ":". You can use this
+ option multiple times
+ --bidi-workaround Work around terminals that lack
+ bidirectional text support. Requires bidiv
+ or fribidi executable in PATH
+ --sleep-requests SECONDS Number of seconds to sleep between requests
+ during data extraction
+ --sleep-interval SECONDS Number of seconds to sleep before each
+ download. This is the minimum time to sleep
+ when used along with --max-sleep-interval
+ (Alias: --min-sleep-interval)
+ --max-sleep-interval SECONDS Maximum number of seconds to sleep. Can only
+ be used along with --min-sleep-interval
+ --sleep-subtitles SECONDS Number of seconds to sleep before each
+ subtitle download
## Video Format Options:
- -f, --format FORMAT Video format code, see "FORMAT SELECTION"
- for more details
- -S, --format-sort SORTORDER Sort the formats by the fields given, see
- "Sorting Formats" for more details
- --S-force, --format-sort-force Force user specified sort order to have
- precedence over all fields, see "Sorting
- Formats" for more details
- --no-format-sort-force Some fields have precedence over the user
- specified sort order (default), see
- "Sorting Formats" for more details
- --video-multistreams Allow multiple video streams to be merged
- into a single file
- --no-video-multistreams Only one video stream is downloaded for
- each output file (default)
- --audio-multistreams Allow multiple audio streams to be merged
- into a single file
- --no-audio-multistreams Only one audio stream is downloaded for
- each output file (default)
- --prefer-free-formats Prefer video formats with free containers
- over non-free ones of same quality. Use
- with "-S ext" to strictly prefer free
- containers irrespective of quality
- --no-prefer-free-formats Don't give any special preference to free
- containers (default)
- --check-formats Make sure formats are selected only from
- those that are actually downloadable
- --check-all-formats Check all formats for whether they are
- actually downloadable
- --no-check-formats Do not check that the formats are actually
- downloadable
- -F, --list-formats List available formats of each video.
- Simulate unless --no-simulate is used
- --merge-output-format FORMAT If a merge is required (e.g.
- bestvideo+bestaudio), output to given
- container format. One of mkv, mp4, ogg,
- webm, flv. Ignored if no merge is required
+ -f, --format FORMAT Video format code, see "FORMAT SELECTION"
+ for more details
+ -S, --format-sort SORTORDER Sort the formats by the fields given, see
+ "Sorting Formats" for more details
+ --format-sort-force Force user specified sort order to have
+ precedence over all fields, see "Sorting
+ Formats" for more details (Alias: --S-force)
+ --no-format-sort-force Some fields have precedence over the user
+ specified sort order (default)
+ --video-multistreams Allow multiple video streams to be merged
+ into a single file
+ --no-video-multistreams Only one video stream is downloaded for each
+ output file (default)
+ --audio-multistreams Allow multiple audio streams to be merged
+ into a single file
+ --no-audio-multistreams Only one audio stream is downloaded for each
+ output file (default)
+ --prefer-free-formats Prefer video formats with free containers
+ over non-free ones of same quality. Use with
+ "-S ext" to strictly prefer free containers
+ irrespective of quality
+ --no-prefer-free-formats Don't give any special preference to free
+ containers (default)
+ --check-formats Make sure formats are selected only from
+ those that are actually downloadable
+ --check-all-formats Check all formats for whether they are
+ actually downloadable
+ --no-check-formats Do not check that the formats are actually
+ downloadable
+ -F, --list-formats List available formats of each video.
+ Simulate unless --no-simulate is used
+ --merge-output-format FORMAT If a merge is required (e.g.
+ bestvideo+bestaudio), output to given
+ container format. One of mkv, mp4, ogg,
+ webm, flv. Ignored if no merge is required
## Subtitle Options:
- --write-subs Write subtitle file
- --no-write-subs Do not write subtitle file (default)
- --write-auto-subs Write automatically generated subtitle file
- (Alias: --write-automatic-subs)
- --no-write-auto-subs Do not write auto-generated subtitles
- (default) (Alias: --no-write-automatic-subs)
- --list-subs List available subtitles of each video.
- Simulate unless --no-simulate is used
- --sub-format FORMAT Subtitle format, accepts formats
- preference, for example: "srt" or
- "ass/srt/best"
- --sub-langs LANGS Languages of the subtitles to download (can
- be regex) or "all" separated by commas.
- (Eg: --sub-langs "en.*,ja") You can prefix
- the language code with a "-" to exempt it
- from the requested languages. (Eg:
- --sub-langs all,-live_chat) Use --list-subs
- for a list of available language tags
+ --write-subs Write subtitle file
+ --no-write-subs Do not write subtitle file (default)
+ --write-auto-subs Write automatically generated subtitle file
+ (Alias: --write-automatic-subs)
+ --no-write-auto-subs Do not write auto-generated subtitles
+ (default) (Alias: --no-write-automatic-subs)
+ --list-subs List available subtitles of each video.
+ Simulate unless --no-simulate is used
+ --sub-format FORMAT Subtitle format; accepts formats preference,
+ Eg: "srt" or "ass/srt/best"
+ --sub-langs LANGS Languages of the subtitles to download (can
+ be regex) or "all" separated by commas. (Eg:
+ --sub-langs "en.*,ja") You can prefix the
+ language code with a "-" to exclude it from
+ the requested languages. (Eg: --sub-langs
+ all,-live_chat) Use --list-subs for a list
+ of available language tags
## Authentication Options:
- -u, --username USERNAME Login with this account ID
- -p, --password PASSWORD Account password. If this option is left
- out, yt-dlp will ask interactively
- -2, --twofactor TWOFACTOR Two-factor authentication code
- -n, --netrc Use .netrc authentication data
- --netrc-location PATH Location of .netrc authentication data;
- either the path or its containing
- directory. Defaults to ~/.netrc
- --video-password PASSWORD Video password (vimeo, youku)
- --ap-mso MSO Adobe Pass multiple-system operator (TV
- provider) identifier, use --ap-list-mso for
- a list of available MSOs
- --ap-username USERNAME Multiple-system operator account login
- --ap-password PASSWORD Multiple-system operator account password.
- If this option is left out, yt-dlp will ask
- interactively
- --ap-list-mso List all supported multiple-system
- operators
- --client-certificate CERTFILE Path to client certificate file in PEM
- format. May include the private key
- --client-certificate-key KEYFILE Path to private key file for client
- certificate
+ -u, --username USERNAME Login with this account ID
+ -p, --password PASSWORD Account password. If this option is left
+ out, yt-dlp will ask interactively
+ -2, --twofactor TWOFACTOR Two-factor authentication code
+ -n, --netrc Use .netrc authentication data
+ --netrc-location PATH Location of .netrc authentication data;
+ either the path or its containing directory.
+ Defaults to ~/.netrc
+ --video-password PASSWORD Video password (vimeo, youku)
+ --ap-mso MSO Adobe Pass multiple-system operator (TV
+ provider) identifier, use --ap-list-mso for
+ a list of available MSOs
+ --ap-username USERNAME Multiple-system operator account login
+ --ap-password PASSWORD Multiple-system operator account password.
+ If this option is left out, yt-dlp will ask
+ interactively
+ --ap-list-mso List all supported multiple-system operators
+ --client-certificate CERTFILE Path to client certificate file in PEM
+ format. May include the private key
+ --client-certificate-key KEYFILE
+ Path to private key file for client
+ certificate
--client-certificate-password PASSWORD
- Password for client certificate private
- key, if encrypted. If not provided and the
- key is encrypted, yt-dlp will ask
- interactively
+ Password for client certificate private key,
+ if encrypted. If not provided, and the key
+ is encrypted, yt-dlp will ask interactively
## Post-Processing Options:
- -x, --extract-audio Convert video files to audio-only files
- (requires ffmpeg and ffprobe)
- --audio-format FORMAT Specify audio format to convert the audio
- to when -x is used. Currently supported
- formats are: best (default) or one of aac,
- flac, mp3, m4a, opus, vorbis, wav, alac
- --audio-quality QUALITY Specify ffmpeg audio quality to use when
- converting the audio with -x. Insert a
- value between 0 (best) and 10 (worst) for
- VBR or a specific bitrate like 128K
- (default 5)
- --remux-video FORMAT Remux the video into another container if
- necessary (currently supported: mp4, mkv,
- flv, webm, mov, avi, mka, ogg, aac, flac,
- mp3, m4a, opus, vorbis, wav, alac). If
- target container does not support the
- video/audio codec, remuxing will fail. You
- can specify multiple rules; Eg.
- "aac>m4a/mov>mp4/mkv" will remux aac to
- m4a, mov to mp4 and anything else to mkv.
- --recode-video FORMAT Re-encode the video into another format if
- re-encoding is necessary. The syntax and
- supported formats are the same as --remux-video
- --postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
- Specify the postprocessor/executable name
- and the arguments separated by a colon ":"
- to give the argument to the specified
- postprocessor/executable. Supported PP are:
- Merger, ModifyChapters, SplitChapters,
- ExtractAudio, VideoRemuxer, VideoConvertor,
- Metadata, EmbedSubtitle, EmbedThumbnail,
- SubtitlesConvertor, ThumbnailsConvertor,
- FixupStretched, FixupM4a, FixupM3u8,
- FixupTimestamp and FixupDuration. The
- supported executables are: AtomicParsley,
- FFmpeg and FFprobe. You can also specify
- "PP+EXE:ARGS" to give the arguments to the
- specified executable only when being used
- by the specified postprocessor.
- Additionally, for ffmpeg/ffprobe, "_i"/"_o"
- can be appended to the prefix optionally
- followed by a number to pass the argument
- before the specified input/output file. Eg:
- --ppa "Merger+ffmpeg_i1:-v quiet". You can
- use this option multiple times to give
- different arguments to different
- postprocessors. (Alias: --ppa)
- -k, --keep-video Keep the intermediate video file on disk
- after post-processing
- --no-keep-video Delete the intermediate video file after
- post-processing (default)
- --post-overwrites Overwrite post-processed files (default)
- --no-post-overwrites Do not overwrite post-processed files
- --embed-subs Embed subtitles in the video (only for mp4,
- webm and mkv videos)
- --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. Also
- embeds chapters/infojson if present unless
- --no-embed-chapters/--no-embed-info-json
- are used (Alias: --add-metadata)
- --no-embed-metadata Do not add metadata to file (default)
- (Alias: --no-add-metadata)
- --embed-chapters Add chapter markers to the video file
- (Alias: --add-chapters)
- --no-embed-chapters Do not add chapter markers (default)
- (Alias: --no-add-chapters)
- --embed-info-json Embed the infojson as an attachment to
- mkv/mka video files
- --no-embed-info-json Do not embed the infojson as an attachment
- to the video file
- --parse-metadata FROM:TO Parse additional metadata like title/artist
- from other fields; see "MODIFYING METADATA"
- for details
+ -x, --extract-audio Convert video files to audio-only files
+ (requires ffmpeg and ffprobe)
+ --audio-format FORMAT Specify audio format to convert the audio to
+ when -x is used. Currently supported formats
+ are: best (default) or one of aac, flac,
+ mp3, m4a, opus, vorbis, wav, alac
+ --audio-quality QUALITY Specify ffmpeg audio quality to use when
+ converting the audio with -x. Insert a value
+ between 0 (best) and 10 (worst) for VBR or a
+ specific bitrate like 128K (default 5)
+ --remux-video FORMAT Remux the video into another container if
+ necessary (currently supported: mp4, mkv,
+ flv, webm, mov, avi, mka, ogg, aac, flac,
+ mp3, m4a, opus, vorbis, wav, alac). If
+ target container does not support the
+ video/audio codec, remuxing will fail. You
+ can specify multiple rules; Eg.
+ "aac>m4a/mov>mp4/mkv" will remux aac to m4a,
+ mov to mp4 and anything else to mkv.
+ --recode-video FORMAT Re-encode the video into another format if
+ necessary. The syntax and supported formats
+ are the same as --remux-video
+ --postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
+ Specify the postprocessor/executable name
+ and the arguments separated by a colon ":"
+ to give the argument to the specified
+ postprocessor/executable. Supported PP are:
+ Merger, ModifyChapters, SplitChapters,
+ ExtractAudio, VideoRemuxer, VideoConvertor,
+ Metadata, EmbedSubtitle, EmbedThumbnail,
+ SubtitlesConvertor, ThumbnailsConvertor,
+ FixupStretched, FixupM4a, FixupM3u8,
+ FixupTimestamp and FixupDuration. The
+ supported executables are: AtomicParsley,
+ FFmpeg and FFprobe. You can also specify
+ "PP+EXE:ARGS" to give the arguments to the
+ specified executable only when being used by
+ the specified postprocessor. Additionally,
+ for ffmpeg/ffprobe, "_i"/"_o" can be
+ appended to the prefix optionally followed
+ by a number to pass the argument before the
+ specified input/output file. Eg: --ppa
+ "Merger+ffmpeg_i1:-v quiet". You can use
+ this option multiple times to give different
+ arguments to different postprocessors.
+ (Alias: --ppa)
+ -k, --keep-video Keep the intermediate video file on disk
+ after post-processing
+ --no-keep-video Delete the intermediate video file after
+ post-processing (default)
+ --post-overwrites Overwrite post-processed files (default)
+ --no-post-overwrites Do not overwrite post-processed files
+ --embed-subs Embed subtitles in the video (only for mp4,
+ webm and mkv videos)
+ --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. Also
+ embeds chapters/infojson if present unless
+ --no-embed-chapters/--no-embed-info-json are
+ used (Alias: --add-metadata)
+ --no-embed-metadata Do not add metadata to file (default)
+ (Alias: --no-add-metadata)
+ --embed-chapters Add chapter markers to the video file
+ (Alias: --add-chapters)
+ --no-embed-chapters Do not add chapter markers (default) (Alias:
+ --no-add-chapters)
+ --embed-info-json Embed the infojson as an attachment to
+ mkv/mka video files
+ --no-embed-info-json Do not embed the infojson as an attachment
+ to the video file
+ --parse-metadata FROM:TO Parse additional metadata like title/artist
+ from other fields; see "MODIFYING METADATA"
+ for details
--replace-in-metadata FIELDS REGEX REPLACE
- Replace text in a metadata field using the
- given regex. This option can be used
- multiple times
- --xattrs Write metadata to the video file's xattrs
- (using dublin core and xdg standards)
- --concat-playlist POLICY Concatenate videos in a playlist. One of
- "never", "always", or "multi_video"
- (default; only when the videos form a
- single show). All the video files must have
- same codecs and number of streams to be
- concatable. The "pl_video:" prefix can be
- used with "--paths" and "--output" to set
- the output filename for the concatenated
- files. See "OUTPUT TEMPLATE" for details
- --fixup POLICY Automatically correct known faults of the
- file. One of never (do nothing), warn (only
- emit a warning), detect_or_warn (the
- default; fix file if we can, warn
- otherwise), force (try fixing even if file
- already exists)
- --ffmpeg-location PATH Location of the ffmpeg binary; either the
- path to the binary or its containing
- directory
- --exec [WHEN:]CMD Execute a command, optionally prefixed with
- when to execute it (after_move if
- unspecified), separated by a ":". Supported
- values of "WHEN" are the same as that of
- --use-postprocessor. Same syntax as the
- output template can be used to pass any
- field as arguments to the command. After
- download, an additional field "filepath"
- that contains the final path of the
- downloaded file is also available, and if
- no fields are passed, %(filepath)q is
- appended to the end of the command. This
- option can be used multiple times
- --no-exec Remove any previously defined --exec
- --convert-subs FORMAT Convert the subtitles to another format
- (currently supported: srt, vtt, ass, lrc)
- (Alias: --convert-subtitles)
- --convert-thumbnails FORMAT Convert the thumbnails to another format
- (currently supported: jpg, png, webp)
- --split-chapters Split video into multiple files based on
- internal chapters. The "chapter:" prefix
- can be used with "--paths" and "--output"
- to set the output filename for the split
- files. See "OUTPUT TEMPLATE" for details
- --no-split-chapters Do not split video based on chapters
- (default)
- --remove-chapters REGEX Remove chapters whose title matches the
- given regular expression. Time ranges
- prefixed by a "*" can also be used in place
- of chapters to remove the specified range.
- Eg: --remove-chapters "*10:15-15:00"
- --remove-chapters "intro". This option can
- be used multiple times
- --no-remove-chapters Do not remove any chapters from the file
- (default)
- --force-keyframes-at-cuts Force keyframes around the chapters before
- removing/splitting them. Requires a
- re-encode and thus is very slow, but the
- resulting video may have fewer artifacts
- around the cuts
- --no-force-keyframes-at-cuts Do not force keyframes around the chapters
- when cutting/splitting (default)
- --use-postprocessor NAME[:ARGS] The (case sensitive) name of plugin
- postprocessors to be enabled, and
- (optionally) arguments to be passed to it,
- separated by a colon ":". ARGS are a
- semicolon ";" delimited list of NAME=VALUE.
- The "when" argument determines when the
- postprocessor is invoked. It can be one of
- "pre_process" (after video extraction),
- "after_filter" (after video passes filter),
- "before_dl" (before each video download),
- "post_process" (after each video download;
- default), "after_move" (after moving video
- file to it's final locations),
- "after_video" (after downloading and
- processing all formats of a video), or
- "playlist" (at end of playlist). This
- option can be used multiple times to add
- different postprocessors
+ Replace text in a metadata field using the
+ given regex. This option can be used
+ multiple times
+ --xattrs Write metadata to the video file's xattrs
+ (using dublin core and xdg standards)
+ --concat-playlist POLICY Concatenate videos in a playlist. One of
+ "never", "always", or "multi_video"
+ (default; only when the videos form a single
+ show). All the video files must have same
+ codecs and number of streams to be
+ concatable. The "pl_video:" prefix can be
+ used with "--paths" and "--output" to set
+ the output filename for the concatenated
+ files. See "OUTPUT TEMPLATE" for details
+ --fixup POLICY Automatically correct known faults of the
+ file. One of never (do nothing), warn (only
+ emit a warning), detect_or_warn (the
+ default; fix file if we can, warn
+ otherwise), force (try fixing even if file
+ already exists)
+ --ffmpeg-location PATH Location of the ffmpeg binary; either the
+ path to the binary or its containing
+ directory
+ --exec [WHEN:]CMD Execute a command, optionally prefixed with
+ when to execute it (after_move if
+ unspecified), separated by a ":". Supported
+ values of "WHEN" are the same as that of
+ --use-postprocessor. Same syntax as the
+ output template can be used to pass any
+ field as arguments to the command. After
+ download, an additional field "filepath"
+ that contains the final path of the
+ downloaded file is also available, and if no
+ fields are passed, %(filepath)q is appended
+ to the end of the command. This option can
+ be used multiple times
+ --no-exec Remove any previously defined --exec
+ --convert-subs FORMAT Convert the subtitles to another format
+ (currently supported: srt, vtt, ass, lrc)
+ (Alias: --convert-subtitles)
+ --convert-thumbnails FORMAT Convert the thumbnails to another format
+ (currently supported: jpg, png, webp). You
+ can specify multiple rules using similar
+ syntax as --remux-video
+ --split-chapters Split video into multiple files based on
+ internal chapters. The "chapter:" prefix can
+ be used with "--paths" and "--output" to set
+ the output filename for the split files. See
+ "OUTPUT TEMPLATE" for details
+ --no-split-chapters Do not split video based on chapters
+ (default)
+ --remove-chapters REGEX Remove chapters whose title matches the
+ given regular expression. Time ranges
+ prefixed by a "*" can also be used in place
+ of chapters to remove the specified range.
+ Eg: --remove-chapters "*10:15-15:00"
+ --remove-chapters "intro". This option can
+ be used multiple times
+ --no-remove-chapters Do not remove any chapters from the file
+ (default)
+ --force-keyframes-at-cuts Force keyframes around chapters when
+ removing/splitting them. This is slow due to
+ needing a re-encode, but the resulting video
+ may have fewer artifacts around the cuts
+ --no-force-keyframes-at-cuts Do not force keyframes around the chapters
+ when cutting/splitting (default)
+ --use-postprocessor NAME[:ARGS]
+ The (case sensitive) name of plugin
+ postprocessors to be enabled, and
+ (optionally) arguments to be passed to it,
+ separated by a colon ":". ARGS are a
+ semicolon ";" delimited list of NAME=VALUE.
+ The "when" argument determines when the
+ postprocessor is invoked. It can be one of
+ "pre_process" (after video extraction),
+ "after_filter" (after video passes filter),
+ "before_dl" (before each video download),
+ "post_process" (after each video download;
+ default), "after_move" (after moving video
+ file to it's final locations), "after_video"
+ (after downloading and processing all
+ formats of a video), or "playlist" (at end
+ of playlist). This option can be used
+ multiple times to add different
+ postprocessors
## SponsorBlock Options:
Make chapter entries for, or remove various segments (sponsor,
introductions, etc.) from downloaded YouTube videos using the
[SponsorBlock API](https://sponsor.ajay.app)
- --sponsorblock-mark CATS SponsorBlock categories to create chapters
- for, separated by commas. Available
- categories are all, default(=all), sponsor,
- intro, outro, selfpromo, preview, filler,
- interaction, music_offtopic, poi_highlight.
- You can prefix the category with a "-" to
- exempt it. See [1] for description of the
- categories. Eg: --sponsorblock-mark all,-preview
- [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
- --sponsorblock-remove CATS SponsorBlock categories to be removed from
- the video file, separated by commas. If a
- category is present in both mark and
- remove, remove takes precedence. The syntax
- and available categories are the same as
- for --sponsorblock-mark except that
- "default" refers to "all,-filler" and
- poi_highlight is not available
+ --sponsorblock-mark CATS SponsorBlock categories to create chapters
+ for, separated by commas. Available
+ categories are sponsor, intro, outro,
+ selfpromo, preview, filler, interaction,
+ music_offtopic, poi_highlight, all and
+ default (=all). You can prefix the category
+ with a "-" to exclude it. See [1] for
+ description of the categories. Eg:
+ --sponsorblock-mark all,-preview
+ [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
+ --sponsorblock-remove CATS SponsorBlock categories to be removed from
+ the video file, separated by commas. If a
+ category is present in both mark and remove,
+ remove takes precedence. The syntax and
+ available categories are the same as for
+ --sponsorblock-mark except that "default"
+ refers to "all,-filler" and poi_highlight is
+ not available
--sponsorblock-chapter-title TEMPLATE
- The title template for SponsorBlock
- chapters created by --sponsorblock-mark.
- The same syntax as the output template is
- used, but the only available fields are
- start_time, end_time, category, categories,
- name, category_names. Defaults to
- "[SponsorBlock]: %(category_names)l"
- --no-sponsorblock Disable both --sponsorblock-mark and
- --sponsorblock-remove
- --sponsorblock-api URL SponsorBlock API location, defaults to
- https://sponsor.ajay.app
+ An output template for the title of the
+ SponsorBlock chapters created by
+ --sponsorblock-mark. The only available
+ fields are start_time, end_time, category,
+ categories, name, category_names. Defaults
+ to "[SponsorBlock]: %(category_names)l"
+ --no-sponsorblock Disable both --sponsorblock-mark and
+ --sponsorblock-remove
+ --sponsorblock-api URL SponsorBlock API location, defaults to
+ https://sponsor.ajay.app
## Extractor Options:
- --extractor-retries RETRIES Number of retries for known extractor
- errors (default is 3), or "infinite"
- --allow-dynamic-mpd Process dynamic DASH manifests (default)
- (Alias: --no-ignore-dynamic-mpd)
- --ignore-dynamic-mpd Do not process dynamic DASH manifests
- (Alias: --no-allow-dynamic-mpd)
- --hls-split-discontinuity Split HLS playlists to different formats at
- discontinuities such as ad breaks
- --no-hls-split-discontinuity Do not split HLS playlists to different
- formats at discontinuities such as ad
- breaks (default)
- --extractor-args KEY:ARGS Pass these arguments to the extractor. See
- "EXTRACTOR ARGUMENTS" for details. You can
- use this option multiple times to give
- arguments for different extractors
+ --extractor-retries RETRIES Number of retries for known extractor errors
+ (default is 3), or "infinite"
+ --allow-dynamic-mpd Process dynamic DASH manifests (default)
+ (Alias: --no-ignore-dynamic-mpd)
+ --ignore-dynamic-mpd Do not process dynamic DASH manifests
+ (Alias: --no-allow-dynamic-mpd)
+ --hls-split-discontinuity Split HLS playlists to different formats at
+ discontinuities such as ad breaks
+ --no-hls-split-discontinuity Do not split HLS playlists to different
+ formats at discontinuities such as ad breaks
+ (default)
+ --extractor-args KEY:ARGS Pass these arguments to the extractor. See
+ "EXTRACTOR ARGUMENTS" for details. You can
+ use this option multiple times to give
+ arguments for different extractors
# CONFIGURATION
ydl.download(URLS)
```
-Most likely, you'll want to use various options. For a list of options available, have a look at [`yt_dlp/YoutubeDL.py`](yt_dlp/YoutubeDL.py#L181).
+Most likely, you'll want to use various options. For a list of options available, have a look at [`yt_dlp/YoutubeDL.py`](yt_dlp/YoutubeDL.py#L180).
**Tip**: If you are porting your code from youtube-dl to yt-dlp, one important point to look out for is that we do not guarantee the return value of `YoutubeDL.extract_info` to be json serializable, or even be a dictionary. It will be dictionary-like, but if you want to ensure it is a serializable dictionary, pass it through `YoutubeDL.sanitize_info` as shown in the [example below](#extracting-information)
These options are not intended to be used by the end-user
--test Download only part of video for testing extractors
+ --load-pages Load pages dumped by --write-pages
--youtube-print-sig-code For testing youtube signatures
--allow-unplayable-formats List unplayable formats also
--no-allow-unplayable-formats Default