1yt-dlp(1) yt-dlp(1)
2
6 yt-dlp - A youtube-dl fork with additional features and patches
7
9 yt-dlp [OPTIONS] URL [URL...]
10
12 yt-dlp is a youtube-dl (https://github.com/ytdl-org/youtube-dl) fork
13 based on the now inactive youtube-dlc (https://github.com/black‐
14 jack4494/yt-dlc). The main focus of this project is adding new fea‐
15 tures and patches while also keeping up to date with the original
16 project
17
19 General Options:
20 -h, --help
21 Print this help text and exit
22 --version
24 Print program version and exit
25 -U, --update
27 Update this program to latest version
28 --no-update
30 Do not update (default)
31 -i, --ignore-errors
33 Ignore download and postprocessing errors. The download will be
34 considered successful even if the postprocessing fails
35 --no-abort-on-error
37 Continue with next video on download errors; e.g. to skip un‐
38 available videos in a playlist (default)
39 --abort-on-error
41 Abort downloading of further videos if an error occurs (Alias:
42 --no-ignore-errors)
43 --dump-user-agent
45 Display the current user-agent and exit
46 --list-extractors
48 List all supported extractors and exit
49 --extractor-descriptions
51 Output descriptions of all supported extractors and exit
52 --force-generic-extractor
54 Force extraction to use the generic extractor
55 --default-search PREFIX
57 Use this prefix for unqualified URLs. Eg: "gvsearch2:python"
58 downloads two videos from google videos for the search term
59 "python". Use the value "auto" to let yt-dlp guess ("auto_warn‐
60 ing" to emit a warning when guessing). "error" just throws an
61 error. The default value "fixup_error" repairs broken URLs, but
62 emits an error if this is not possible instead of searching
63 --ignore-config
65 Don't load any more configuration files except those given by
66 --config-locations. For backward compatibility, if this option
67 is found inside the system configuration file, the user configu‐
68 ration is not loaded. (Alias: --no-config)
69 --no-config-locations
71 Do not load any custom configuration files (default). When giv‐
72 en inside a configuration file, ignore all previous --config-lo‐
73 cations defined in the current file
74 --config-locations PATH
76 Location of the main configuration file; either the path to the
77 config or its containing directory ("-" for stdin). Can be used
78 multiple times and inside other configuration files
79 --flat-playlist
81 Do not extract the videos of a playlist, only list them
82 --no-flat-playlist
84 Extract the videos of a playlist
85 --live-from-start
87 Download livestreams from the start. Currently only supported
88 for YouTube (Experimental)
89 --no-live-from-start
91 Download livestreams from the current time (default)
92 --wait-for-video MIN[-MAX]
94 Wait for scheduled streams to become available. Pass the mini‐
95 mum number of seconds (or range) to wait between retries
96 --no-wait-for-video
98 Do not wait for scheduled streams (default)
99 --mark-watched
101 Mark videos watched (even with --simulate)
102 --no-mark-watched
104 Do not mark videos watched (default)
105 --no-colors
107 Do not emit color codes in output
108 --compat-options OPTS
110 Options that can help keep compatibility with youtube-dl or
111 youtube-dlc configurations by reverting some of the changes made
112 in yt-dlp. See "Differences in default behavior" for details
113 --alias ALIASES OPTIONS
115 Create aliases for an option string. Unless an alias starts
116 with a dash "-", it is prefixed with "--". Arguments are parsed
117 according to the Python string formatting mini-language. Eg:
118 --alias get-audio,-X "-S=aext:{0},abr -x --audio-format {0}"
119 creates options "--get-audio" and "-X" that takes an argument
120 (ARG0) and expands to "-S=aext:ARG0,abr -x --audio-format ARG0".
121 All defined aliases are listed in the --help output. Alias op‐
122 tions can trigger more aliases; so be careful to avoid defining
123 recursive options. As a safety measure, each alias may be trig‐
124 gered a maximum of 100 times. This option can be used multiple
125 times
126 Network Options:
128 --proxy URL
129 Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS
130 proxy, specify a proper scheme. Eg: socks5://us‐
131 er:pass@127.0.0.1:1080/. Pass in an empty string (--proxy "")
132 for direct connection
133 --socket-timeout SECONDS
135 Time to wait before giving up, in seconds
136 --source-address IP
138 Client-side IP address to bind to
139 -4, --force-ipv4
141 Make all connections via IPv4
142 -6, --force-ipv6
144 Make all connections via IPv6
145 Geo-restriction:
147 --geo-verification-proxy URL
148 Use this proxy to verify the IP address for some geo-restricted
149 sites. The default proxy specified by --proxy (or none, if the
150 option is not present) is used for the actual downloading
151 --geo-bypass
153 Bypass geographic restriction via faking X-Forwarded-For HTTP
154 header (default)
155 --no-geo-bypass
157 Do not bypass geographic restriction via faking X-Forwarded-For
158 HTTP header
159 --geo-bypass-country CODE
161 Force bypass geographic restriction with explicitly provided
162 two-letter ISO 3166-2 country code
163 --geo-bypass-ip-block IP_BLOCK
165 Force bypass geographic restriction with explicitly provided IP
166 block in CIDR notation
167 Video Selection:
169 -I, --playlist-items ITEM_SPEC
170 Comma separated playlist_index of the videos to download. You
171 can specify a range using "[START]:[STOP][:STEP]". For backward
172 compatibility, START-STOP is also supported. Use negative in‐
173 dices to count from the right and negative STEP to download in
174 reverse order. Eg: "-I 1:3,7,-5::2" used on a playlist of size
175 15 will download the videos at index 1,2,3,7,11,13,15
176 --min-filesize SIZE
178 Do not download any videos smaller than SIZE (e.g. 50k or
179 44.6m)
180 --max-filesize SIZE
182 Do not download any videos larger than SIZE (e.g. 50k or 44.6m)
183 --date DATE
185 Download only videos uploaded on this date. The date can be
186 "YYYYMMDD" or in the format [now|today|yesterday][-
187 N[day|week|month|year]]. Eg: --date today-2weeks
188 --datebefore DATE
190 Download only videos uploaded on or before this date. The date
191 formats accepted is the same as --date
192 --dateafter DATE
194 Download only videos uploaded on or after this date. The date
195 formats accepted is the same as --date
196 --match-filters FILTER
198 Generic video filter. Any "OUTPUT TEMPLATE" field can be com‐
199 pared with a number or a string using the operators defined in
200 "Filtering formats". You can also simply specify a field to
201 match if the field is present, use "!field" to check if the
202 field is not present, and "&" to check multiple conditions. Use
203 a "" to escape "&" or quotes if needed. If used multiple times,
204 the filter matches if atleast one of the conditions are met.
205 Eg: --match-filter !is_live --match-filter "like_count>?100 &
206 description~='(?i)& dogs" matches only videos that are not live
207 OR those that have a like count more than 100 (or the like field
208 is not available) and also has a description that contains the
209 phrase "cats & dogs" (caseless). Use "--match-filter -" to in‐
210 teractively ask whether to download each video
211 --no-match-filter
213 Do not use generic video filter (default)
214 --no-playlist
216 Download only the video, if the URL refers to a video and a
217 playlist
218 --yes-playlist
220 Download the playlist, if the URL refers to a video and a
221 playlist
222 --age-limit YEARS
224 Download only videos suitable for the given age
225 --download-archive FILE
227 Download only videos not listed in the archive file. Record the
228 IDs of all downloaded videos in it
229 --no-download-archive
231 Do not use archive file (default)
232 --max-downloads NUMBER
234 Abort after downloading NUMBER files
235 --break-on-existing
237 Stop the download process when encountering a file that is in
238 the archive
239 --break-on-reject
241 Stop the download process when encountering a file that has been
242 filtered out
243 --break-per-input
245 Make --break-on-existing, --break-on-reject and --max-downloads
246 act only on the current input URL
247 --no-break-per-input
249 --break-on-existing and similar options terminates the entire
250 download queue
251 --skip-playlist-after-errors N
253 Number of allowed failures until the rest of the playlist is
254 skipped
255 Download Options:
257 -N, --concurrent-fragments N
258 Number of fragments of a dash/hlsnative video that should be
259 downloaded concurrently (default is 1)
260 -r, --limit-rate RATE
262 Maximum download rate in bytes per second (e.g. 50K or 4.2M)
263 --throttled-rate RATE
265 Minimum download rate in bytes per second below which throttling
266 is assumed and the video data is re-extracted (e.g. 100K)
267 -R, --retries RETRIES
269 Number of retries (default is 10), or "infinite"
270 --file-access-retries RETRIES
272 Number of times to retry on file access error (default is 3), or
273 "infinite"
274 --fragment-retries RETRIES
276 Number of retries for a fragment (default is 10), or "infinite"
277 (DASH, hlsnative and ISM)
278 --retry-sleep [TYPE:]EXPR
280 An expression for the time to sleep between retries in seconds
281 (optionally) prefixed by the type of retry (file_access, frag‐
282 ment, http (default)) to apply the sleep to. EXPR can be a num‐
283 ber, linear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]].
284 This option can be used multiple times to set the sleep for the
285 different retry types. Eg: --retry-sleep linear=1::2 --retry-
286 sleep fragment:exp=1:20
287 --skip-unavailable-fragments
289 Skip unavailable fragments for DASH, hlsnative and ISM downloads
290 (default) (Alias: --no-abort-on-unavailable-fragment)
291 --abort-on-unavailable-fragment
293 Abort download if a fragment is unavailable (Alias: --no-skip-
294 unavailable-fragments)
295 --keep-fragments
297 Keep downloaded fragments on disk after downloading is finished
298 --no-keep-fragments
300 Delete downloaded fragments after downloading is finished (de‐
301 fault)
302 --buffer-size SIZE
304 Size of download buffer (e.g. 1024 or 16K) (default is 1024)
305 --resize-buffer
307 The buffer size is automatically resized from an initial value
308 of --buffer-size (default)
309 --no-resize-buffer
311 Do not automatically adjust the buffer size
312 --http-chunk-size SIZE
314 Size of a chunk for chunk-based HTTP downloading (e.g. 10485760
315 or 10M) (default is disabled). May be useful for bypassing
316 bandwidth throttling imposed by a webserver (experimental)
317 --playlist-random
319 Download playlist videos in random order
320 --lazy-playlist
322 Process entries in the playlist as they are received. This dis‐
323 ables n_entries, --playlist-random and --playlist-reverse
324 --no-lazy-playlist
326 Process videos in the playlist only after the entire playlist is
327 parsed (default)
328 --xattr-set-filesize
330 Set file xattribute ytdl.filesize with expected file size
331 --hls-use-mpegts
333 Use the mpegts container for HLS videos; allowing some players
334 to play the video while downloading, and reducing the chance of
335 file corruption if download is interrupted. This is enabled by
336 default for live streams
337 --no-hls-use-mpegts
339 Do not use the mpegts container for HLS videos. This is default
340 when not downloading live streams
341 --download-sections REGEX
343 Download only chapters whose title matches the given regular ex‐
344 pression. Time ranges prefixed by a "" can also be used in
345 place of chapters to download the specified range. Eg: --down‐
346 load-sections "10:15-15:00" --download-sections "intro". Needs
347 ffmpeg. This option can be used multiple times to download mul‐
348 tiple sections
349 --downloader [PROTO:]NAME
351 Name or path of the external downloader to use (optionally) pre‐
352 fixed by the protocols (http, ftp, m3u8, dash, rstp, rtmp, mms)
353 to use it for. Currently supports native, aria2c, avconv, axel,
354 curl, ffmpeg, httpie, wget. You can use this option multiple
355 times to set different downloaders for different protocols. For
356 example, --downloader aria2c --downloader "dash,m3u8:native"
357 will use aria2c for http/ftp downloads, and the native download‐
358 er for dash/m3u8 downloads (Alias: --external-downloader)
359 --downloader-args NAME:ARGS
361 Give these arguments to the external downloader. Specify the
362 downloader name and the arguments separated by a colon ":". For
363 ffmpeg, arguments can be passed to different positions using the
364 same syntax as --postprocessor-args. You can use this option
365 multiple times to give different arguments to different down‐
366 loaders (Alias: --external-downloader-args)
367 Filesystem Options:
369 -a, --batch-file FILE
370 File containing URLs to download ("-" for stdin), one URL per
371 line. Lines starting with "#", ";" or "]" are considered as
372 comments and ignored
373 --no-batch-file
375 Do not read URLs from batch file (default)
376 -P, --paths [TYPES:]PATH
378 The paths where the files should be downloaded. Specify the
379 type of file and the path separated by a colon ":". All the
380 same TYPES as --output are supported. Additionally, you can al‐
381 so provide "home" (default) and "temp" paths. All intermediary
382 files are first downloaded to the temp path and then the final
383 files are moved over to the home path after download is fin‐
384 ished. This option is ignored if --output is an absolute path
385 -o, --output [TYPES:]TEMPLATE
387 Output filename template; see "OUTPUT TEMPLATE" for details
388 --output-na-placeholder TEXT
390 Placeholder for unavailable fields in "OUTPUT TEMPLATE" (de‐
391 fault: "NA")
392 --restrict-filenames
394 Restrict filenames to only ASCII characters, and avoid "&" and
395 spaces in filenames
396 --no-restrict-filenames
398 Allow Unicode characters, "&" and spaces in filenames (default)
399 --windows-filenames
401 Force filenames to be Windows-compatible
402 --no-windows-filenames
404 Make filenames Windows-compatible only if using Windows (de‐
405 fault)
406 --trim-filenames LENGTH
408 Limit the filename length (excluding extension) to the specified
409 number of characters
410 -w, --no-overwrites
412 Do not overwrite any files
413 --force-overwrites
415 Overwrite all video and metadata files. This option includes
416 --no-continue
417 --no-force-overwrites
419 Do not overwrite the video, but overwrite related files (de‐
420 fault)
421 -c, --continue
423 Resume partially downloaded files/fragments (default)
424 --no-continue
426 Do not resume partially downloaded fragments. If the file is
427 not fragmented, restart download of the entire file
428 --part Use .part files instead of writing directly into output file
430 (default)
431 --no-part
433 Do not use .part files - write directly into output file
434 --mtime
436 Use the Last-modified header to set the file modification time
437 (default)
438 --no-mtime
440 Do not use the Last-modified header to set the file modification
441 time
442 --write-description
444 Write video description to a .description file
445 --no-write-description
447 Do not write video description (default)
448 --write-info-json
450 Write video metadata to a .info.json file (this may contain per‐
451 sonal information)
452 --no-write-info-json
454 Do not write video metadata (default)
455 --write-playlist-metafiles
457 Write playlist metadata in addition to the video metadata when
458 using --write-info-json, --write-description etc. (default)
459 --no-write-playlist-metafiles
461 Do not write playlist metadata when using --write-info-json,
462 --write-description etc.
463 --clean-info-json
465 Remove some private fields such as filenames from the infojson.
466 Note that it could still contain some personal information (de‐
467 fault)
468 --no-clean-info-json
470 Write all fields to the infojson
471 --write-comments
473 Retrieve video comments to be placed in the infojson. The com‐
474 ments are fetched even without this option if the extraction is
475 known to be quick (Alias: --get-comments)
476 --no-write-comments
478 Do not retrieve video comments unless the extraction is known to
479 be quick (Alias: --no-get-comments)
480 --load-info-json FILE
482 JSON file containing the video information (created with the
483 "--write-info-json" option)
484 --cookies FILE
486 Netscape formatted file to read cookies from and dump cookie jar
487 in
488 --no-cookies
490 Do not read/dump cookies from/to file (default)
491 --cookies-from-browser BROWSER[+KEYRING][:PROFILE]
493 The name of the browser and (optionally) the name/path of the
494 profile to load cookies from, separated by a ":". Currently
495 supported browsers are: brave, chrome, chromium, edge, firefox,
496 opera, safari, vivaldi. By default, the most recently accessed
497 profile is used. The keyring used for decrypting Chromium cook‐
498 ies on Linux can be (optionally) specified after the browser
499 name separated by a "+". Currently supported keyrings are: ba‐
500 sictext, gnomekeyring, kwallet
501 --no-cookies-from-browser
503 Do not load cookies from browser (default)
504 --cache-dir DIR
506 Location in the filesystem where youtube-dl can store some down‐
507 loaded information (such as client ids and signatures) perma‐
508 nently. By default $XDG_CACHE_HOME/yt-dlp or ~/.cache/yt-dlp
509 --no-cache-dir
511 Disable filesystem caching
512 --rm-cache-dir
514 Delete all filesystem cache files
515 Thumbnail Options:
517 --write-thumbnail
518 Write thumbnail image to disk
519 --no-write-thumbnail
521 Do not write thumbnail image to disk (default)
522 --write-all-thumbnails
524 Write all thumbnail image formats to disk
525 --list-thumbnails
527 List available thumbnails of each video. Simulate unless --no-
528 simulate is used
529 Internet Shortcut Options:
531 --write-link
532 Write an internet shortcut file, depending on the current plat‐
533 form (.url, .webloc or .desktop). The URL may be cached by the
534 OS
535 --write-url-link
537 Write a .url Windows internet shortcut. The OS caches the URL
538 based on the file path
539 --write-webloc-link
541 Write a .webloc macOS internet shortcut
542 --write-desktop-link
544 Write a .desktop Linux internet shortcut
545 Verbosity and Simulation Options:
547 -q, --quiet
548 Activate quiet mode. If used with --verbose, print the log to
549 stderr
550 --no-warnings
552 Ignore warnings
553 -s, --simulate
555 Do not download the video and do not write anything to disk
556 --no-simulate
558 Download the video even if printing/listing options are used
559 --ignore-no-formats-error
561 Ignore "No video formats" error. Useful for extracting metadata
562 even if the videos are not actually available for download (ex‐
563 perimental)
564 --no-ignore-no-formats-error
566 Throw error when no downloadable video formats are found (de‐
567 fault)
568 --skip-download
570 Do not download the video but write all related files (Alias:
571 --no-download)
572 -O, --print [WHEN:]TEMPLATE
574 Field name or output template to print to screen, optionally
575 prefixed with when to print it, separated by a ":". Supported
576 values of "WHEN" are the same as that of --use-postprocessor,
577 and "video" (default). Implies --quiet. Implies --simulate un‐
578 less --no-simulate or later stages of WHEN are used. This op‐
579 tion can be used multiple times
580 --print-to-file [WHEN:]TEMPLATE FILE
582 Append given template to the file. The values of WHEN and TEM‐
583 PLATE are same as that of --print. FILE uses the same syntax as
584 the output template. This option can be used multiple times
585 -j, --dump-json
587 Quiet, but print JSON information for each video. Simulate un‐
588 less --no-simulate is used. See "OUTPUT TEMPLATE" for a de‐
589 scription of available keys
590 -J, --dump-single-json
592 Quiet, but print JSON information for each url or infojson
593 passed. Simulate unless --no-simulate is used. If the URL
594 refers to a playlist, the whole playlist information is dumped
595 in a single line
596 --force-write-archive
598 Force download archive entries to be written as far as no errors
599 occur, even if -s or another simulation option is used (Alias:
600 --force-download-archive)
601 --newline
603 Output progress bar as new lines
604 --no-progress
606 Do not print progress bar
607 --progress
609 Show progress bar, even if in quiet mode
610 --console-title
612 Display progress in console titlebar
613 --progress-template [TYPES:]TEMPLATE
615 Template for progress outputs, optionally prefixed with one of
616 "download:" (default), "download-title:" (the console title),
617 "postprocess:", or "postprocess-title:". The video's fields are
618 accessible under the "info" key and the progress attributes are
619 accessible under "progress" key. E.g.: --console-title
620 --progress-template "download-title:%(in‐
621 fo.id)s-%(progress.eta)s"
622 -v, --verbose
624 Print various debugging information
625 --dump-pages
627 Print downloaded pages encoded using base64 to debug problems
628 (very verbose)
629 --write-pages
631 Write downloaded intermediary pages to files in the current di‐
632 rectory to debug problems
633 --print-traffic
635 Display sent and read HTTP traffic
636 Workarounds:
638 --encoding ENCODING
639 Force the specified encoding (experimental)
640 --legacy-server-connect
642 Explicitly allow HTTPS connection to servers that do not support
643 RFC 5746 secure renegotiation
644 --no-check-certificates
646 Suppress HTTPS certificate validation
647 --prefer-insecure
649 Use an unencrypted connection to retrieve information about the
650 video (Currently supported only for YouTube)
651 --add-header FIELD:VALUE
653 Specify a custom HTTP header and its value, separated by a colon
654 ":". You can use this option multiple times
655 --bidi-workaround
657 Work around terminals that lack bidirectional text support. Re‐
658 quires bidiv or fribidi executable in PATH
659 --sleep-requests SECONDS
661 Number of seconds to sleep between requests during data extrac‐
662 tion
663 --sleep-interval SECONDS
665 Number of seconds to sleep before each download. This is the
666 minimum time to sleep when used along with --max-sleep-interval
667 (Alias: --min-sleep-interval)
668 --max-sleep-interval SECONDS
670 Maximum number of seconds to sleep. Can only be used along with
671 --min-sleep-interval
672 --sleep-subtitles SECONDS
674 Number of seconds to sleep before each subtitle download
675 Video Format Options:
677 -f, --format FORMAT
678 Video format code, see "FORMAT SELECTION" for more details
679 -S, --format-sort SORTORDER
681 Sort the formats by the fields given, see "Sorting Formats" for
682 more details
683 --format-sort-force
685 Force user specified sort order to have precedence over all
686 fields, see "Sorting Formats" for more details (Alias: --S-
687 force)
688 --no-format-sort-force
690 Some fields have precedence over the user specified sort order
691 (default)
692 --video-multistreams
694 Allow multiple video streams to be merged into a single file
695 --no-video-multistreams
697 Only one video stream is downloaded for each output file (de‐
698 fault)
699 --audio-multistreams
701 Allow multiple audio streams to be merged into a single file
702 --no-audio-multistreams
704 Only one audio stream is downloaded for each output file (de‐
705 fault)
706 --prefer-free-formats
708 Prefer video formats with free containers over non-free ones of
709 same quality. Use with "-S ext" to strictly prefer free con‐
710 tainers irrespective of quality
711 --no-prefer-free-formats
713 Don't give any special preference to free containers (default)
714 --check-formats
716 Make sure formats are selected only from those that are actually
717 downloadable
718 --check-all-formats
720 Check all formats for whether they are actually downloadable
721 --no-check-formats
723 Do not check that the formats are actually downloadable
724 -F, --list-formats
726 List available formats of each video. Simulate unless --no-sim‐
727 ulate is used
728 --merge-output-format FORMAT
730 If a merge is required (e.g. bestvideo+bestaudio), output to
731 given container format. One of mkv, mp4, ogg, webm, flv. Ig‐
732 nored if no merge is required
733 Subtitle Options:
735 --write-subs
736 Write subtitle file
737 --no-write-subs
739 Do not write subtitle file (default)
740 --write-auto-subs
742 Write automatically generated subtitle file (Alias: --write-au‐
743 tomatic-subs)
744 --no-write-auto-subs
746 Do not write auto-generated subtitles (default) (Alias: --no-
747 write-automatic-subs)
748 --list-subs
750 List available subtitles of each video. Simulate unless --no-
751 simulate is used
752 --sub-format FORMAT
754 Subtitle format; accepts formats preference, Eg: "srt" or
755 "ass/srt/best"
756 --sub-langs LANGS
758 Languages of the subtitles to download (can be regex) or "all"
759 separated by commas. (Eg: --sub-langs "en.*,ja") You can prefix
760 the language code with a "-" to exclude it from the requested
761 languages. (Eg: --sub-langs all,-live_chat) Use --list-subs for
762 a list of available language tags
763 Authentication Options:
765 -u, --username USERNAME
766 Login with this account ID
767 -p, --password PASSWORD
769 Account password. If this option is left out, yt-dlp will ask
770 interactively
771 -2, --twofactor TWOFACTOR
773 Two-factor authentication code
774 -n, --netrc
776 Use .netrc authentication data
777 --netrc-location PATH
779 Location of .netrc authentication data; either the path or its
780 containing directory. Defaults to ~/.netrc
781 --video-password PASSWORD
783 Video password (vimeo, youku)
784 --ap-mso MSO
786 Adobe Pass multiple-system operator (TV provider) identifier,
787 use --ap-list-mso for a list of available MSOs
788 --ap-username USERNAME
790 Multiple-system operator account login
791 --ap-password PASSWORD
793 Multiple-system operator account password. If this option is
794 left out, yt-dlp will ask interactively
795 --ap-list-mso
797 List all supported multiple-system operators
798 --client-certificate CERTFILE
800 Path to client certificate file in PEM format. May include the
801 private key
802 --client-certificate-key KEYFILE
804 Path to private key file for client certificate
805 --client-certificate-password PASSWORD
807 Password for client certificate private key, if encrypted. If
808 not provided, and the key is encrypted, yt-dlp will ask interac‐
809 tively
810 Post-Processing Options:
812 -x, --extract-audio
813 Convert video files to audio-only files (requires ffmpeg and ff‐
814 probe)
815 --audio-format FORMAT
817 Format to convert the audio to when -x is used. (currently sup‐
818 ported: best (default), mp3, aac, m4a, opus, vorbis, flac, alac,
819 wav). You can specify multiple rules using similar syntax as
820 --remux-video
821 --audio-quality QUALITY
823 Specify ffmpeg audio quality to use when converting the audio
824 with -x. Insert a value between 0 (best) and 10 (worst) for VBR
825 or a specific bitrate like 128K (default 5)
826 --remux-video FORMAT
828 Remux the video into another container if necessary (currently
829 supported: mp4, mkv, flv, webm, mov, avi, mka, ogg, mp3, aac,
830 m4a, opus, vorbis, flac, alac, wav). If target container does
831 not support the video/audio codec, remuxing will fail. You can
832 specify multiple rules; Eg. "aac>m4a/mov>mp4/mkv" will remux
833 aac to m4a, mov to mp4 and anything else to mkv
834 --recode-video FORMAT
836 Re-encode the video into another format if necessary. The syn‐
837 tax and supported formats are the same as --remux-video
838 --postprocessor-args NAME:ARGS
840 Give these arguments to the postprocessors. Specify the post‐
841 processor/executable name and the arguments separated by a colon
842 ":" to give the argument to the specified postprocessor/exe‐
843 cutable. Supported PP are: Merger, ModifyChapters, SplitChap‐
844 ters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, Em‐
845 bedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsCon‐
846 vertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp and
847 FixupDuration. The supported executables are: AtomicParsley,
848 FFmpeg and FFprobe. You can also specify "PP+EXE:ARGS" to give
849 the arguments to the specified executable only when being used
850 by the specified postprocessor. Additionally, for ffmpeg/ff‐
851 probe, "_i"/"_o" can be appended to the prefix optionally fol‐
852 lowed by a number to pass the argument before the specified in‐
853 put/output file. Eg: --ppa "Merger+ffmpeg_i1:-v quiet". You
854 can use this option multiple times to give different arguments
855 to different postprocessors. (Alias: --ppa)
856 -k, --keep-video
858 Keep the intermediate video file on disk after post-processing
859 --no-keep-video
861 Delete the intermediate video file after post-processing (de‐
862 fault)
863 --post-overwrites
865 Overwrite post-processed files (default)
866 --no-post-overwrites
868 Do not overwrite post-processed files
869 --embed-subs
871 Embed subtitles in the video (only for mp4, webm and mkv videos)
872 --no-embed-subs
874 Do not embed subtitles (default)
875 --embed-thumbnail
877 Embed thumbnail in the video as cover art
878 --no-embed-thumbnail
880 Do not embed thumbnail (default)
881 --embed-metadata
883 Embed metadata to the video file. Also embeds chapters/infojson
884 if present unless --no-embed-chapters/--no-embed-info-json are
885 used (Alias: --add-metadata)
886 --no-embed-metadata
888 Do not add metadata to file (default) (Alias: --no-add-metadata)
889 --embed-chapters
891 Add chapter markers to the video file (Alias: --add-chapters)
892 --no-embed-chapters
894 Do not add chapter markers (default) (Alias: --no-add-chapters)
895 --embed-info-json
897 Embed the infojson as an attachment to mkv/mka video files
898 --no-embed-info-json
900 Do not embed the infojson as an attachment to the video file
901 --parse-metadata FROM:TO
903 Parse additional metadata like title/artist from other fields;
904 see "MODIFYING METADATA" for details
905 --replace-in-metadata FIELDS REGEX REPLACE
907 Replace text in a metadata field using the given regex. This
908 option can be used multiple times
909 --xattrs
911 Write metadata to the video file's xattrs (using dublin core and
912 xdg standards)
913 --concat-playlist POLICY
915 Concatenate videos in a playlist. One of "never", "always", or
916 "multi_video" (default; only when the videos form a single
917 show). All the video files must have same codecs and number of
918 streams to be concatable. The "pl_video:" prefix can be used
919 with "--paths" and "--output" to set the output filename for the
920 concatenated files. See "OUTPUT TEMPLATE" for details
921 --fixup POLICY
923 Automatically correct known faults of the file. One of never
924 (do nothing), warn (only emit a warning), detect_or_warn (the
925 default; fix file if we can, warn otherwise), force (try fixing
926 even if file already exists)
927 --ffmpeg-location PATH
929 Location of the ffmpeg binary; either the path to the binary or
930 its containing directory
931 --exec [WHEN:]CMD
933 Execute a command, optionally prefixed with when to execute it
934 (after_move if unspecified), separated by a ":". Supported val‐
935 ues of "WHEN" are the same as that of --use-postprocessor. Same
936 syntax as the output template can be used to pass any field as
937 arguments to the command. After download, an additional field
938 "filepath" that contains the final path of the downloaded file
939 is also available, and if no fields are passed, %(filepath)q is
940 appended to the end of the command. This option can be used
941 multiple times
942 --no-exec
944 Remove any previously defined --exec
945 --convert-subs FORMAT
947 Convert the subtitles to another format (currently supported:
948 srt, vtt, ass, lrc) (Alias: --convert-subtitles)
949 --convert-thumbnails FORMAT
951 Convert the thumbnails to another format (currently supported:
952 jpg, png, webp). You can specify multiple rules using similar
953 syntax as --remux-video
954 --split-chapters
956 Split video into multiple files based on internal chapters. The
957 "chapter:" prefix can be used with "--paths" and "--output" to
958 set the output filename for the split files. See "OUTPUT TEM‐
959 PLATE" for details
960 --no-split-chapters
962 Do not split video based on chapters (default)
963 --remove-chapters REGEX
965 Remove chapters whose title matches the given regular expres‐
966 sion. The syntax is the same as --download-sections. This op‐
967 tion can be used multiple times
968 --no-remove-chapters
970 Do not remove any chapters from the file (default)
971 --force-keyframes-at-cuts
973 Force keyframes at cuts when downloading/splitting/removing sec‐
974 tions. This is slow due to needing a re-encode, but the result‐
975 ing video may have fewer artifacts around the cuts
976 --no-force-keyframes-at-cuts
978 Do not force keyframes around the chapters when cutting/split‐
979 ting (default)
980 --use-postprocessor NAME[:ARGS]
982 The (case sensitive) name of plugin postprocessors to be en‐
983 abled, and (optionally) arguments to be passed to it, separated
984 by a colon ":". ARGS are a semicolon ";" delimited list of
985 NAME=VALUE. The "when" argument determines when the postproces‐
986 sor is invoked. It can be one of "pre_process" (after video ex‐
987 traction), "after_filter" (after video passes filter), "be‐
988 fore_dl" (before each video download), "post_process" (after
989 each video download; default), "after_move" (after moving video
990 file to it's final locations), "after_video" (after downloading
991 and processing all formats of a video), or "playlist" (at end of
992 playlist). This option can be used multiple times to add dif‐
993 ferent postprocessors
994 SponsorBlock Options:
996 Make chapter entries for, or remove various segments (sponsor, intro‐
997 ductions, etc.) from downloaded YouTube videos using the SponsorBlock
998 API (https://sponsor.ajay.app)
999 --sponsorblock-mark CATS
1001 SponsorBlock categories to create chapters for, separated by
1002 commas. Available categories are sponsor, intro, outro, self‐
1003 promo, preview, filler, interaction, music_offtopic, poi_high‐
1004 light, all and default (=all). You can prefix the category with
1005 a "-" to exclude it. See [1] for description of the categories.
1006 Eg: --sponsorblock-mark all,-preview [1] https://wiki.spon‐
1007 sor.ajay.app/w/Segment_Categories
1008 --sponsorblock-remove CATS
1010 SponsorBlock categories to be removed from the video file, sepa‐
1011 rated by commas. If a category is present in both mark and re‐
1012 move, remove takes precedence. The syntax and available cate‐
1013 gories are the same as for --sponsorblock-mark except that "de‐
1014 fault" refers to "all,-filler" and poi_highlight is not avail‐
1015 able
1016 --sponsorblock-chapter-title TEMPLATE
1018 An output template for the title of the SponsorBlock chapters
1019 created by --sponsorblock-mark. The only available fields are
1020 start_time, end_time, category, categories, name, catego‐
1021 ry_names. Defaults to "[SponsorBlock]: %(category_names)l"
1022 --no-sponsorblock
1024 Disable both --sponsorblock-mark and --sponsorblock-remove
1025 --sponsorblock-api URL
1027 SponsorBlock API location, defaults to https://sponsor.ajay.app
1028 Extractor Options:
1030 --extractor-retries RETRIES
1031 Number of retries for known extractor errors (default is 3), or
1032 "infinite"
1033 --allow-dynamic-mpd
1035 Process dynamic DASH manifests (default) (Alias: --no-ignore-dy‐
1036 namic-mpd)
1037 --ignore-dynamic-mpd
1039 Do not process dynamic DASH manifests (Alias: --no-allow-dynam‐
1040 ic-mpd)
1041 --hls-split-discontinuity
1043 Split HLS playlists to different formats at discontinuities such
1044 as ad breaks
1045 --no-hls-split-discontinuity
1047 Do not split HLS playlists to different formats at discontinu‐
1048 ities such as ad breaks (default)
1049 --extractor-args KEY:ARGS
1051 Pass these arguments to the extractor. See "EXTRACTOR ARGU‐
1052 MENTS" for details. You can use this option multiple times to
1053 give arguments for different extractors
1054
1056 You can configure yt-dlp by placing any supported command line option
1057 to a configuration file. The configuration is loaded from the follow‐
1058 ing locations:
1059 1. Main Configuration: The file given by --config-location
1061 2. Portable Configuration: yt-dlp.conf in the same directory as the
1063 bundled binary. If you are running from source-code (<root
1064 dir>/yt_dlp/__main__.py), the root directory is used instead.
1065 3. Home Configuration: yt-dlp.conf in the home path given by -P, or in
1067 the current directory if no such path is given
1068 4. User Configuration:
1070 • %XDG_CONFIG_HOME%/yt-dlp/config (recommended on Linux/macOS)
1072 • %XDG_CONFIG_HOME%/yt-dlp.conf
1074 • %APPDATA%/yt-dlp/config (recommended on Windows)
1076 • %APPDATA%/yt-dlp/config.txt
1078 • ~/yt-dlp.conf
1080 • ~/yt-dlp.conf.txt
1082 %XDG_CONFIG_HOME% defaults to ~/.config if undefined. On windows,
1084 %APPDATA% generally points to C:\Users\<user name>\AppData\Roaming
1085 and ~ points to %HOME% if present, %USERPROFILE% (generally
1086 C:\Users\<user name>), or %HOMEDRIVE%%HOMEPATH%
1087 5. System Configuration: /etc/yt-dlp.conf
1089 For example, with the following configuration file yt-dlp will always
1091 extract the audio, not copy the mtime, use a proxy and save all videos
1092 under YouTube directory in your home directory:
1093 # Lines starting with # are comments
1095 # Always extract audio
1097 -x
1098 # Do not copy the mtime
1100 --no-mtime
1101 # Use this proxy
1103 --proxy 127.0.0.1:3128
1104 # Save all videos under YouTube directory in your home directory
1106 -o ~/YouTube/%(title)s.%(ext)s
1107 Note that options in configuration file are just the same options aka
1109 switches used in regular command line calls; thus there must be no
1110 whitespace after - or --, e.g. -o or --proxy but not - o or -- proxy.
1111 You can use --ignore-config if you want to disable all configuration
1113 files for a particular yt-dlp run. If --ignore-config is found inside
1114 any configuration file, no further configuration will be loaded. For
1115 example, having the option in the portable configuration file prevents
1116 loading of home, user, and system configurations. Additionally, (for
1117 backward compatibility) if --ignore-config is found inside the system
1118 configuration file, the user configuration is not loaded.
1119 Authentication with .netrc file
1121 You may also want to configure automatic credentials storage for ex‐
1122 tractors that support authentication (by providing login and password
1123 with --username and --password) in order not to pass credentials as
1124 command line arguments on every yt-dlp execution and prevent tracking
1125 plain text passwords in the shell command history. You can achieve
1126 this using a .netrc file (https://stackoverflow.com/tags/.netrc/info)
1127 on a per extractor basis. For that you will need to create a .netrc
1128 file in --netrc-location and restrict permissions to read/write by only
1129 you:
1130 touch $HOME/.netrc
1132 chmod a-rwx,u+rw $HOME/.netrc
1133 After that you can add credentials for an extractor in the following
1135 format, where extractor is the name of the extractor in lowercase:
1136 machine <extractor> login <username> password <password>
1138 For example:
1140 machine youtube login myaccount@gmail.com password my_youtube_password
1142 machine twitch login my_twitch_account_name password my_twitch_password
1143 To activate authentication with the .netrc file you should pass --netrc
1145 to yt-dlp or place it in the configuration file.
1146 The default location of the .netrc file is $HOME (~) in UNIX. On Win‐
1148 dows, it is %HOME% if present, %USERPROFILE% (generally C:\Users\<user
1149 name>) or %HOMEDRIVE%%HOMEPATH%
1150
1152 The -o option is used to indicate a template for the output file names
1153 while -P option is used to specify the path each type of file should be
1154 saved to.
1155 The simplest usage of -o is not to set any template arguments when
1157 downloading a single file, like in yt-dlp -o funny_video.flv
1158 "https://some/video" (hard-coding file extension like this is not rec‐
1159 ommended and could break some post-processing).
1160 It may however also contain special sequences that will be replaced
1162 when downloading each video. The special sequences may be formatted
1163 according to Python string formatting operations
1164 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1165 formatting). For example, %(NAME)s or %(NAME)05d. To clarify, that is
1166 a percent symbol followed by a name in parentheses, followed by format‐
1167 ting operations.
1168 The field names themselves (the part inside the parenthesis) can also
1170 have some special formatting:
1171 1. Object traversal: The dictionaries and lists available in metadata
1173 can be traversed by using a . (dot) separator. You can also do
1174 python slicing using :. Eg: %(tags.0)s, %(subtitles.en.-1.ext)s,
1175 %(id.3:7:-1)s, %(formats.:.format_id)s. %()s refers to the entire
1176 infodict. Note that all the fields that become available using this
1177 method are not listed below. Use -j to see such fields
1178 2. Addition: Addition and subtraction of numeric fields can be done us‐
1180 ing + and - respectively. Eg: %(playlist_index+10)03d, %(n_en‐
1181 tries+1-playlist_index)d
1182 3. Date/time Formatting: Date/time fields can be formatted according to
1184 strftime formatting (https://docs.python.org/3/library/date‐
1185 time.html#strftime-and-strptime-format-codes) by specifying it sepa‐
1186 rated from the field name using a >. Eg: %(duration>%H-%M-%S)s,
1187 %(upload_date>%Y-%m-%d)s, %(epoch-3600>%H-%M-%S)s
1188 4. Alternatives: Alternate fields can be specified separated with a ,.
1190 Eg: %(release_date>%Y,upload_date>%Y|Unknown)s
1191 5. Replacement: A replacement value can specified using a & separator.
1193 If the field is not empty, this replacement value will be used in‐
1194 stead of the actual field content. This is done after alternate
1195 fields are considered; thus the replacement is used if any of the
1196 alternative fields is not empty.
1197 6. Default: A literal default value can be specified for when the field
1199 is empty using a | separator. This overrides --output-na-template.
1200 Eg: %(uploader|Unknown)s
1201 7. More Conversions: In addition to the normal format types diouxXeEf‐
1203 FgGcrs, B, j, l, q, D, S can be used for converting to Bytes, json
1204 (flag # for pretty-printing), a comma separated list (flag # for \n
1205 newline-separated), a string quoted for the terminal (flag # to
1206 split a list into different arguments), to add Decimal suffixes (Eg:
1207 10M) (flag # to use 1024 as factor), and to Sanitize as filename
1208 (flag # for restricted), respectively
1209 8. Unicode normalization: The format type U can be used for NFC unicode
1211 normalization (https://docs.python.org/3/library/unicodeda‐
1212 ta.html#unicodedata.normalize). The alternate form flag (#) changes
1213 the normalization to NFD and the conversion flag + can be used for
1214 NFKC/NFKD compatibility equivalence normalization. Eg: %(ti‐
1215 tle)+.100U is NFKC
1216 To summarize, the general syntax for a field is:
1218 %(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
1220 Additionally, you can set different output templates for the various
1222 metadata files separately from the general output template by specify‐
1223 ing the type of file followed by the template separated by a colon :.
1224 The different file types supported are subtitle, thumbnail, descrip‐
1225 tion, annotation (deprecated), infojson, link, pl_thumbnail, pl_de‐
1226 scription, pl_infojson, chapter, pl_video. For example, -o "%(ti‐
1227 tle)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s" will put the
1228 thumbnails in a folder with the same name as the video. If any of the
1229 templates is empty, that type of file will not be written. Eg:
1230 --write-thumbnail -o "thumbnail:" will write thumbnails only for
1231 playlists and not for video.
1232 The available fields are:
1234 • id (string): Video identifier
1236 • title (string): Video title
1238 • fulltitle (string): Video title ignoring live timestamp and generic
1240 title
1241 • url (string): Video URL
1243 • ext (string): Video filename extension
1245 • alt_title (string): A secondary title of the video
1247 • description (string): The description of the video
1249 • display_id (string): An alternative identifier for the video
1251 • uploader (string): Full name of the video uploader
1253 • license (string): License name the video is licensed under
1255 • creator (string): The creator of the video
1257 • timestamp (numeric): UNIX timestamp of the moment the video became
1259 available
1260 • upload_date (string): Video upload date in UTC (YYYYMMDD)
1262 • release_timestamp (numeric): UNIX timestamp of the moment the video
1264 was released
1265 • release_date (string): The date (YYYYMMDD) when the video was re‐
1267 leased in UTC
1268 • modified_timestamp (numeric): UNIX timestamp of the moment the video
1270 was last modified
1271 • modified_date (string): The date (YYYYMMDD) when the video was last
1273 modified in UTC
1274 • uploader_id (string): Nickname or id of the video uploader
1276 • channel (string): Full name of the channel the video is uploaded on
1278 • channel_id (string): Id of the channel
1280 • channel_follower_count (numeric): Number of followers of the channel
1282 • location (string): Physical location where the video was filmed
1284 • duration (numeric): Length of the video in seconds
1286 • duration_string (string): Length of the video (HH:mm:ss)
1288 • view_count (numeric): How many users have watched the video on the
1290 platform
1291 • like_count (numeric): Number of positive ratings of the video
1293 • dislike_count (numeric): Number of negative ratings of the video
1295 • repost_count (numeric): Number of reposts of the video
1297 • average_rating (numeric): Average rating give by users, the scale
1299 used depends on the webpage
1300 • comment_count (numeric): Number of comments on the video (For some
1302 extractors, comments are only downloaded at the end, and so this
1303 field cannot be used)
1304 • age_limit (numeric): Age restriction for the video (years)
1306 • live_status (string): One of "is_live", "was_live", "is_upcoming",
1308 "not_live"
1309 • is_live (boolean): Whether this video is a live stream or a fixed-
1311 length video
1312 • was_live (boolean): Whether this video was originally a live stream
1314 • playable_in_embed (string): Whether this video is allowed to play in
1316 embedded players on other sites
1317 • availability (string): Whether the video is "private", "premium_on‐
1319 ly", "subscriber_only", "needs_auth", "unlisted" or "public"
1320 • start_time (numeric): Time in seconds where the reproduction should
1322 start, as specified in the URL
1323 • end_time (numeric): Time in seconds where the reproduction should
1325 end, as specified in the URL
1326 • format (string): A human-readable description of the format
1328 • format_id (string): Format code specified by --format
1330 • format_note (string): Additional info about the format
1332 • width (numeric): Width of the video
1334 • height (numeric): Height of the video
1336 • resolution (string): Textual description of width and height
1338 • tbr (numeric): Average bitrate of audio and video in KBit/s
1340 • abr (numeric): Average audio bitrate in KBit/s
1342 • acodec (string): Name of the audio codec in use
1344 • asr (numeric): Audio sampling rate in Hertz
1346 • vbr (numeric): Average video bitrate in KBit/s
1348 • fps (numeric): Frame rate
1350 • dynamic_range (string): The dynamic range of the video
1352 • stretched_ratio (float): width:height of the video's pixels, if not
1354 square
1355 • vcodec (string): Name of the video codec in use
1357 • container (string): Name of the container format
1359 • filesize (numeric): The number of bytes, if known in advance
1361 • filesize_approx (numeric): An estimate for the number of bytes
1363 • protocol (string): The protocol that will be used for the actual
1365 download
1366 • extractor (string): Name of the extractor
1368 • extractor_key (string): Key name of the extractor
1370 • epoch (numeric): Unix epoch of when the information extraction was
1372 completed
1373 • autonumber (numeric): Number that will be increased with each down‐
1375 load, starting at --autonumber-start
1376 • video_autonumber (numeric): Number that will be increased with each
1378 video
1379 • n_entries (numeric): Total number of extracted items in the playlist
1381 • playlist_id (string): Identifier of the playlist that contains the
1383 video
1384 • playlist_title (string): Name of the playlist that contains the video
1386 • playlist (string): playlist_id or playlist_title
1388 • playlist_count (numeric): Total number of items in the playlist. May
1390 not be known if entire playlist is not extracted
1391 • playlist_index (numeric): Index of the video in the playlist padded
1393 with leading zeros according the final index
1394 • playlist_autonumber (numeric): Position of the video in the playlist
1396 download queue padded with leading zeros according to the total
1397 length of the playlist
1398 • playlist_uploader (string): Full name of the playlist uploader
1400 • playlist_uploader_id (string): Nickname or id of the playlist upload‐
1402 er
1403 • webpage_url (string): A URL to the video webpage which if given to
1405 yt-dlp should allow to get the same result again
1406 • webpage_url_basename (string): The basename of the webpage URL
1408 • webpage_url_domain (string): The domain of the webpage URL
1410 • original_url (string): The URL given by the user (or same as web‐
1412 page_url for playlist entries)
1413 Available for the video that belongs to some logical chapter or sec‐
1415 tion:
1416 • chapter (string): Name or title of the chapter the video belongs to
1418 • chapter_number (numeric): Number of the chapter the video belongs to
1420 • chapter_id (string): Id of the chapter the video belongs to
1422 Available for the video that is an episode of some series or programme:
1424 • series (string): Title of the series or programme the video episode
1426 belongs to
1427 • season (string): Title of the season the video episode belongs to
1429 • season_number (numeric): Number of the season the video episode be‐
1431 longs to
1432 • season_id (string): Id of the season the video episode belongs to
1434 • episode (string): Title of the video episode
1436 • episode_number (numeric): Number of the video episode within a season
1438 • episode_id (string): Id of the video episode
1440 Available for the media that is a track or a part of a music album:
1442 • track (string): Title of the track
1444 • track_number (numeric): Number of the track within an album or a disc
1446 • track_id (string): Id of the track
1448 • artist (string): Artist(s) of the track
1450 • genre (string): Genre(s) of the track
1452 • album (string): Title of the album the track belongs to
1454 • album_type (string): Type of the album
1456 • album_artist (string): List of all artists appeared on the album
1458 • disc_number (numeric): Number of the disc or other physical medium
1460 the track belongs to
1461 • release_year (numeric): Year (YYYY) when the album was released
1463 Available only when using --download-sections and for chapter: prefix
1465 when using --split-chapters for videos with internal chapters:
1466 • section_title (string): Title of the chapter
1468 • section_number (numeric): Number of the chapter within the file
1470 • section_start (numeric): Start time of the chapter in seconds
1472 • section_end (numeric): End time of the chapter in seconds
1474 Available only when used in --print:
1476 • urls (string): The URLs of all requested formats, one in each line
1478 • filename (string): Name of the video file. Note that the actual
1480 filename may be different due to post-processing. Use --exec echo to
1481 get the name after all postprocessing is complete
1482 • formats_table (table): The video format table as printed by --list-
1484 formats
1485 • thumbnails_table (table): The thumbnail format table as printed by
1487 --list-thumbnails
1488 • subtitles_table (table): The subtitle format table as printed by
1490 --list-subs
1491 • automatic_captions_table (table): The automatic subtitle format table
1493 as printed by --list-subs
1494 Available only in --sponsorblock-chapter-title:
1496 • start_time (numeric): Start time of the chapter in seconds
1498 • end_time (numeric): End time of the chapter in seconds
1500 • categories (list): The SponsorBlock categories the chapter belongs to
1502 • category (string): The smallest SponsorBlock category the chapter be‐
1504 longs to
1505 • category_names (list): Friendly names of the categories
1507 • name (string): Friendly name of the smallest category
1509 Each aforementioned sequence when referenced in an output template will
1511 be replaced by the actual value corresponding to the sequence name.
1512 For example for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title
1513 yt-dlp test video and id BaW_jenozKc, this will result in a yt-dlp test
1514 video-BaW_jenozKc.mp4 file created in the current directory.
1515 Note that some of the sequences are not guaranteed to be present since
1517 they depend on the metadata obtained by a particular extractor. Such
1518 sequences will be replaced with placeholder value provided with --out‐
1519 put-na-placeholder (NA by default).
1520 Tip: Look at the -j output to identify which fields are available for
1522 the particular URL
1523 For numeric sequences you can use numeric related formatting
1525 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1526 formatting), for example, %(view_count)05d will result in a string with
1527 view count padded with zeros up to 5 characters, like in 00042.
1528 Output templates can also contain arbitrary hierarchical path, e.g. -o
1530 "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" which will result
1531 in downloading each video in a directory corresponding to this path
1532 template. Any missing directory will be automatically created for you.
1533 To use percent literals in an output template use %%. To output to
1535 stdout use -o -.
1536 The current default template is %(title)s [%(id)s].%(ext)s.
1538 In some cases, you don't want special characters such as 中, spaces, or
1540 &, such as when transferring the downloaded filename to a Windows sys‐
1541 tem or the filename through an 8bit-unsafe channel. In these cases,
1542 add the --restrict-filenames flag to get a shorter title.
1543 Output template examples
1545 $ yt-dlp --get-filename -o "test video.%(ext)s" BaW_jenozKc
1546 test video.webm # Literal name with correct extension
1547 $ yt-dlp --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
1549 youtube-dl test video ''_ä↭𝕐.webm # All kinds of weird characters
1550 $ yt-dlp --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
1552 youtube-dl_test_video_.webm # Restricted file name
1553 # Download YouTube playlist videos in separate directory indexed by video order in a playlist
1555 $ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1556 # Download YouTube playlist videos in separate directories according to their uploaded year
1558 $ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1559 # Prefix playlist index with " - " separator, but only if it is available
1561 $ yt-dlp -o '%(playlist_index|)s%(playlist_index& - |)s%(title)s.%(ext)s' BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1562 # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
1564 $ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1565 # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
1567 $ yt-dlp -u user -p password -P "~/MyVideos" -o "%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s" "https://www.udemy.com/java-tutorial"
1568 # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
1570 $ yt-dlp -P "C:/MyVideos" -o "%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" "https://videomore.ru/kino_v_detalayah/5_sezon/367617"
1571 # Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
1573 # and put all temporary files in "C:\MyVideos\tmp"
1574 $ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs
1575 # Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
1577 $ yt-dlp -P "C:/MyVideos" -o "%(uploader)s/%(title)s.%(ext)s" -o "subtitle:%(uploader)s/subs/%(title)s.%(ext)s" BaW_jenozKc --write-subs
1578 # Stream the video being downloaded to stdout
1580 $ yt-dlp -o - BaW_jenozKc
1581
1583 By default, yt-dlp tries to download the best available quality if you
1584 don't pass any options. This is generally equivalent to using -f
1585 bestvideo*+bestaudio/best. However, if multiple audiostreams is en‐
1586 abled (--audio-multistreams), the default format changes to -f
1587 bestvideo+bestaudio/best. Similarly, if ffmpeg is unavailable, or if
1588 you use yt-dlp to stream to stdout (-o -), the default becomes -f
1589 best/bestvideo+bestaudio.
1590 Deprecation warning: Latest versions of yt-dlp can stream multiple for‐
1592 mats to the stdout simultaneously using ffmpeg. So, in future ver‐
1593 sions, the default for this will be set to -f bv*+ba/b similar to nor‐
1594 mal downloads. If you want to preserve the -f b/bv+ba setting, it is
1595 recommended to explicitly specify it in the configuration options.
1596 The general syntax for format selection is -f FORMAT (or --format FOR‐
1598 MAT) where FORMAT is a selector expression, i.e. an expression that
1599 describes format or formats you would like to download.
1600 The simplest case is requesting a specific format, for example with -f
1602 22 you can download the format with format code equal to 22. You can
1603 get the list of available format codes for particular video using
1604 --list-formats or -F. Note that these format codes are extractor spe‐
1605 cific.
1606 You can also use a file extension (currently 3gp, aac, flv, m4a, mp3,
1608 mp4, ogg, wav, webm are supported) to download the best quality format
1609 of a particular file extension served as a single file, e.g. -f webm
1610 will download the best quality format with the webm extension served as
1611 a single file.
1612 You can use -f - to interactively provide the format selector for each
1614 video
1615 You can also use special names to select particular edge case formats:
1617 • all: Select all formats separately
1619 • mergeall: Select and merge all formats (Must be used with --audio-
1621 multistreams, --video-multistreams or both)
1622 • b*, best*: Select the best quality format that contains either a
1624 video or an audio
1625 • b, best: Select the best quality format that contains both video and
1627 audio. Equivalent to best*[vcodec!=none][acodec!=none]
1628 • bv, bestvideo: Select the best quality video-only format. Equivalent
1630 to best*[acodec=none]
1631 • bv*, bestvideo*: Select the best quality format that contains video.
1633 It may also contain audio. Equivalent to best*[vcodec!=none]
1634 • ba, bestaudio: Select the best quality audio-only format. Equivalent
1636 to best*[vcodec=none]
1637 • ba*, bestaudio*: Select the best quality format that contains audio.
1639 It may also contain video. Equivalent to best*[acodec!=none] (Do not
1640 use! (https://github.com/yt-dlp/yt-dlp/issues/979#issuecom‐
1641 ment-919629354))
1642 • w*, worst*: Select the worst quality format that contains either a
1644 video or an audio
1645 • w, worst: Select the worst quality format that contains both video
1647 and audio. Equivalent to worst*[vcodec!=none][acodec!=none]
1648 • wv, worstvideo: Select the worst quality video-only format. Equiva‐
1650 lent to worst*[acodec=none]
1651 • wv*, worstvideo*: Select the worst quality format that contains
1653 video. It may also contain audio. Equivalent to
1654 worst*[vcodec!=none]
1655 • wa, worstaudio: Select the worst quality audio-only format. Equiva‐
1657 lent to worst*[vcodec=none]
1658 • wa*, worstaudio*: Select the worst quality format that contains au‐
1660 dio. It may also contain video. Equivalent to worst*[acodec!=none]
1661 For example, to download the worst quality video-only format you can
1663 use -f worstvideo. It is however recommended not to use worst and re‐
1664 lated options. When your format selector is worst, the format which is
1665 worst in all respects is selected. Most of the time, what you actually
1666 want is the video with the smallest filesize instead. So it is gener‐
1667 ally better to use -S +size or more rigorously, -S +size,+br,+res,+fps
1668 instead of -f worst. See sorting formats for more details.
1669 You can select the n'th best format of a type by using best<type>.<n>.
1671 For example, best.2 will select the 2nd best combined format. Similar‐
1672 ly, bv*.3 will select the 3rd best format that contains a video stream.
1673 If you want to download multiple videos and they don't have the same
1675 formats available, you can specify the order of preference using slash‐
1676 es. Note that formats on the left hand side are preferred, for example
1677 -f 22/17/18 will download format 22 if it's available, otherwise it
1678 will download format 17 if it's available, otherwise it will download
1679 format 18 if it's available, otherwise it will complain that no suit‐
1680 able formats are available for download.
1681 If you want to download several formats of the same video use a comma
1683 as a separator, e.g. -f 22,17,18 will download all these three for‐
1684 mats, of course if they are available. Or a more sophisticated example
1685 combined with the precedence feature: -f
1686 136/137/mp4/bestvideo,140/m4a/bestaudio.
1687 You can merge the video and audio of multiple formats into a single
1689 file using -f <format1>+<format2>+... (requires ffmpeg installed), for
1690 example -f bestvideo+bestaudio will download the best video-only for‐
1691 mat, the best audio-only format and mux them together with ffmpeg.
1692 Deprecation warning: Since the below described behavior is complex and
1694 counter-intuitive, this will be removed and multistreams will be en‐
1695 abled by default in the future. A new operator will be instead added
1696 to limit formats to single audio/video
1697 Unless --video-multistreams is used, all formats with a video stream
1699 except the first one are ignored. Similarly, unless --audio-multi‐
1700 streams is used, all formats with an audio stream except the first one
1701 are ignored. For example, -f bestvideo+best+bestaudio --video-multi‐
1702 streams --audio-multistreams will download and merge all 3 given for‐
1703 mats. The resulting file will have 2 video streams and 2 audio
1704 streams. But -f bestvideo+best+bestaudio --no-video-multistreams will
1705 download and merge only bestvideo and bestaudio. best is ignored since
1706 another format containing a video stream (bestvideo) has already been
1707 selected. The order of the formats is therefore important. -f
1708 best+bestaudio --no-audio-multistreams will download and merge both
1709 formats while -f bestaudio+best --no-audio-multistreams will ignore
1710 best and download only bestaudio.
1711 Filtering Formats
1713 You can also filter the video formats by putting a condition in brack‐
1714 ets, as in -f "best[height=720]" (or -f "[filesize>10M]").
1715 The following numeric meta fields can be used with comparisons <, <=,
1717 >, >=, = (equals), != (not equals):
1718 • filesize: The number of bytes, if known in advance
1720 • width: Width of the video, if known
1722 • height: Height of the video, if known
1724 • tbr: Average bitrate of audio and video in KBit/s
1726 • abr: Average audio bitrate in KBit/s
1728 • vbr: Average video bitrate in KBit/s
1730 • asr: Audio sampling rate in Hertz
1732 • fps: Frame rate
1734 Also filtering work for comparisons = (equals), ^= (starts with), $=
1736 (ends with), *= (contains), ~= (matches regex) and following string
1737 meta fields:
1738 • ext: File extension
1740 • acodec: Name of the audio codec in use
1742 • vcodec: Name of the video codec in use
1744 • container: Name of the container format
1746 • protocol: The protocol that will be used for the actual download,
1748 lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, ism,
1749 http_dash_segments, m3u8, or m3u8_native)
1750 • format_id: A short description of the format
1752 • language: Language code
1754 Any string comparison may be prefixed with negation ! in order to pro‐
1756 duce an opposite comparison, e.g. !*= (does not contain). The compar‐
1757 and of a string comparison needs to be quoted with either double or
1758 single quotes if it contains spaces or special characters other than
1759 ._-.
1760 Note that none of the aforementioned meta fields are guaranteed to be
1762 present since this solely depends on the metadata obtained by particu‐
1763 lar extractor, i.e. the metadata offered by the website. Any other
1764 field made available by the extractor can also be used for filtering.
1765 Formats for which the value is not known are excluded unless you put a
1767 question mark (?) after the operator. You can combine format filters,
1768 so -f "[height<=?720][tbr>500]" selects up to 720p videos (or videos
1769 where the height is not known) with a bitrate of at least 500 KBit/s.
1770 You can also use the filters with all to download all formats that sat‐
1771 isfy the filter. For example, -f "all[vcodec=none]" selects all audio-
1772 only formats.
1773 Format selectors can also be grouped using parentheses, for example if
1775 you want to download the best pre-merged mp4 and webm formats with a
1776 height lower than 480 you can use -f "(mp4,webm)[height<480]".
1777 Sorting Formats
1779 You can change the criteria for being considered the best by using -S
1780 (--format-sort). The general format for this is --format-sort
1781 field1,field2....
1782 The available fields are:
1784 • hasvid: Gives priority to formats that has a video stream
1786 • hasaud: Gives priority to formats that has a audio stream
1788 • ie_pref: The format preference
1790 • lang: The language preference
1792 • quality: The quality of the format
1794 • source: The preference of the source
1796 • proto: Protocol used for download (https/ftps > http/ftp > m3u8_na‐
1798 tive/m3u8 > http_dash_segments> websocket_frag > mms/rtsp > f4f/f4m)
1799 • vcodec: Video Codec (av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 >
1801 theora > other)
1802 • acodec: Audio Codec (flac/alac > wav/aiff > opus > vorbis > aac >
1804 mp4a > mp3 > eac3 > ac3 > dts > other)
1805 • codec: Equivalent to vcodec,acodec
1807 • vext: Video Extension (mp4 > webm > flv > other). If --prefer-free-
1809 formats is used, webm is preferred.
1810 • aext: Audio Extension (m4a > aac > mp3 > ogg > opus > webm > other).
1812 If --prefer-free-formats is used, the order changes to opus > ogg >
1813 webm > m4a > mp3 > aac.
1814 • ext: Equivalent to vext,aext
1816 • filesize: Exact filesize, if known in advance
1818 • fs_approx: Approximate filesize calculated from the manifests
1820 • size: Exact filesize if available, otherwise approximate filesize
1822 • height: Height of video
1824 • width: Width of video
1826 • res: Video resolution, calculated as the smallest dimension.
1828 • fps: Framerate of video
1830 • hdr: The dynamic range of the video (DV > HDR12 > HDR10+ > HDR10 >
1832 HLG > SDR)
1833 • tbr: Total average bitrate in KBit/s
1835 • vbr: Average video bitrate in KBit/s
1837 • abr: Average audio bitrate in KBit/s
1839 • br: Equivalent to using tbr,vbr,abr
1841 • asr: Audio sample rate in Hz
1843 Deprecation warning: Many of these fields have (currently undocumented)
1845 aliases, that may be removed in a future version. It is recommended to
1846 use only the documented field names.
1847 All fields, unless specified otherwise, are sorted in descending order.
1849 To reverse this, prefix the field with a +. Eg: +res prefers format
1850 with the smallest resolution. Additionally, you can suffix a preferred
1851 value for the fields, separated by a :. Eg: res:720 prefers larger
1852 videos, but no larger than 720p and the smallest video if there are no
1853 videos less than 720p. For codec and ext, you can provide two pre‐
1854 ferred values, the first for video and the second for audio. Eg:
1855 +codec:avc:m4a (equivalent to +vcodec:avc,+acodec:m4a) sets the video
1856 codec preference to h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 >
1857 theora and audio codec preference to mp4a > aac > vorbis > opus > mp3 >
1858 ac3 > dts. You can also make the sorting prefer the nearest values to
1859 the provided by using ~ as the delimiter. Eg: filesize~1G prefers the
1860 format with filesize closest to 1 GiB.
1861 The fields hasvid and ie_pref are always given highest priority in
1863 sorting, irrespective of the user-defined order. This behaviour can be
1864 changed by using --format-sort-force. Apart from these, the default
1865 order used is: lang,quality,res,fps,hdr:12,codec:vp9.2,size,br,asr,pro‐
1866 to,ext,hasaud,source,id. The extractors may override this default or‐
1867 der, but they cannot override the user-provided order.
1868 Note that the default has codec:vp9.2; i.e. av1 is not preferred.
1870 Similarly, the default for hdr is hdr:12; i.e. dolby vision is not
1871 preferred. These choices are made since DV and AV1 formats are not yet
1872 fully compatible with most devices. This may be changed in the future
1873 as more devices become capable of smoothly playing back these formats.
1874 If your format selector is worst, the last item is selected after sort‐
1876 ing. This means it will select the format that is worst in all re‐
1877 spects. Most of the time, what you actually want is the video with the
1878 smallest filesize instead. So it is generally better to use -f best -S
1879 +size,+br,+res,+fps.
1880 Tip: You can use the -v -F to see how the formats have been sorted
1882 (worst to best).
1883 Format Selection examples
1885 # Download and merge the best video-only format and the best audio-only format,
1886 # or download the best combined format if video-only format is not available
1887 $ yt-dlp -f "bv+ba/b"
1888 # Download best format that contains video,
1890 # and if it doesn't already have an audio stream, merge it with best audio-only format
1891 $ yt-dlp -f "bv*+ba/b"
1892 # Same as above
1894 $ yt-dlp
1895 # Download the best video-only format and the best audio-only format without merging them
1897 # For this case, an output template should be used since
1898 # by default, bestvideo and bestaudio will have the same file name.
1899 $ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"
1900 # Download and merge the best format that has a video stream,
1902 # and all audio-only formats into one file
1903 $ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams
1904 # Download and merge the best format that has a video stream,
1906 # and the best 2 audio-only formats into one file
1907 $ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams
1908 # The following examples show the old method (without -S) of format selection
1911 # and how to use -S to achieve a similar but (generally) better result
1912 # Download the worst video available (old method)
1914 $ yt-dlp -f "wv*+wa/w"
1915 # Download the best video available but with the smallest resolution
1917 $ yt-dlp -S "+res"
1918 # Download the smallest video available
1920 $ yt-dlp -S "+size,+br"
1921 # Download the best mp4 video available, or the best video if no mp4 available
1925 $ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"
1926 # Download the best video with the best extension
1928 # (For video, mp4 > webm > flv. For audio, m4a > aac > mp3 ...)
1929 $ yt-dlp -S "ext"
1930 # Download the best video available but no better than 480p,
1934 # or the worst video if there is no video under 480p
1935 $ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"
1936 # Download the best video available with the largest height but no better than 480p,
1938 # or the best video with the smallest resolution if there is no video under 480p
1939 $ yt-dlp -S "height:480"
1940 # Download the best video available with the largest resolution but no better than 480p,
1942 # or the best video with the smallest resolution if there is no video under 480p
1943 # Resolution is determined by using the smallest dimension.
1944 # So this works correctly for vertical videos as well
1945 $ yt-dlp -S "res:480"
1946 # Download the best video (that also has audio) but no bigger than 50 MB,
1950 # or the worst video (that also has audio) if there is no video under 50 MB
1951 $ yt-dlp -f "b[filesize<50M] / w"
1952 # Download largest video (that also has audio) but no bigger than 50 MB,
1954 # or the smallest video (that also has audio) if there is no video under 50 MB
1955 $ yt-dlp -f "b" -S "filesize:50M"
1956 # Download best video (that also has audio) that is closest in size to 50 MB
1958 $ yt-dlp -f "b" -S "filesize~50M"
1959 # Download best video available via direct link over HTTP/HTTPS protocol,
1963 # or the best video available via any protocol if there is no such video
1964 $ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"
1965 # Download best video available via the best protocol
1967 # (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
1968 $ yt-dlp -S "proto"
1969 # Download the best video with either h264 or h265 codec,
1973 # or the best video if there is no such video
1974 $ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"
1975 # Download the best video with best codec no better than h264,
1977 # or the best video with worst codec if there is no such video
1978 $ yt-dlp -S "codec:h264"
1979 # Download the best video with worst codec no worse than h264,
1981 # or the best video with best codec if there is no such video
1982 $ yt-dlp -S "+codec:h264"
1983 # More complex examples
1987 # Download the best video no better than 720p preferring framerate greater than 30,
1989 # or the worst video (still preferring framerate greater than 30) if there is no such video
1990 $ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"
1991 # Download the video with the largest resolution no better than 720p,
1993 # or the video with the smallest resolution available if there is no such video,
1994 # preferring larger framerate for formats with the same resolution
1995 $ yt-dlp -S "res:720,fps"
1996 # Download the video with smallest resolution no worse than 480p,
2000 # or the video with the largest resolution available if there is no such video,
2001 # preferring better codec and then larger total bitrate for the same resolution
2002 $ yt-dlp -S "+res:480,codec,br"
2003
2005 The metadata obtained by the extractors can be modified by using
2006 --parse-metadata and --replace-in-metadata
2007 --replace-in-metadata FIELDS REGEX REPLACE is used to replace text in
2009 any metadata field using python regular expression
2010 (https://docs.python.org/3/library/re.html#regular-expression-syntax).
2011 Backreferences (https://docs.python.org/3/library/re.html?high‐
2012 light=backreferences#re.sub) can be used in the replace string for ad‐
2013 vanced use.
2014 The general syntax of --parse-metadata FROM:TO is to give the name of a
2016 field or an output template to extract data from, and the format to in‐
2017 terpret it as, separated by a colon :. Either a python regular expres‐
2018 sion (https://docs.python.org/3/library/re.html#regular-expression-syn‐
2019 tax) with named capture groups or a similar syntax to the output tem‐
2020 plate (only %(field)s formatting is supported) can be used for TO. The
2021 option can be used multiple times to parse and modify various fields.
2022 Note that any field created by this can be used in the output template
2024 and will also affect the media file's metadata added when using --add-
2025 metadata.
2026 This option also has a few special uses:
2028 • You can download an additional URL based on the metadata of the cur‐
2030 rently downloaded video. To do this, set the field additional_urls
2031 to the URL that you want to download. Eg: --parse-metadata "descrip‐
2032 tion:(?P<additional_urls>https?://www\.vimeo\.com/\d+) will download
2033 the first vimeo video found in the description
2034 • You can use this to change the metadata that is embedded in the media
2036 file. To do this, set the value of the corresponding field with a
2037 meta_ prefix. For example, any value you set to meta_description
2038 field will be added to the description field in the file. For exam‐
2039 ple, you can use this to set a different "description" and "synop‐
2040 sis". To modify the metadata of individual streams, use the meta<n>_
2041 prefix (Eg: meta1_language). Any value set to the meta_ field will
2042 overwrite all default values.
2043 Note: Metadata modification happens before format selection, post-ex‐
2045 traction and other post-processing operations. Some fields may be
2046 added or changed during these steps, overriding your changes.
2047 For reference, these are the fields yt-dlp adds by default to the file
2049 metadata:
2050 Metadata fields From
2052 ─────────────────────────────────────────────────────
2053 title track or title
2054 date upload_date
2055 description, synopsis description
2056 purl, comment webpage_url
2057 track track_number
2058 artist artist, creator, uploader
2059 or uploader_id
2060 genre genre
2061 album album
2062 album_artist album_artist
2064 disc disc_number
2065 show series
2066 season_number season_number
2067 episode_id episode or episode_id
2068 episode_sort episode_number
2069 language of each stream the format's language
2070 Note: The file format may not support some of these fields
2072 Modifying metadata examples
2074 # Interpret the title as "Artist - Title"
2075 $ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"
2076 # Regex example
2078 $ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"
2079 # Set title as "Series name S01E05"
2081 $ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"
2082 # Prioritize uploader as the "artist" field in video metadata
2084 $ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --add-metadata
2085 # Set "comment" field in video metadata using description instead of webpage_url,
2087 # handling multiple lines correctly
2088 $ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --add-metadata
2089 # Do not set any "synopsis" in the video metadata
2091 $ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"
2092 # Remove "formats" field from the infojson by setting it to an empty string
2094 $ yt-dlp --parse-metadata ":(?P<formats>)" -j
2095 # Replace all spaces and "_" in title and uploader with a `-`
2097 $ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"
2098
2100 Some extractors accept additional arguments which can be passed using
2101 --extractor-args KEY:ARGS. ARGS is a ; (semicolon) separated string of
2102 ARG=VAL1,VAL2. Eg: --extractor-args "youtube:player-client=android_em‐
2103 bedded,web;include_live_dash" --extractor-args "funimation:version=un‐
2104 cut"
2105 The following extractors use this feature:
2107 youtube
2109 • skip: One or more of hls, dash or translated_subs to skip extraction
2110 of the m3u8 manifests, dash manifests and auto-translated subtitles
2111 (https://github.com/yt-dlp/yt-dlp/issues/4090#issuecom‐
2112 ment-1158102032) respectively
2113 • player_client: Clients to extract video data from. The main clients
2115 are web, android and ios with variants _music, _embedded, _embed‐
2116 screen, _creator (Eg: web_embedded); and mweb and tv_embedded (age‐
2117 gate bypass) with no variants. By default, android,web is used, but
2118 tv_embedded and creator variants are added as required for age-gated
2119 videos. Similarly the music variants are added for music.youtube.com
2120 urls. You can use all to use all the clients, and default for the
2121 default clients.
2122 • player_skip: Skip some network requests that are generally needed for
2124 robust extraction. One or more of configs (skip client configs),
2125 webpage (skip initial webpage), js (skip js player). While these op‐
2126 tions can help reduce the number of requests needed or avoid some
2127 rate-limiting, they could cause some issues. See #860
2128 (https://github.com/yt-dlp/yt-dlp/pull/860) for more details
2129 • include_live_dash: Include live dash formats even without --live-
2131 from-start (These formats don't download properly)
2132 • comment_sort: top or new (default) - choose comment sorting mode (on
2134 YouTube's side)
2135 • max_comments: Limit the amount of comments to gather. Comma-separat‐
2137 ed list of integers representing max-comments,max-parents,max-
2138 replies,max-replies-per-thread. Default is all,all,all,all
2139 • E.g. all,all,1000,10 will get a maximum of 1000 replies total,
2141 with up to 10 replies per thread. 1000,all,100 will get a maximum
2142 of 1000 comments, with a maximum of 100 replies total
2143 • innertube_host: Innertube API host to use for all API requests
2145 • e.g. studio.youtube.com, youtubei.googleapis.com
2147 • Note: Cookies exported from www.youtube.com will not work with
2149 hosts other than *.youtube.com
2150 • innertube_key: Innertube API key to use for all API requests
2152 youtubetab (YouTube playlists, channels, feeds, etc.)
2154 • skip: One or more of webpage (skip initial webpage download), au‐
2155 thcheck (allow the download of playlists requiring authentication
2156 when no initial webpage is downloaded. This may cause unwanted be‐
2157 havior, see #1122 (https://github.com/yt-dlp/yt-dlp/pull/1122) for
2158 more details)
2159 • approximate_date: Extract approximate upload_date in flat-playlist.
2161 This may cause date-based filters to be slightly off
2162 funimation
2164 • language: Languages to extract. Eg: funimation:language=english,ja‐
2165 panese
2166 • version: The video version to extract - uncut or simulcast
2168 crunchyroll
2170 • language: Languages to extract. Eg: crunchyroll:language=jaJp
2171 • hardsub: Which hard-sub versions to extract. Eg: crunchyroll:hard‐
2173 sub=None,enUS
2174 crunchyrollbeta
2176 • format: Which stream type(s) to extract. Default is adaptive_hls Eg:
2177 crunchyrollbeta:format=vo_adaptive_hls
2178 • Potentially useful values include adaptive_hls, adaptive_dash,
2180 vo_adaptive_hls, vo_adaptive_dash, download_hls, trailer_hls,
2181 trailer_dash
2182 • hardsub: Preference order for which hardsub versions to extract. De‐
2184 fault is None (no hardsubs). Eg: crunchyrollbeta:hardsub=en-US,None
2185 vikichannel
2187 • video_types: Types of videos to download - one or more of episodes,
2188 movies, clips, trailers
2189 niconico
2191 • segment_duration: Segment duration in milliseconds for HLS-DMC for‐
2192 mats. Use it at your own risk since this feature may result in your
2193 account termination.
2194 youtubewebarchive
2196 • check_all: Try to check more at the cost of more requests. One or
2197 more of thumbnails, captures
2198 gamejolt
2200 • comment_sort: hot (default), you (cookies needed), top, new - choose
2201 comment sorting mode (on GameJolt's side)
2202 hotstar
2204 • res: resolution to ignore - one or more of sd, hd, fhd
2205 • vcodec: vcodec to ignore - one or more of h264, h265, dvh265
2207 • dr: dynamic range to ignore - one or more of sdr, hdr10, dv
2209 tiktok
2211 • app_version: App version to call mobile APIs with - should be set
2212 along with manifest_app_version. (e.g. 20.2.1)
2213 • manifest_app_version: Numeric app version to call mobile APIs with.
2215 (e.g. 221)
2216 rokfinchannel
2218 • tab: Which tab to download. One of new, top, videos, podcasts,
2219 streams, stacks. (E.g. rokfinchannel:tab=streams)
2220 NOTE: These options may be changed/removed in the future without con‐
2222 cern for backward compatibility
2223
2225 You can install yt-dlp using one of the following methods:
2226 Using the release binary
2228 You can simply download the correct binary file for your OS
2229 Note: The manpages, shell completion files etc. are available in the
2231 source tarball (https://github.com/yt-dlp/yt-dlp/releases/latest/down‐
2232 load/yt-dlp.tar.gz)
2233 In UNIX-like OSes (MacOS, Linux, BSD), you can also install the same in
2235 one of the following ways:
2236 sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
2238 sudo chmod a+rx /usr/local/bin/yt-dlp
2239 sudo wget https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -O /usr/local/bin/yt-dlp
2241 sudo chmod a+rx /usr/local/bin/yt-dlp
2242 sudo aria2c https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp --dir /usr/local/bin -o yt-dlp
2244 sudo chmod a+rx /usr/local/bin/yt-dlp
2245 With PIP (https://pypi.org/project/pip)
2247 You can install the PyPI package (https://pypi.org/project/yt-dlp)
2248 with:
2249 python3 -m pip install -U yt-dlp
2251 You can install without any of the optional dependencies using:
2253 python3 -m pip install --no-deps -U yt-dlp
2255 If you want to be on the cutting edge, you can also install the master
2257 branch with:
2258 python3 -m pip install --force-reinstall https://github.com/yt-dlp/yt-dlp/archive/master.tar.gz
2260 On some systems, you may need to use py or python instead of python3
2262 With Homebrew (https://brew.sh)
2264 macOS or Linux users that are using Homebrew can also install it by:
2265 brew install yt-dlp/taps/yt-dlp
2267 UPDATE
2269 You can use yt-dlp -U to update if you are using the provided release
2270 If you installed with pip, simply re-run the same command that was used
2272 to install the program
2273 If you installed using Homebrew, run brew upgrade yt-dlp/taps/yt-dlp
2275 DEPENDENCIES
2277 Python versions 3.7+ (CPython and PyPy) are supported. Other versions
2278 and implementations may or may not work correctly.
2279 While all the other dependencies are optional, ffmpeg and ffprobe are
2281 highly recommended
2282 Strongly recommended
2284 • ffmpeg and ffprobe (https://www.ffmpeg.org) - Required for merging
2285 separate video and audio files as well as for various post-processing
2286 tasks. License depends on the build (https://www.ffmpeg.org/le‐
2287 gal.html)
2288 Note: There are some regressions in newer ffmpeg versions that causes
2290 various issues when used alongside yt-dlp. Since ffmpeg is such an
2291 important dependency, we provide custom builds
2292 (https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-static-auto-builds)
2293 with patches for these issues at yt-dlp/FFmpeg-Builds
2294 (https://github.com/yt-dlp/FFmpeg-Builds). See the readme
2295 (https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for details
2296 on the specific issues solved by these builds
2297 Networking
2299 • certifi (https://github.com/certifi/python-certifi)* - Provides
2300 Mozilla's root certificate bundle. Licensed under MPLv2
2301 (https://github.com/certifi/python-certifi/blob/master/LICENSE)
2302 • brotli (https://github.com/google/brotli)* or brotlicffi
2304 (https://github.com/python-hyper/brotlicffi) - Brotli
2305 (https://en.wikipedia.org/wiki/Brotli) content encoding support.
2306 Both licensed under MIT 1 (https://github.com/google/brotli/blob/mas‐
2307 ter/LICENSE) 2 (https://github.com/python-hyper/brotlicffi/blob/mas‐
2308 ter/LICENSE)
2309 • websockets (https://github.com/aaugustin/websockets)* - For download‐
2311 ing over websocket. Licensed under BSD-3-Clause
2312 (https://github.com/aaugustin/websockets/blob/main/LICENSE)
2313 Metadata
2315 • mutagen (https://github.com/quodlibet/mutagen)* - For --embed-thumb‐
2316 nail in certain formats. Licensed under GPLv2+
2317 (https://github.com/quodlibet/mutagen/blob/master/COPYING)
2318 • AtomicParsley (https://github.com/wez/atomicparsley) - For --embed-
2320 thumbnail in mp4/m4a files when mutagen/ffmpeg cannot. Licensed un‐
2321 der GPLv2+ (https://github.com/wez/atomicparsley/blob/master/COPYING)
2322 • xattr (https://github.com/xattr/xattr), pyxattr
2324 (https://github.com/iustin/pyxattr) or setfattr (http://savan‐
2325 nah.nongnu.org/projects/attr) - For writing xattr metadata (--xattr)
2326 on Linux. Licensed under MIT (https://github.com/xattr/xat‐
2327 tr/blob/master/LICENSE.txt), LGPL2.1 (https://github.com/iustin/pyx‐
2328 attr/blob/master/COPYING) and GPLv2+ (http://git.savan‐
2329 nah.nongnu.org/cgit/attr.git/tree/doc/COPYING) respectively
2330 Misc
2332 • pycryptodomex (https://github.com/Legrandin/pycryptodome)* - For de‐
2333 crypting AES-128 HLS streams and various other data. Licensed under
2334 BSD-2-Clause (https://github.com/Legrandin/pycryptodome/blob/mas‐
2335 ter/LICENSE.rst)
2336 • phantomjs (https://github.com/ariya/phantomjs) - Used in extractors
2338 where javascript needs to be run. Licensed under BSD-3-Clause
2339 (https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
2340 • secretstorage (https://github.com/mitya57/secretstorage) - For
2342 --cookies-from-browser to access the Gnome keyring while decrypting
2343 cookies of Chromium-based browsers on Linux. Licensed under
2344 BSD-3-Clause (https://github.com/mitya57/secretstorage/blob/mas‐
2345 ter/LICENSE)
2346 • Any external downloader that you want to use with --downloader
2348 Deprecated
2350 • avconv and avprobe (https://www.libav.org) - Now deprecated alterna‐
2351 tive to ffmpeg. License depends on the build (https://libav.org/le‐
2352 gal)
2353 • sponskrub (https://github.com/faissaloo/SponSkrub) - For using the
2355 now deprecated sponskrub options. Licensed under GPLv3+
2356 (https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
2357 • rtmpdump (http://rtmpdump.mplayerhq.hu) - For downloading rtmp
2359 streams. ffmpeg can be used instead with --downloader ffmpeg. Li‐
2360 censed under GPLv2+ (http://rtmpdump.mplayerhq.hu)
2361 • mplayer (http://mplayerhq.hu/design7/info.html) or mpv
2363 (https://mpv.io) - For downloading rstp/mms streams. ffmpeg can be
2364 used instead with --downloader ffmpeg. Licensed under GPLv2+
2365 (https://github.com/mpv-player/mpv/blob/master/Copyright)
2366 To use or redistribute the dependencies, you must agree to their re‐
2368 spective licensing terms.
2369 The Windows and MacOS standalone release binaries are built with the
2371 Python interpreter and the packages marked with * included.
2372 If you do not have the necessary dependencies for a task you are at‐
2374 tempting, yt-dlp will warn you. All the currently available dependen‐
2375 cies are visible at the top of the --verbose output
2376 COMPILE
2378 Standalone PyInstaller Builds
2379 To build the Windows/MacOS executable, you must have Python and pyin‐
2380 staller (plus any of yt-dlp's optional dependencies if needed). Once
2381 you have all the necessary dependencies installed, simply run
2382 pyinst.py. The executable will be built for the same architecture
2383 (32/64 bit) as the Python used.
2384 python3 -m pip install -U pyinstaller -r requirements.txt
2386 python3 devscripts/make_lazy_extractors.py
2387 python3 pyinst.py
2388 On some systems, you may need to use py or python instead of python3.
2390 Note that pyinstaller does not support (https://github.com/pyin‐
2392 staller/pyinstaller#requirements-and-tested-platforms) Python installed
2393 from the Windows store without using a virtual environment.
2394 Important: Running pyinstaller directly without using pyinst.py is not
2396 officially supported. This may or may not work correctly.
2397 Platform-independent Binary (UNIX)
2399 You will need the build tools python (3.6+), zip, make (GNU), pandoc*
2400 and pytest*.
2401 After installing these, simply run make.
2403 You can also run make yt-dlp instead to compile only the binary without
2405 updating any of the additional files. (The dependencies marked with *
2406 are not needed for this)
2407 Standalone Py2Exe Builds (Windows)
2409 While we provide the option to build with py2exe
2410 (https://www.py2exe.org), it is recommended to build using PyInstaller
2411 instead since the py2exe builds cannot contain pycryptodomex/certifi
2412 and needs VC++14 on the target computer to run.
2413 If you wish to build it anyway, install Python and py2exe, and then
2415 simply run setup.py py2exe
2416 py -m pip install -U py2exe -r requirements.txt
2418 py devscripts/make_lazy_extractors.py
2419 py setup.py py2exe
2420 Related scripts
2422 • devscripts/update-version.py - Update the version number based on
2423 current timestamp
2424 • devscripts/make_lazy_extractors.py - Create lazy extractors. Running
2426 this before building the binaries (any variant) will improve their
2427 startup performance. Set the environment variable YTDLP_NO_LAZY_EX‐
2428 TRACTORS=1 if you wish to forcefully disable lazy extractor loading.
2429 You can also fork the project on github and run your fork's build work‐
2431 flow to automatically build a full release
2432
2434 Plugins are loaded from <root-dir>/ytdlp_plugins/<type>/__init__.py;
2435 where <root-dir> is the directory of the binary (<root-dir>/yt-dlp), or
2436 the root directory of the module if you are running directly from
2437 source-code (<root dir>/yt_dlp/__main__.py). Plugins are currently not
2438 supported for the pip version
2439 Plugins can be of <type>s extractor or postprocessor. Extractor plug‐
2441 ins do not need to be enabled from the CLI and are automatically in‐
2442 voked when the input URL is suitable for it. Postprocessor plugins can
2443 be invoked using --use-postprocessor NAME.
2444 See ytdlp_plugins for example plugins.
2446 Note that all plugins are imported even if not invoked, and that there
2448 are no checks performed on plugin code. Use plugins at your own risk
2449 and only if you trust the code
2450 If you are a plugin author, add ytdlp-plugins (https://github.com/top‐
2452 ics/ytdlp-plugins) as a topic to your repository for discoverability
2453
2455 yt-dlp makes the best effort to be a good command-line program, and
2456 thus should be callable from any programming language.
2457 Your program should avoid parsing the normal stdout since they may
2459 change in future versions. Instead they should use options such as -J,
2460 --print, --progress-template, --exec etc to create console output that
2461 you can reliably reproduce and parse.
2462 From a Python program, you can embed yt-dlp in a more powerful fashion,
2464 like this:
2465 from yt_dlp import YoutubeDL
2467 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2469 with YoutubeDL() as ydl:
2470 ydl.download(URLS)
2471 Most likely, you'll want to use various options. For a list of options
2473 available, have a look at yt_dlp/YoutubeDL.py.
2474 Tip: If you are porting your code from youtube-dl to yt-dlp, one impor‐
2476 tant point to look out for is that we do not guarantee the return value
2477 of YoutubeDL.extract_info to be json serializable, or even be a dictio‐
2478 nary. It will be dictionary-like, but if you want to ensure it is a
2479 serializable dictionary, pass it through YoutubeDL.sanitize_info as
2480 shown in the example below
2481 Embedding examples
2483 Extracting information
2484 import json
2485 import yt_dlp
2486 URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'
2488 # ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
2490 ydl_opts = {}
2491 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2492 info = ydl.extract_info(URL, download=False)
2493 # ℹ️ ydl.sanitize_info makes the info json-serializable
2495 print(json.dumps(ydl.sanitize_info(info)))
2496 Download using an info-json
2498 import yt_dlp
2499 INFO_FILE = 'path/to/video.info.json'
2501 with yt_dlp.YoutubeDL() as ydl:
2503 error_code = ydl.download_with_info_file(INFO_FILE)
2504 print('Some videos failed to download' if error_code
2506 else 'All videos successfully downloaded')
2507 Extract audio
2509 import yt_dlp
2510 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2512 ydl_opts = {
2514 'format': 'm4a/bestaudio/best',
2515 # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
2516 'postprocessors': [{ # Extract audio using ffmpeg
2517 'key': 'FFmpegExtractAudio',
2518 'preferredcodec': 'm4a',
2519 }]
2520 }
2521 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2523 error_code = ydl.download(URLS)
2524 Filter videos
2526 import yt_dlp
2527 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2529 def longer_than_a_minute(info, *, incomplete):
2531 """Download only videos longer than a minute (or with unknown duration)"""
2532 duration = info.get('duration')
2533 if duration and duration < 60:
2534 return 'The video is too short'
2535 ydl_opts = {
2537 'match_filter': longer_than_a_minute,
2538 }
2539 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2541 error_code = ydl.download(URLS)
2542 Adding logger and progress hook
2544 import yt_dlp
2545 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2547 class MyLogger:
2549 def debug(self, msg):
2550 # For compatibility with youtube-dl, both debug and info are passed into debug
2551 # You can distinguish them by the prefix '[debug] '
2552 if msg.startswith('[debug] '):
2553 pass
2554 else:
2555 self.info(msg)
2556 def info(self, msg):
2558 pass
2559 def warning(self, msg):
2561 pass
2562 def error(self, msg):
2564 print(msg)
2565 # ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
2568 def my_hook(d):
2569 if d['status'] == 'finished':
2570 print('Done downloading, now post-processing ...')
2571 ydl_opts = {
2574 'logger': MyLogger(),
2575 'progress_hooks': [my_hook],
2576 }
2577 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2579 ydl.download(URLS)
2580 Add a custom PostProcessor
2582 import yt_dlp
2583 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2585 # ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
2587 class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
2588 def run(self, info):
2589 self.to_screen('Doing stuff')
2590 return [], info
2591 with yt_dlp.YoutubeDL() as ydl:
2594 # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
2595 ydl.add_post_processor(MyCustomPP(), when='pre_process')
2596 ydl.download(URLS)
2597 Use a custom format selector
2599 import yt_dlp
2600 URL = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2602 def format_selector(ctx):
2604 """ Select the best video and the best audio that won't result in an mkv.
2605 NOTE: This is just an example and does not handle all cases """
2606 # formats are already sorted worst to best
2608 formats = ctx.get('formats')[::-1]
2609 # acodec='none' means there is no audio
2611 best_video = next(f for f in formats
2612 if f['vcodec'] != 'none' and f['acodec'] == 'none')
2613 # find compatible audio extension
2615 audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
2616 # vcodec='none' means there is no video
2617 best_audio = next(f for f in formats if (
2618 f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))
2619 # These are the minimum required fields for a merged format
2621 yield {
2622 'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
2623 'ext': best_video['ext'],
2624 'requested_formats': [best_video, best_audio],
2625 # Must be + separated list of protocols
2626 'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
2627 }
2628 ydl_opts = {
2631 'format': format_selector,
2632 }
2633 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2635 ydl.download(URLS)
2636
2638 • Merged with youtube-dl v2021.12.17+ commit/a03b977
2639 (https://github.com/ytdl-org/youtube-dl/com‐
2640 mit/a03b9775d544b06a5b4f2aa630214c7c22fc2229) and youtube-dlc
2641 v2020.11.11-3+ commit/f9401f2 (https://github.com/blackjack4494/yt-
2642 dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee): You get all the
2643 features and patches of youtube-dlc (https://github.com/black‐
2644 jack4494/yt-dlc) in addition to the latest youtube-dl
2645 (https://github.com/ytdl-org/youtube-dl)
2646 • SponsorBlock Integration: You can mark/remove sponsor sections in
2648 youtube videos by utilizing the SponsorBlock (https://spon‐
2649 sor.ajay.app) API
2650 • Format Sorting: The default format sorting options have been changed
2652 so that higher resolution and better codecs will be now preferred in‐
2653 stead of simply using larger bitrate. Furthermore, you can now spec‐
2654 ify the sort order using -S. This allows for much easier format se‐
2655 lection than what is possible by simply using --format (examples)
2656 • Merged with animelover1984/youtube-dl: You get most of the features
2658 and improvements from animelover1984/youtube-dl
2659 (https://github.com/animelover1984/youtube-dl) including --write-com‐
2660 ments, BiliBiliSearch, BilibiliChannel, Embedding thumbnail in
2661 mp4/ogg/opus, playlist infojson etc. Note that the NicoNico
2662 livestreams are not available. See #31 (https://github.com/yt-
2663 dlp/yt-dlp/pull/31) for details.
2664 • YouTube improvements:
2666 • Supports Clips, Stories (ytstories:<channel UCID>), Search (includ‐
2668 ing filters)*, YouTube Music Search, Channel-specific search,
2669 Search prefixes (ytsearch:, ytsearchdate:)*, Mixes, YouTube Music
2670 Albums/Channels (except self-uploaded music (https://github.com/yt-
2671 dlp/yt-dlp/issues/723)), and Feeds (:ytfav, :ytwatchlater, :ytsubs,
2672 :ythistory, :ytrec, :ytnotif)
2673 • Fix for n-sig based throttling (https://github.com/ytdl-
2675 org/youtube-dl/issues/29326) *
2676 • Supports some (but not all) age-gated content without cookies
2678 • Download livestreams from the start using --live-from-start (exper‐
2680 imental)
2681 • 255kbps audio is extracted (if available) from YouTube Music when
2683 premium cookies are given
2684 • Redirect channel's home URL automatically to /video to preserve the
2686 old behaviour
2687 • Cookies from browser: Cookies can be automatically extracted from all
2689 major web browsers using --cookies-from-browser BROWS‐
2690 ER[+KEYRING][:PROFILE]
2691 • Download time range: Videos can be downloaded partially based on ei‐
2693 ther timestamps or chapters using --download-sections
2694 • Split video by chapters: Videos can be split into multiple files
2696 based on chapters using --split-chapters
2697 • Multi-threaded fragment downloads: Download multiple fragments of
2699 m3u8/mpd videos in parallel. Use --concurrent-fragments (-N) option
2700 to set the number of threads used
2701 • Aria2c with HLS/DASH: You can use aria2c as the external downloader
2703 for DASH(mpd) and HLS(m3u8) formats
2704 • New and fixed extractors: Many new extractors have been added and a
2706 lot of existing ones have been fixed. See the changelog or the list
2707 of supported sites
2708 • New MSOs: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
2710 • Subtitle extraction from manifests: Subtitles can be extracted from
2712 streaming media manifests. See commit/be6202f
2713 (https://github.com/yt-dlp/yt-dlp/com‐
2714 mit/be6202f12b97858b9d716e608394b51065d0419f) for details
2715 • Multiple paths and output templates: You can give different output
2717 templates and download paths for different types of files. You can
2718 also set a temporary path where intermediary files are downloaded to
2719 using --paths (-P)
2720 • Portable Configuration: Configuration files are automatically loaded
2722 from the home and root directories. See configuration for details
2723 • Output template improvements: Output templates can now have date-time
2725 formatting, numeric offsets, object traversal etc. See output tem‐
2726 plate for details. Even more advanced operations can also be done
2727 with the help of --parse-metadata and --replace-in-metadata
2728 • Other new options: Many new options have been added such as --alias,
2730 --print, --concat-playlist, --wait-for-video, --retry-sleep, --sleep-
2731 requests, --convert-thumbnails, --force-download-archive, --force-
2732 overwrites, --break-on-reject etc
2733 • Improvements: Regex and other operators in --format/--match-filter,
2735 multiple --postprocessor-args and --downloader-args, faster archive
2736 checking, more format selection options, merge multi-video/audio,
2737 multiple --config-locations, --exec at different stages, etc
2738 • Plugins: Extractors and PostProcessors can be loaded from an external
2740 file. See plugins for details
2741 • Self-updater: The releases can be updated using yt-dlp -U
2743 See changelog or commits (https://github.com/yt-dlp/yt-dlp/commits) for
2745 the full list of changes
2746 Features marked with a * have been back-ported to youtube-dl
2748 Differences in default behavior
2750 Some of yt-dlp's default options are different from that of youtube-dl
2751 and youtube-dlc:
2752 • The options --auto-number (-A), --title (-t) and --literal (-l), no
2754 longer work. See removed options for details
2755 • avconv is not supported as an alternative to ffmpeg
2757 • yt-dlp stores config files in slightly different locations to
2759 youtube-dl. See configuration for a list of correct locations
2760 • The default output template is %(title)s [%(id)s].%(ext)s. There is
2762 no real reason for this change. This was changed before yt-dlp was
2763 ever made public and now there are no plans to change it back to
2764 %(title)s-%(id)s.%(ext)s. Instead, you may use --compat-options
2765 filename
2766 • The default format sorting is different from youtube-dl and prefers
2768 higher resolution and better codecs rather than higher bitrates. You
2769 can use the --format-sort option to change this to any order you pre‐
2770 fer, or use --compat-options format-sort to use youtube-dl's sorting
2771 order
2772 • The default format selector is bv*+ba/b. This means that if a com‐
2774 bined video + audio format that is better than the best video-only
2775 format is found, the former will be preferred. Use -f bv+ba/b or
2776 --compat-options format-spec to revert this
2777 • Unlike youtube-dlc, yt-dlp does not allow merging multiple au‐
2779 dio/video streams into one file by default (since this conflicts with
2780 the use of -f bv*+ba). If needed, this feature must be enabled using
2781 --audio-multistreams and --video-multistreams. You can also use
2782 --compat-options multistreams to enable both
2783 • --no-abort-on-error is enabled by default. Use --abort-on-error or
2785 --compat-options abort-on-error to abort on errors instead
2786 • When writing metadata files such as thumbnails, description or infoj‐
2788 son, the same information (if available) is also written for
2789 playlists. Use --no-write-playlist-metafiles or --compat-options no-
2790 playlist-metafiles to not write these files
2791 • --add-metadata attaches the infojson to mkv files in addition to
2793 writing the metadata when used with --write-info-json. Use --no-em‐
2794 bed-info-json or --compat-options no-attach-info-json to revert this
2795 • Some metadata are embedded into different fields when using --add-
2797 metadata as compared to youtube-dl. Most notably, comment field con‐
2798 tains the webpage_url and synopsis contains the description. You can
2799 use --parse-metadata to modify this to your liking or use --compat-
2800 options embed-metadata to revert this
2801 • playlist_index behaves differently when used with options like
2803 --playlist-reverse and --playlist-items. See #302
2804 (https://github.com/yt-dlp/yt-dlp/issues/302) for details. You can
2805 use --compat-options playlist-index if you want to keep the earlier
2806 behavior
2807 • The output of -F is listed in a new format. Use --compat-options
2809 list-formats to revert this
2810 • All experiences of a funimation episode are considered as a single
2812 video. This behavior breaks existing archives. Use --compat-options
2813 seperate-video-versions to extract information from only the default
2814 player
2815 • Youtube live chat (if available) is considered as a subtitle. Use
2817 --sub-langs all,-live_chat to download all subtitles except live
2818 chat. You can also use --compat-options no-live-chat to prevent live
2819 chat from downloading
2820 • Youtube channel URLs are automatically redirected to /video. Append
2822 a /featured to the URL to download only the videos in the home page.
2823 If the channel does not have a videos tab, we try to download the
2824 equivalent UU playlist instead. For all other tabs, if the channel
2825 does not show the requested tab, an error will be raised. Also,
2826 /live URLs raise an error if there are no live videos instead of
2827 silently downloading the entire channel. You may use --compat-op‐
2828 tions no-youtube-channel-redirect to revert all these redirections
2829 • Unavailable videos are also listed for youtube playlists. Use --com‐
2831 pat-options no-youtube-unavailable-videos to remove this
2832 • If ffmpeg is used as the downloader, the downloading and merging of
2834 formats happen in a single step when possible. Use --compat-options
2835 no-direct-merge to revert this
2836 • Thumbnail embedding in mp4 is done with mutagen if possible. Use
2838 --compat-options embed-thumbnail-atomicparsley to force the use of
2839 AtomicParsley instead
2840 • Some private fields such as filenames are removed by default from the
2842 infojson. Use --no-clean-infojson or --compat-options no-clean-info‐
2843 json to revert this
2844 • When --embed-subs and --write-subs are used together, the subtitles
2846 are written to disk and also embedded in the media file. You can use
2847 just --embed-subs to embed the subs and automatically delete the sep‐
2848 arate file. See #630 (comment) (https://github.com/yt-dlp/yt-dlp/is‐
2849 sues/630#issuecomment-893659460) for more info. --compat-options no-
2850 keep-subs can be used to revert this
2851 • certifi will be used for SSL root certificates, if installed. If you
2853 want to use only system certificates, use --compat-options no-certifi
2854 • youtube-dl tries to remove some superfluous punctuations from file‐
2856 names. While this can sometimes be helpful, it is often undesirable.
2857 So yt-dlp tries to keep the fields in the filenames as close to their
2858 original values as possible. You can use --compat-options filename-
2859 sanitization to revert to youtube-dl's behavior
2860 For ease of use, a few more compat options are available:
2862 • --compat-options all: Use all compat options (Do NOT use)
2864 • --compat-options youtube-dl: Same as --compat-options all,-multi‐
2866 streams
2867 • --compat-options youtube-dlc: Same as --compat-options all,-no-live-
2869 chat,-no-youtube-channel-redirect
2870
2872 These are all the deprecated options and the current alternative to
2873 achieve the same effect
2874 Almost redundant options
2876 While these options are almost the same as their new counterparts,
2877 there are some differences that prevents them being redundant
2878 -j, --dump-json --print "%()j"
2880 -F, --list-formats --print formats_table
2881 --list-thumbnails --print thumbnails_table --print playlist:thumbnails_table
2882 --list-subs --print automatic_captions_table --print subtitles_table
2883 Redundant options
2885 While these options are redundant, they are still expected to be used
2886 due to their ease of use
2887 --get-description --print description
2889 --get-duration --print duration_string
2890 --get-filename --print filename
2891 --get-format --print format
2892 --get-id --print id
2893 --get-thumbnail --print thumbnail
2894 -e, --get-title --print title
2895 -g, --get-url --print urls
2896 --match-title REGEX --match-filter "title ~= (?i)REGEX"
2897 --reject-title REGEX --match-filter "title !~= (?i)REGEX"
2898 --min-views COUNT --match-filter "view_count >=? COUNT"
2899 --max-views COUNT --match-filter "view_count <=? COUNT"
2900 --user-agent UA --add-header "User-Agent:UA"
2901 --referer URL --add-header "Referer:URL"
2902 --playlist-start NUMBER -I NUMBER:
2903 --playlist-end NUMBER -I :NUMBER
2904 --playlist-reverse -I ::-1
2905 --no-playlist-reverse Default
2906 Not recommended
2908 While these options still work, their use is not recommended since
2909 there are other alternatives to achieve the same
2910 --exec-before-download CMD --exec "before_dl:CMD"
2912 --no-exec-before-download --no-exec
2913 --all-formats -f all
2914 --all-subs --sub-langs all --write-subs
2915 --print-json -j --no-simulate
2916 --autonumber-size NUMBER Use string formatting. Eg: %(autonumber)03d
2917 --autonumber-start NUMBER Use internal field formatting like %(autonumber+NUMBER)s
2918 --id -o "%(id)s.%(ext)s"
2919 --metadata-from-title FORMAT --parse-metadata "%(title)s:FORMAT"
2920 --hls-prefer-native --downloader "m3u8:native"
2921 --hls-prefer-ffmpeg --downloader "m3u8:ffmpeg"
2922 --list-formats-old --compat-options list-formats (Alias: --no-list-formats-as-table)
2923 --list-formats-as-table --compat-options -list-formats [Default] (Alias: --no-list-formats-old)
2924 --youtube-skip-dash-manifest --extractor-args "youtube:skip=dash" (Alias: --no-youtube-include-dash-manifest)
2925 --youtube-skip-hls-manifest --extractor-args "youtube:skip=hls" (Alias: --no-youtube-include-hls-manifest)
2926 --youtube-include-dash-manifest Default (Alias: --no-youtube-skip-dash-manifest)
2927 --youtube-include-hls-manifest Default (Alias: --no-youtube-skip-hls-manifest)
2928 Developer options
2930 These options are not intended to be used by the end-user
2931 --test Download only part of video for testing extractors
2933 --load-pages Load pages dumped by --write-pages
2934 --youtube-print-sig-code For testing youtube signatures
2935 --allow-unplayable-formats List unplayable formats also
2936 --no-allow-unplayable-formats Default
2937 Old aliases
2939 These are aliases that are no longer documented for various reasons
2940 --avconv-location --ffmpeg-location
2942 --clean-infojson --clean-info-json
2943 --cn-verification-proxy URL --geo-verification-proxy URL
2944 --dump-headers --print-traffic
2945 --dump-intermediate-pages --dump-pages
2946 --force-write-download-archive --force-write-archive
2947 --load-info --load-info-json
2948 --no-clean-infojson --no-clean-info-json
2949 --no-split-tracks --no-split-chapters
2950 --no-write-srt --no-write-subs
2951 --prefer-unsecure --prefer-insecure
2952 --rate-limit RATE --limit-rate RATE
2953 --split-tracks --split-chapters
2954 --srt-lang LANGS --sub-langs LANGS
2955 --trim-file-names LENGTH --trim-filenames LENGTH
2956 --write-srt --write-subs
2957 --yes-overwrites --force-overwrites
2958 Sponskrub Options
2960 Support for SponSkrub (https://github.com/faissaloo/SponSkrub) has been
2961 deprecated in favor of the --sponsorblock options
2962 --sponskrub --sponsorblock-mark all
2964 --no-sponskrub --no-sponsorblock
2965 --sponskrub-cut --sponsorblock-remove all
2966 --no-sponskrub-cut --sponsorblock-remove -all
2967 --sponskrub-force Not applicable
2968 --no-sponskrub-force Not applicable
2969 --sponskrub-location Not applicable
2970 --sponskrub-args Not applicable
2971 No longer supported
2973 These options may no longer work as intended
2974 --prefer-avconv avconv is not officially supported by yt-dlp (Alias: --no-prefer-ffmpeg)
2976 --prefer-ffmpeg Default (Alias: --no-prefer-avconv)
2977 -C, --call-home Not implemented
2978 --no-call-home Default
2979 --include-ads No longer supported
2980 --no-include-ads Default
2981 --write-annotations No supported site has annotations now
2982 --no-write-annotations Default
2983 Removed
2985 These options were deprecated since 2014 and have now been entirely re‐
2986 moved
2987 -A, --auto-number -o "%(autonumber)s-%(id)s.%(ext)s"
2989 -t, -l, --title, --literal -o "%(title)s-%(id)s.%(ext)s"
2990
2992 See CONTRIBUTING.md for instructions on Opening an Issue and Contribut‐
2993 ing code to the project
2994
2996 For FAQ see the youtube-dl README (https://github.com/ytdl-org/youtube-
2997 dl#faq)
2998 yt-dlp(1)