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 the latest version
28 –no-update
30 Do not check for updates (default)
31 –update-to [CHANNEL]@[TAG]
33 Upgrade/downgrade to a specific version. CHANNEL can be a
34 repository as well. CHANNEL and TAG default to “stable” and
35 “latest” respectively if omitted; See “UPDATE” for details.
36 Supported channels: stable, nightly
37 -i, –ignore-errors
39 Ignore download and postprocessing errors. The download will be
40 considered successful even if the postprocessing fails
41 –no-abort-on-error
43 Continue with next video on download errors; e.g. to skip un‐
44 available videos in a playlist (default)
45 –abort-on-error
47 Abort downloading of further videos if an error occurs (Alias:
48 –no-ignore-errors)
49 –dump-user-agent
51 Display the current user-agent and exit
52 –list-extractors
54 List all supported extractors and exit
55 –extractor-descriptions
57 Output descriptions of all supported extractors and exit
58 –use-extractors NAMES
60 Extractor names to use separated by commas. You can also use
61 regexes, “all”, “default” and “end” (end URL matching);
62 e.g. –ies “holodex.*,end,youtube”. Prefix the name with a “-”
63 to exclude it, e.g. –ies default,-generic. Use –list-extractors
64 for a list of extractor names. (Alias: –ies)
65 –default-search PREFIX
67 Use this prefix for unqualified URLs. E.g. “gvsearch2:python”
68 downloads two videos from google videos for the search term
69 “python”. Use the value “auto” to let yt-dlp guess (“auto_warn‐
70 ing” to emit a warning when guessing). “error” just throws an
71 error. The default value “fixup_error” repairs broken URLs, but
72 emits an error if this is not possible instead of searching
73 –ignore-config
75 Don’t load any more configuration files except those given by
76 –config-locations. For backward compatibility, if this option
77 is found inside the system configuration file, the user configu‐
78 ration is not loaded. (Alias: –no-config)
79 –no-config-locations
81 Do not load any custom configuration files (default). When giv‐
82 en inside a configuration file, ignore all previous –config-lo‐
83 cations defined in the current file
84 –config-locations PATH
86 Location of the main configuration file; either the path to the
87 config or its containing directory (“-” for stdin). Can be used
88 multiple times and inside other configuration files
89 –flat-playlist
91 Do not extract the videos of a playlist, only list them
92 –no-flat-playlist
94 Fully extract the videos of a playlist (default)
95 –live-from-start
97 Download livestreams from the start. Currently only supported
98 for YouTube (Experimental)
99 –no-live-from-start
101 Download livestreams from the current time (default)
102 –wait-for-video MIN[-MAX]
104 Wait for scheduled streams to become available. Pass the mini‐
105 mum number of seconds (or range) to wait between retries
106 –no-wait-for-video
108 Do not wait for scheduled streams (default)
109 –mark-watched
111 Mark videos watched (even with –simulate)
112 –no-mark-watched
114 Do not mark videos watched (default)
115 –color [STREAM:]POLICY
117 Whether to emit color codes in output, optionally prefixed by
118 the STREAM (stdout or stderr) to apply the setting to. Can be
119 one of “always”, “auto” (default), “never”, or “no_color” (use
120 non color terminal sequences). Can be used multiple times
121 –compat-options OPTS
123 Options that can help keep compatibility with youtube-dl or
124 youtube-dlc configurations by reverting some of the changes made
125 in yt-dlp. See “Differences in default behavior” for details
126 –alias ALIASES OPTIONS
128 Create aliases for an option string. Unless an alias starts
129 with a dash “-”, it is prefixed with “–”. Arguments are parsed
130 according to the Python string formatting mini-language. E.g.
131 –alias get-audio,-X “-S=aext:{0},abr -x –audio-format {0}” cre‐
132 ates options “–get-audio” and “-X” that takes an argument (ARG0)
133 and expands to “-S=aext:ARG0,abr -x –audio-format ARG0”. All
134 defined aliases are listed in the –help output. Alias options
135 can trigger more aliases; so be careful to avoid defining recur‐
136 sive options. As a safety measure, each alias may be triggered
137 a maximum of 100 times. This option can be used multiple times
138 Network Options:
140 –proxy URL
141 Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS
142 proxy, specify a proper scheme, e.g. socks5://us‐
143 er:pass@127.0.0.1:1080/. Pass in an empty string (–proxy ““)
144 for direct connection
145 –socket-timeout SECONDS
147 Time to wait before giving up, in seconds
148 –source-address IP
150 Client-side IP address to bind to
151 -4, –force-ipv4
153 Make all connections via IPv4
154 -6, –force-ipv6
156 Make all connections via IPv6
157 –enable-file-urls
159 Enable file:// URLs. This is disabled by default for security
160 reasons.
161 Geo-restriction:
163 –geo-verification-proxy URL
164 Use this proxy to verify the IP address for some geo-restricted
165 sites. The default proxy specified by –proxy (or none, if the
166 option is not present) is used for the actual downloading
167 –xff VALUE
169 How to fake X-Forwarded-For HTTP header to try bypassing geo‐
170 graphic restriction. One of “default” (only when known to be
171 useful), “never”, an IP block in CIDR notation, or a two-letter
172 ISO 3166-2 country code
173 Video Selection:
175 -I, –playlist-items ITEM_SPEC
176 Comma separated playlist_index of the items to download. You
177 can specify a range using “[START]:[STOP][:STEP]”. For backward
178 compatibility, START-STOP is also supported. Use negative in‐
179 dices to count from the right and negative STEP to download in
180 reverse order. E.g. “-I 1:3,7,-5::2” used on a playlist of
181 size 15 will download the items at index 1,2,3,7,11,13,15
182 –min-filesize SIZE
184 Abort download if filesize is smaller than SIZE, e.g. 50k or
185 44.6M
186 –max-filesize SIZE
188 Abort download if filesize is larger than SIZE, e.g. 50k or
189 44.6M
190 –date DATE
192 Download only videos uploaded on this date. The date can be
193 “YYYYMMDD” or in the format [now|today|yester‐
194 day][-N[day|week|month|year]]. E.g. “–date today-2weeks” down‐
195 loads only videos uploaded on the same day two weeks ago
196 –datebefore DATE
198 Download only videos uploaded on or before this date. The date
199 formats accepted is the same as –date
200 –dateafter DATE
202 Download only videos uploaded on or after this date. The date
203 formats accepted is the same as –date
204 –match-filters FILTER
206 Generic video filter. Any “OUTPUT TEMPLATE” field can be com‐
207 pared with a number or a string using the operators defined in
208 “Filtering Formats”. You can also simply specify a field to
209 match if the field is present, use “!field” to check if the
210 field is not present, and “&” to check multiple conditions. Use
211 a “" to escape”&” or quotes if needed. If used multiple times,
212 the filter matches if atleast one of the conditions are met.
213 E.g. –match-filter !is_live –match-filter “like_count>?100 &
214 description~=’(?i)& dogs” matches only videos that are not live
215 OR those that have a like count more than 100 (or the like field
216 is not available) and also has a description that contains the
217 phrase “cats & dogs” (caseless). Use “–match-filter -” to in‐
218 teractively ask whether to download each video
219 –no-match-filters
221 Do not use any –match-filter (default)
222 –break-match-filters FILTER
224 Same as “–match-filters” but stops the download process when a
225 video is rejected
226 –no-break-match-filters
228 Do not use any –break-match-filters (default)
229 –no-playlist
231 Download only the video, if the URL refers to a video and a
232 playlist
233 –yes-playlist
235 Download the playlist, if the URL refers to a video and a
236 playlist
237 –age-limit YEARS
239 Download only videos suitable for the given age
240 –download-archive FILE
242 Download only videos not listed in the archive file. Record the
243 IDs of all downloaded videos in it
244 –no-download-archive
246 Do not use archive file (default)
247 –max-downloads NUMBER
249 Abort after downloading NUMBER files
250 –break-on-existing
252 Stop the download process when encountering a file that is in
253 the archive
254 –break-per-input
256 Alters –max-downloads, –break-on-existing, –break-match-filter,
257 and autonumber to reset per input URL
258 –no-break-per-input
260 –break-on-existing and similar options terminates the entire
261 download queue
262 –skip-playlist-after-errors N
264 Number of allowed failures until the rest of the playlist is
265 skipped
266 Download Options:
268 -N, –concurrent-fragments N
269 Number of fragments of a dash/hlsnative video that should be
270 downloaded concurrently (default is 1)
271 -r, –limit-rate RATE
273 Maximum download rate in bytes per second, e.g. 50K or 4.2M
274 –throttled-rate RATE
276 Minimum download rate in bytes per second below which throttling
277 is assumed and the video data is re-extracted, e.g. 100K
278 -R, –retries RETRIES
280 Number of retries (default is 10), or “infinite”
281 –file-access-retries RETRIES
283 Number of times to retry on file access error (default is 3), or
284 “infinite”
285 –fragment-retries RETRIES
287 Number of retries for a fragment (default is 10), or “infinite”
288 (DASH, hlsnative and ISM)
289 –retry-sleep [TYPE:]EXPR
291 Time to sleep between retries in seconds (optionally) prefixed
292 by the type of retry (http (default), fragment, file_access, ex‐
293 tractor) to apply the sleep to. EXPR can be a number, lin‐
294 ear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]]. This op‐
295 tion can be used multiple times to set the sleep for the differ‐
296 ent retry types, e.g. –retry-sleep linear=1::2 –retry-sleep
297 fragment:exp=1:20
298 –skip-unavailable-fragments
300 Skip unavailable fragments for DASH, hlsnative and ISM downloads
301 (default) (Alias: –no-abort-on-unavailable-fragments)
302 –abort-on-unavailable-fragments
304 Abort download if a fragment is unavailable (Alias: –no-skip-un‐
305 available-fragments)
306 –keep-fragments
308 Keep downloaded fragments on disk after downloading is finished
309 –no-keep-fragments
311 Delete downloaded fragments after downloading is finished (de‐
312 fault)
313 –buffer-size SIZE
315 Size of download buffer, e.g. 1024 or 16K (default is 1024)
316 –resize-buffer
318 The buffer size is automatically resized from an initial value
319 of –buffer-size (default)
320 –no-resize-buffer
322 Do not automatically adjust the buffer size
323 –http-chunk-size SIZE
325 Size of a chunk for chunk-based HTTP downloading, e.g. 10485760
326 or 10M (default is disabled). May be useful for bypassing band‐
327 width throttling imposed by a webserver (experimental)
328 –playlist-random
330 Download playlist videos in random order
331 –lazy-playlist
333 Process entries in the playlist as they are received. This dis‐
334 ables n_entries, –playlist-random and –playlist-reverse
335 –no-lazy-playlist
337 Process videos in the playlist only after the entire playlist is
338 parsed (default)
339 –xattr-set-filesize
341 Set file xattribute ytdl.filesize with expected file size
342 –hls-use-mpegts
344 Use the mpegts container for HLS videos; allowing some players
345 to play the video while downloading, and reducing the chance of
346 file corruption if download is interrupted. This is enabled by
347 default for live streams
348 –no-hls-use-mpegts
350 Do not use the mpegts container for HLS videos. This is default
351 when not downloading live streams
352 –download-sections REGEX
354 Download only chapters that match the regular expression. A “”
355 prefix denotes time-range instead of chapter. Negative time‐
356 stamps are calculated from the end. ”from-url” can be used to
357 download between the “start_time” and “end_time” extracted from
358 the URL. Needs ffmpeg. This option can be used multiple times
359 to download multiple sections, e.g. –download-sections
360 “*10:15-inf” –download-sections “intro”
361 –downloader [PROTO:]NAME
363 Name or path of the external downloader to use (optionally) pre‐
364 fixed by the protocols (http, ftp, m3u8, dash, rstp, rtmp, mms)
365 to use it for. Currently supports native, aria2c, avconv, axel,
366 curl, ffmpeg, httpie, wget. You can use this option multiple
367 times to set different downloaders for different protocols.
368 E.g. –downloader aria2c –downloader “dash,m3u8:native” will use
369 aria2c for http/ftp downloads, and the native downloader for
370 dash/m3u8 downloads (Alias: –external-downloader)
371 –downloader-args NAME:ARGS
373 Give these arguments to the external downloader. Specify the
374 downloader name and the arguments separated by a colon “:”. For
375 ffmpeg, arguments can be passed to different positions using the
376 same syntax as –postprocessor-args. You can use this option
377 multiple times to give different arguments to different down‐
378 loaders (Alias: –external-downloader-args)
379 Filesystem Options:
381 -a, –batch-file FILE
382 File containing URLs to download (“-” for stdin), one URL per
383 line. Lines starting with “#”, “;” or “]” are considered as
384 comments and ignored
385 –no-batch-file
387 Do not read URLs from batch file (default)
388 -P, –paths [TYPES:]PATH
390 The paths where the files should be downloaded. Specify the
391 type of file and the path separated by a colon “:”. All the
392 same TYPES as –output are supported. Additionally, you can also
393 provide “home” (default) and “temp” paths. All intermediary
394 files are first downloaded to the temp path and then the final
395 files are moved over to the home path after download is fin‐
396 ished. This option is ignored if –output is an absolute path
397 -o, –output [TYPES:]TEMPLATE
399 Output filename template; see “OUTPUT TEMPLATE” for details
400 –output-na-placeholder TEXT
402 Placeholder for unavailable fields in “OUTPUT TEMPLATE” (de‐
403 fault: “NA”)
404 –restrict-filenames
406 Restrict filenames to only ASCII characters, and avoid “&” and
407 spaces in filenames
408 –no-restrict-filenames
410 Allow Unicode characters, “&” and spaces in filenames (default)
411 –windows-filenames
413 Force filenames to be Windows-compatible
414 –no-windows-filenames
416 Make filenames Windows-compatible only if using Windows (de‐
417 fault)
418 –trim-filenames LENGTH
420 Limit the filename length (excluding extension) to the specified
421 number of characters
422 -w, –no-overwrites
424 Do not overwrite any files
425 –force-overwrites
427 Overwrite all video and metadata files. This option includes
428 –no-continue
429 –no-force-overwrites
431 Do not overwrite the video, but overwrite related files (de‐
432 fault)
433 -c, –continue
435 Resume partially downloaded files/fragments (default)
436 –no-continue
438 Do not resume partially downloaded fragments. If the file is
439 not fragmented, restart download of the entire file
440 –part Use .part files instead of writing directly into output file
442 (default)
443 –no-part
445 Do not use .part files - write directly into output file
446 –mtime Use the Last-modified header to set the file modification time
448 (default)
449 –no-mtime
451 Do not use the Last-modified header to set the file modification
452 time
453 –write-description
455 Write video description to a .description file
456 –no-write-description
458 Do not write video description (default)
459 –write-info-json
461 Write video metadata to a .info.json file (this may contain per‐
462 sonal information)
463 –no-write-info-json
465 Do not write video metadata (default)
466 –write-playlist-metafiles
468 Write playlist metadata in addition to the video metadata when
469 using –write-info-json, –write-description etc. (default)
470 –no-write-playlist-metafiles
472 Do not write playlist metadata when using –write-info-json,
473 –write-description etc.
474 –clean-info-json
476 Remove some internal metadata such as filenames from the infoj‐
477 son (default)
478 –no-clean-info-json
480 Write all fields to the infojson
481 –write-comments
483 Retrieve video comments to be placed in the infojson. The com‐
484 ments are fetched even without this option if the extraction is
485 known to be quick (Alias: –get-comments)
486 –no-write-comments
488 Do not retrieve video comments unless the extraction is known to
489 be quick (Alias: –no-get-comments)
490 –load-info-json FILE
492 JSON file containing the video information (created with the
493 “–write-info-json” option)
494 –cookies FILE
496 Netscape formatted file to read cookies from and dump cookie jar
497 in
498 –no-cookies
500 Do not read/dump cookies from/to file (default)
501 –cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]
503 The name of the browser to load cookies from. Currently sup‐
504 ported browsers are: brave, chrome, chromium, edge, firefox,
505 opera, safari, vivaldi. Optionally, the KEYRING used for de‐
506 crypting Chromium cookies on Linux, the name/path of the PROFILE
507 to load cookies from, and the CONTAINER name (if Firefox)
508 (“none” for no container) can be given with their respective
509 seperators. By default, all containers of the most recently ac‐
510 cessed profile are used. Currently supported keyrings are: ba‐
511 sictext, gnomekeyring, kwallet, kwallet5, kwallet6
512 –no-cookies-from-browser
514 Do not load cookies from browser (default)
515 –cache-dir DIR
517 Location in the filesystem where yt-dlp can store some download‐
518 ed information (such as client ids and signatures) permanently.
519 By default ${XDG_CACHE_HOME}/yt-dlp
520 –no-cache-dir
522 Disable filesystem caching
523 –rm-cache-dir
525 Delete all filesystem cache files
526 Thumbnail Options:
528 –write-thumbnail
529 Write thumbnail image to disk
530 –no-write-thumbnail
532 Do not write thumbnail image to disk (default)
533 –write-all-thumbnails
535 Write all thumbnail image formats to disk
536 –list-thumbnails
538 List available thumbnails of each video. Simulate unless –no-
539 simulate is used
540 Internet Shortcut Options:
542 –write-link
543 Write an internet shortcut file, depending on the current plat‐
544 form (.url, .webloc or .desktop). The URL may be cached by the
545 OS
546 –write-url-link
548 Write a .url Windows internet shortcut. The OS caches the URL
549 based on the file path
550 –write-webloc-link
552 Write a .webloc macOS internet shortcut
553 –write-desktop-link
555 Write a .desktop Linux internet shortcut
556 Verbosity and Simulation Options:
558 -q, –quiet
559 Activate quiet mode. If used with –verbose, print the log to
560 stderr
561 –no-quiet
563 Deactivate quiet mode. (Default)
564 –no-warnings
566 Ignore warnings
567 -s, –simulate
569 Do not download the video and do not write anything to disk
570 –no-simulate
572 Download the video even if printing/listing options are used
573 –ignore-no-formats-error
575 Ignore “No video formats” error. Useful for extracting metadata
576 even if the videos are not actually available for download (ex‐
577 perimental)
578 –no-ignore-no-formats-error
580 Throw error when no downloadable video formats are found (de‐
581 fault)
582 –skip-download
584 Do not download the video but write all related files (Alias:
585 –no-download)
586 -O, –print [WHEN:]TEMPLATE
588 Field name or output template to print to screen, optionally
589 prefixed with when to print it, separated by a “:”. Supported
590 values of “WHEN” are the same as that of –use-postprocessor (de‐
591 fault: video). Implies –quiet. Implies –simulate unless –no-
592 simulate or later stages of WHEN are used. This option can be
593 used multiple times
594 –print-to-file [WHEN:]TEMPLATE FILE
596 Append given template to the file. The values of WHEN and TEM‐
597 PLATE are same as that of –print. FILE uses the same syntax as
598 the output template. This option can be used multiple times
599 -j, –dump-json
601 Quiet, but print JSON information for each video. Simulate un‐
602 less –no-simulate is used. See “OUTPUT TEMPLATE” for a descrip‐
603 tion of available keys
604 -J, –dump-single-json
606 Quiet, but print JSON information for each url or infojson
607 passed. Simulate unless –no-simulate is used. If the URL
608 refers to a playlist, the whole playlist information is dumped
609 in a single line
610 –force-write-archive
612 Force download archive entries to be written as far as no errors
613 occur, even if -s or another simulation option is used (Alias:
614 –force-download-archive)
615 –newline
617 Output progress bar as new lines
618 –no-progress
620 Do not print progress bar
621 –progress
623 Show progress bar, even if in quiet mode
624 –console-title
626 Display progress in console titlebar
627 –progress-template [TYPES:]TEMPLATE
629 Template for progress outputs, optionally prefixed with one of
630 “download:” (default), “download-title:” (the console title),
631 “postprocess:”, or “postprocess-title:”. The video’s fields are
632 accessible under the “info” key and the progress attributes are
633 accessible under “progress” key. E.g. –console-title
634 –progress-template “download-title:%(info.id)s-%(progress.eta)s”
635 -v, –verbose
637 Print various debugging information
638 –dump-pages
640 Print downloaded pages encoded using base64 to debug problems
641 (very verbose)
642 –write-pages
644 Write downloaded intermediary pages to files in the current di‐
645 rectory to debug problems
646 –print-traffic
648 Display sent and read HTTP traffic
649 Workarounds:
651 –encoding ENCODING
652 Force the specified encoding (experimental)
653 –legacy-server-connect
655 Explicitly allow HTTPS connection to servers that do not support
656 RFC 5746 secure renegotiation
657 –no-check-certificates
659 Suppress HTTPS certificate validation
660 –prefer-insecure
662 Use an unencrypted connection to retrieve information about the
663 video (Currently supported only for YouTube)
664 –add-headers FIELD:VALUE
666 Specify a custom HTTP header and its value, separated by a colon
667 “:”. You can use this option multiple times
668 –bidi-workaround
670 Work around terminals that lack bidirectional text support. Re‐
671 quires bidiv or fribidi executable in PATH
672 –sleep-requests SECONDS
674 Number of seconds to sleep between requests during data extrac‐
675 tion
676 –sleep-interval SECONDS
678 Number of seconds to sleep before each download. This is the
679 minimum time to sleep when used along with –max-sleep-interval
680 (Alias: –min-sleep-interval)
681 –max-sleep-interval SECONDS
683 Maximum number of seconds to sleep. Can only be used along with
684 –min-sleep-interval
685 –sleep-subtitles SECONDS
687 Number of seconds to sleep before each subtitle download
688 Video Format Options:
690 -f, –format FORMAT
691 Video format code, see “FORMAT SELECTION” for more details
692 -S, –format-sort SORTORDER
694 Sort the formats by the fields given, see “Sorting Formats” for
695 more details
696 –format-sort-force
698 Force user specified sort order to have precedence over all
699 fields, see “Sorting Formats” for more details (Alias: –S-force)
700 –no-format-sort-force
702 Some fields have precedence over the user specified sort order
703 (default)
704 –video-multistreams
706 Allow multiple video streams to be merged into a single file
707 –no-video-multistreams
709 Only one video stream is downloaded for each output file (de‐
710 fault)
711 –audio-multistreams
713 Allow multiple audio streams to be merged into a single file
714 –no-audio-multistreams
716 Only one audio stream is downloaded for each output file (de‐
717 fault)
718 –prefer-free-formats
720 Prefer video formats with free containers over non-free ones of
721 same quality. Use with “-S ext” to strictly prefer free con‐
722 tainers irrespective of quality
723 –no-prefer-free-formats
725 Don’t give any special preference to free containers (default)
726 –check-formats
728 Make sure formats are selected only from those that are actually
729 downloadable
730 –check-all-formats
732 Check all formats for whether they are actually downloadable
733 –no-check-formats
735 Do not check that the formats are actually downloadable
736 -F, –list-formats
738 List available formats of each video. Simulate unless –no-simu‐
739 late is used
740 –merge-output-format FORMAT
742 Containers that may be used when merging formats, separated by
743 “/”, e.g. “mp4/mkv”. Ignored if no merge is required. (cur‐
744 rently supported: avi, flv, mkv, mov, mp4, webm)
745 Subtitle Options:
747 –write-subs
748 Write subtitle file
749 –no-write-subs
751 Do not write subtitle file (default)
752 –write-auto-subs
754 Write automatically generated subtitle file (Alias: –write-auto‐
755 matic-subs)
756 –no-write-auto-subs
758 Do not write auto-generated subtitles (default) (Alias: –no-
759 write-automatic-subs)
760 –list-subs
762 List available subtitles of each video. Simulate unless –no-
763 simulate is used
764 –sub-format FORMAT
766 Subtitle format; accepts formats preference, e.g. “srt” or
767 “ass/srt/best”
768 –sub-langs LANGS
770 Languages of the subtitles to download (can be regex) or “all”
771 separated by commas, e.g. –sub-langs “en.*,ja”. You can prefix
772 the language code with a “-” to exclude it from the requested
773 languages, e.g. –sub-langs all,-live_chat. Use –list-subs for a
774 list of available language tags
775 Authentication Options:
777 -u, –username USERNAME
778 Login with this account ID
779 -p, –password PASSWORD
781 Account password. If this option is left out, yt-dlp will ask
782 interactively
783 -2, –twofactor TWOFACTOR
785 Two-factor authentication code
786 -n, –netrc
788 Use .netrc authentication data
789 –netrc-location PATH
791 Location of .netrc authentication data; either the path or its
792 containing directory. Defaults to ~/.netrc
793 –netrc-cmd NETRC_CMD
795 Command to execute to get the credentials for an extractor.
796 –video-password PASSWORD
798 Video password (vimeo, youku)
799 –ap-mso MSO
801 Adobe Pass multiple-system operator (TV provider) identifier,
802 use –ap-list-mso for a list of available MSOs
803 –ap-username USERNAME
805 Multiple-system operator account login
806 –ap-password PASSWORD
808 Multiple-system operator account password. If this option is
809 left out, yt-dlp will ask interactively
810 –ap-list-mso
812 List all supported multiple-system operators
813 –client-certificate CERTFILE
815 Path to client certificate file in PEM format. May include the
816 private key
817 –client-certificate-key KEYFILE
819 Path to private key file for client certificate
820 –client-certificate-password PASSWORD
822 Password for client certificate private key, if encrypted. If
823 not provided, and the key is encrypted, yt-dlp will ask interac‐
824 tively
825 Post-Processing Options:
827 -x, –extract-audio
828 Convert video files to audio-only files (requires ffmpeg and ff‐
829 probe)
830 –audio-format FORMAT
832 Format to convert the audio to when -x is used. (currently sup‐
833 ported: best (default), aac, alac, flac, m4a, mp3, opus, vorbis,
834 wav). You can specify multiple rules using similar syntax as
835 –remux-video
836 –audio-quality QUALITY
838 Specify ffmpeg audio quality to use when converting the audio
839 with -x. Insert a value between 0 (best) and 10 (worst) for VBR
840 or a specific bitrate like 128K (default 5)
841 –remux-video FORMAT
843 Remux the video into another container if necessary (currently
844 supported: avi, flv, gif, mkv, mov, mp4, webm, aac, aiff, alac,
845 flac, m4a, mka, mp3, ogg, opus, vorbis, wav). If target con‐
846 tainer does not support the video/audio codec, remuxing will
847 fail. You can specify multiple rules; e.g.
848 “aac>m4a/mov>mp4/mkv” will remux aac to m4a, mov to mp4 and any‐
849 thing else to mkv
850 –recode-video FORMAT
852 Re-encode the video into another format if necessary. The syn‐
853 tax and supported formats are the same as –remux-video
854 –postprocessor-args NAME:ARGS
856 Give these arguments to the postprocessors. Specify the post‐
857 processor/executable name and the arguments separated by a colon
858 “:” to give the argument to the specified postprocessor/exe‐
859 cutable. Supported PP are: Merger, ModifyChapters, SplitChap‐
860 ters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, Em‐
861 bedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsCon‐
862 vertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp and
863 FixupDuration. The supported executables are: AtomicParsley,
864 FFmpeg and FFprobe. You can also specify “PP+EXE:ARGS” to give
865 the arguments to the specified executable only when being used
866 by the specified postprocessor. Additionally, for ffmpeg/ff‐
867 probe, “_i”/“_o” can be appended to the prefix optionally fol‐
868 lowed by a number to pass the argument before the specified in‐
869 put/output file, e.g. –ppa “Merger+ffmpeg_i1:-v quiet”. You can
870 use this option multiple times to give different arguments to
871 different postprocessors. (Alias: –ppa)
872 -k, –keep-video
874 Keep the intermediate video file on disk after post-processing
875 –no-keep-video
877 Delete the intermediate video file after post-processing (de‐
878 fault)
879 –post-overwrites
881 Overwrite post-processed files (default)
882 –no-post-overwrites
884 Do not overwrite post-processed files
885 –embed-subs
887 Embed subtitles in the video (only for mp4, webm and mkv videos)
888 –no-embed-subs
890 Do not embed subtitles (default)
891 –embed-thumbnail
893 Embed thumbnail in the video as cover art
894 –no-embed-thumbnail
896 Do not embed thumbnail (default)
897 –embed-metadata
899 Embed metadata to the video file. Also embeds chapters/infojson
900 if present unless –no-embed-chapters/–no-embed-info-json are
901 used (Alias: –add-metadata)
902 –no-embed-metadata
904 Do not add metadata to file (default) (Alias: –no-add-metadata)
905 –embed-chapters
907 Add chapter markers to the video file (Alias: –add-chapters)
908 –no-embed-chapters
910 Do not add chapter markers (default) (Alias: –no-add-chapters)
911 –embed-info-json
913 Embed the infojson as an attachment to mkv/mka video files
914 –no-embed-info-json
916 Do not embed the infojson as an attachment to the video file
917 –parse-metadata [WHEN:]FROM:TO
919 Parse additional metadata like title/artist from other fields;
920 see “MODIFYING METADATA” for details. Supported values of
921 “WHEN” are the same as that of –use-postprocessor (default:
922 pre_process)
923 –replace-in-metadata [WHEN:]FIELDS REGEX REPLACE
925 Replace text in a metadata field using the given regex. This
926 option can be used multiple times. Supported values of “WHEN”
927 are the same as that of –use-postprocessor (default:
928 pre_process)
929 –xattrs
931 Write metadata to the video file’s xattrs (using dublin core and
932 xdg standards)
933 –concat-playlist POLICY
935 Concatenate videos in a playlist. One of “never”, “always”, or
936 “multi_video” (default; only when the videos form a single
937 show). All the video files must have same codecs and number of
938 streams to be concatable. The “pl_video:” prefix can be used
939 with “–paths” and “–output” to set the output filename for the
940 concatenated files. See “OUTPUT TEMPLATE” for details
941 –fixup POLICY
943 Automatically correct known faults of the file. One of never
944 (do nothing), warn (only emit a warning), detect_or_warn (the
945 default; fix file if we can, warn otherwise), force (try fixing
946 even if file already exists)
947 –ffmpeg-location PATH
949 Location of the ffmpeg binary; either the path to the binary or
950 its containing directory
951 –exec [WHEN:]CMD
953 Execute a command, optionally prefixed with when to execute it,
954 separated by a “:”. Supported values of “WHEN” are the same as
955 that of –use-postprocessor (default: after_move). Same syntax
956 as the output template can be used to pass any field as argu‐
957 ments to the command. If no fields are passed,
958 %(filepath,_filename|)q is appended to the end of the command.
959 This option can be used multiple times
960 –no-exec
962 Remove any previously defined –exec
963 –convert-subs FORMAT
965 Convert the subtitles to another format (currently supported:
966 ass, lrc, srt, vtt) (Alias: –convert-subtitles)
967 –convert-thumbnails FORMAT
969 Convert the thumbnails to another format (currently supported:
970 jpg, png, webp). You can specify multiple rules using similar
971 syntax as –remux-video
972 –split-chapters
974 Split video into multiple files based on internal chapters. The
975 “chapter:” prefix can be used with “–paths” and “–output” to set
976 the output filename for the split files. See “OUTPUT TEMPLATE”
977 for details
978 –no-split-chapters
980 Do not split video based on chapters (default)
981 –remove-chapters REGEX
983 Remove chapters whose title matches the given regular expres‐
984 sion. The syntax is the same as –download-sections. This op‐
985 tion can be used multiple times
986 –no-remove-chapters
988 Do not remove any chapters from the file (default)
989 –force-keyframes-at-cuts
991 Force keyframes at cuts when downloading/splitting/removing sec‐
992 tions. This is slow due to needing a re-encode, but the result‐
993 ing video may have fewer artifacts around the cuts
994 –no-force-keyframes-at-cuts
996 Do not force keyframes around the chapters when cutting/split‐
997 ting (default)
998 –use-postprocessor NAME[:ARGS]
1000 The (case sensitive) name of plugin postprocessors to be en‐
1001 abled, and (optionally) arguments to be passed to it, separated
1002 by a colon “:”. ARGS are a semicolon “;” delimited list of
1003 NAME=VALUE. The “when” argument determines when the postproces‐
1004 sor is invoked. It can be one of “pre_process” (after video ex‐
1005 traction), “after_filter” (after video passes filter), “video”
1006 (after –format; before –print/–output), “before_dl” (before each
1007 video download), “post_process” (after each video download; de‐
1008 fault), “after_move” (after moving video file to it’s final lo‐
1009 cations), “after_video” (after downloading and processing all
1010 formats of a video), or “playlist” (at end of playlist). This
1011 option can be used multiple times to add different postproces‐
1012 sors
1013 SponsorBlock Options:
1015 Make chapter entries for, or remove various segments (sponsor, intro‐
1016 ductions, etc.) from downloaded YouTube videos using the SponsorBlock
1017 API (https://sponsor.ajay.app)
1018 –sponsorblock-mark CATS
1020 SponsorBlock categories to create chapters for, separated by
1021 commas. Available categories are sponsor, intro, outro, self‐
1022 promo, preview, filler, interaction, music_offtopic, poi_high‐
1023 light, chapter, all and default (=all). You can prefix the cat‐
1024 egory with a “-” to exclude it. See [1] for description of the
1025 categories. E.g. –sponsorblock-mark all,-preview [1]
1026 https://wiki.sponsor.ajay.app/w/Segment_Categories
1027 –sponsorblock-remove CATS
1029 SponsorBlock categories to be removed from the video file, sepa‐
1030 rated by commas. If a category is present in both mark and re‐
1031 move, remove takes precedence. The syntax and available cate‐
1032 gories are the same as for –sponsorblock-mark except that “de‐
1033 fault” refers to “all,-filler” and poi_highlight, chapter are
1034 not available
1035 –sponsorblock-chapter-title TEMPLATE
1037 An output template for the title of the SponsorBlock chapters
1038 created by –sponsorblock-mark. The only available fields are
1039 start_time, end_time, category, categories, name, catego‐
1040 ry_names. Defaults to “[SponsorBlock]: %(category_names)l”
1041 –no-sponsorblock
1043 Disable both –sponsorblock-mark and –sponsorblock-remove
1044 –sponsorblock-api URL
1046 SponsorBlock API location, defaults to https://sponsor.ajay.app
1047 Extractor Options:
1049 –extractor-retries RETRIES
1050 Number of retries for known extractor errors (default is 3), or
1051 “infinite”
1052 –allow-dynamic-mpd
1054 Process dynamic DASH manifests (default) (Alias: –no-ignore-dy‐
1055 namic-mpd)
1056 –ignore-dynamic-mpd
1058 Do not process dynamic DASH manifests (Alias: –no-allow-dynamic-
1059 mpd)
1060 –hls-split-discontinuity
1062 Split HLS playlists to different formats at discontinuities such
1063 as ad breaks
1064 –no-hls-split-discontinuity
1066 Do not split HLS playlists to different formats at discontinu‐
1067 ities such as ad breaks (default)
1068 –extractor-args IE_KEY:ARGS
1070 Pass ARGS arguments to the IE_KEY extractor. See “EXTRACTOR AR‐
1071 GUMENTS” for details. You can use this option multiple times to
1072 give arguments for different extractors
1073
1075 You can configure yt-dlp by placing any supported command line option
1076 to a configuration file. The configuration is loaded from the follow‐
1077 ing locations:
1078 1. Main Configuration:
1080 • The file given by --config-location
1082 2. Portable Configuration: (Recommended for portable installations)
1084 • If using a binary, yt-dlp.conf in the same directory as the bina‐
1086 ry
1087 • If running from source-code, yt-dlp.conf in the parent directory
1089 of yt_dlp
1090 3. Home Configuration:
1092 • yt-dlp.conf in the home path given by -P
1094 • If -P is not given, the current directory is searched
1096 4. User Configuration:
1098 • ${XDG_CONFIG_HOME}/yt-dlp.conf
1100 • ${XDG_CONFIG_HOME}/yt-dlp/config (recommended on Linux/macOS)
1102 • ${XDG_CONFIG_HOME}/yt-dlp/config.txt
1104 • ${APPDATA}/yt-dlp.conf
1106 • ${APPDATA}/yt-dlp/config (recommended on Windows)
1108 • ${APPDATA}/yt-dlp/config.txt
1110 • ~/yt-dlp.conf
1112 • ~/yt-dlp.conf.txt
1114 • ~/.yt-dlp/config
1116 • ~/.yt-dlp/config.txt See also: Notes about environment variables
1118 5. System Configuration:
1120 • /etc/yt-dlp.conf
1122 • /etc/yt-dlp/config
1124 • /etc/yt-dlp/config.txt
1126 E.g. with the following configuration file yt-dlp will always extract
1128 the audio, not copy the mtime, use a proxy and save all videos under
1129 YouTube directory in your home directory:
1130 # Lines starting with # are comments
1132 # Always extract audio
1134 -x
1135 # Do not copy the mtime
1137 --no-mtime
1138 # Use this proxy
1140 --proxy 127.0.0.1:3128
1141 # Save all videos under YouTube directory in your home directory
1143 -o ~/YouTube/%(title)s.%(ext)s
1144 Note: Options in configuration file are just the same options aka
1146 switches used in regular command line calls; thus there must be no
1147 whitespace after - or --, e.g. -o or --proxy but not - o or -- proxy.
1148 They must also be quoted when necessary as-if it were a UNIX shell.
1149 You can use --ignore-config if you want to disable all configuration
1151 files for a particular yt-dlp run. If --ignore-config is found inside
1152 any configuration file, no further configuration will be loaded. For
1153 example, having the option in the portable configuration file prevents
1154 loading of home, user, and system configurations. Additionally, (for
1155 backward compatibility) if --ignore-config is found inside the system
1156 configuration file, the user configuration is not loaded.
1157 Configuration file encoding
1159 The configuration files are decoded according to the UTF BOM if
1160 present, and in the encoding from system locale otherwise.
1161 If you want your file to be decoded differently, add # coding: ENCODING
1163 to the beginning of the file (e.g. # coding: shift-jis). There must be
1164 no characters before that, even spaces or BOM.
1165 Authentication with netrc
1167 You may also want to configure automatic credentials storage for ex‐
1168 tractors that support authentication (by providing login and password
1169 with --username and --password) in order not to pass credentials as
1170 command line arguments on every yt-dlp execution and prevent tracking
1171 plain text passwords in the shell command history. You can achieve
1172 this using a .netrc file (https://stackoverflow.com/tags/.netrc/info)
1173 on a per-extractor basis. For that you will need to create a .netrc
1174 file in --netrc-location and restrict permissions to read/write by only
1175 you:
1176 touch ${HOME}/.netrc
1178 chmod a-rwx,u+rw ${HOME}/.netrc
1179 After that you can add credentials for an extractor in the following
1181 format, where extractor is the name of the extractor in lowercase:
1182 machine <extractor> login <username> password <password>
1184 E.g.
1186 machine youtube login myaccount@gmail.com password my_youtube_password
1188 machine twitch login my_twitch_account_name password my_twitch_password
1189 To activate authentication with the .netrc file you should pass --netrc
1191 to yt-dlp or place it in the configuration file.
1192 The default location of the .netrc file is ~ (see below).
1194 As an alternative to using the .netrc file, which has the disadvantage
1196 of keeping your passwords in a plain text file, you can configure a
1197 custom shell command to provide the credentials for an extractor. This
1198 is done by providing the --netrc-cmd parameter, it shall output the
1199 credentials in the netrc format and return 0 on success, other values
1200 will be treated as an error. {} in the command will be replaced by the
1201 name of the extractor to make it possible to select the credentials for
1202 the right extractor.
1203 E.g. To use an encrypted .netrc file stored as .authinfo.gpg
1205 yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' https://www.youtube.com/watch?v=BaW_jenozKc
1207 Notes about environment variables
1209 • Environment variables are normally specified as ${VARIABLE}/$VARIABLE
1210 on UNIX and %VARIABLE% on Windows; but is always shown as ${VARIABLE}
1211 in this documentation
1212 • yt-dlp also allow using UNIX-style variables on Windows for path-like
1214 options; e.g. --output, --config-location
1215 • If unset, ${XDG_CONFIG_HOME} defaults to ~/.config and
1217 ${XDG_CACHE_HOME} to ~/.cache
1218 • On Windows, ~ points to ${HOME} if present; or, ${USERPROFILE} or
1220 ${HOMEDRIVE}${HOMEPATH} otherwise
1221 • On Windows, ${USERPROFILE} generally points to C:\Users\<user name>
1223 and ${APPDATA} to ${USERPROFILE}\AppData\Roaming
1224
1226 The -o option is used to indicate a template for the output file names
1227 while -P option is used to specify the path each type of file should be
1228 saved to.
1229 The simplest usage of -o is not to set any template arguments when
1231 downloading a single file, like in yt-dlp -o funny_video.flv
1232 "https://some/video" (hard-coding file extension like this is not rec‐
1233 ommended and could break some post-processing).
1234 It may however also contain special sequences that will be replaced
1236 when downloading each video. The special sequences may be formatted
1237 according to Python string formatting operations
1238 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1239 formatting), e.g. %(NAME)s or %(NAME)05d. To clarify, that is a per‐
1240 cent symbol followed by a name in parentheses, followed by formatting
1241 operations.
1242 The field names themselves (the part inside the parenthesis) can also
1244 have some special formatting:
1245 1. Object traversal: The dictionaries and lists available in metadata
1247 can be traversed by using a dot . separator; e.g. %(tags.0)s, %(sub‐
1248 titles.en.-1.ext)s. You can do Python slicing with colon :; E.g.
1249 %(id.3:7:-1)s, %(formats.:.format_id)s. Curly braces {} can be used
1250 to build dictionaries with only specific keys; e.g. %(for‐
1251 mats.:.{format_id,height})#j. An empty field name %()s refers to
1252 the entire infodict; e.g. %(.{id,title})s. Note that all the fields
1253 that become available using this method are not listed below. Use
1254 -j to see such fields
1255 2. Addition: Addition and subtraction of numeric fields can be done us‐
1257 ing + and - respectively. E.g. %(playlist_index+10)03d, %(n_en‐
1258 tries+1-playlist_index)d
1259 3. Date/time Formatting: Date/time fields can be formatted according to
1261 strftime formatting (https://docs.python.org/3/library/date‐
1262 time.html#strftime-and-strptime-format-codes) by specifying it sepa‐
1263 rated from the field name using a >. E.g. %(duration>%H-%M-%S)s,
1264 %(upload_date>%Y-%m-%d)s, %(epoch-3600>%H-%M-%S)s
1265 4. Alternatives: Alternate fields can be specified separated with a ,.
1267 E.g. %(release_date>%Y,upload_date>%Y|Unknown)s
1268 5. Replacement: A replacement value can be specified using a & separa‐
1270 tor according to the str.format mini-language
1271 (https://docs.python.org/3/library/string.html#format-specification-
1272 mini-language). If the field is not empty, this replacement value
1273 will be used instead of the actual field content. This is done af‐
1274 ter alternate fields are considered; thus the replacement is used if
1275 any of the alternative fields is not empty. E.g. %(chapters&has
1276 chapters|no chapters)s, %(title&TITLE={:>20}|NO TITLE)s
1277 6. Default: A literal default value can be specified for when the field
1279 is empty using a | separator. This overrides --output-na-placehold‐
1280 er. E.g. %(uploader|Unknown)s
1281 7. More Conversions: In addition to the normal format types diouxXeEf‐
1283 FgGcrs, yt-dlp additionally supports converting to B = Bytes, j =
1284 json (flag # for pretty-printing, + for Unicode), h = HTML escaping,
1285 l = a comma separated list (flag # for \n newline-separated), q = a
1286 string quoted for the terminal (flag # to split a list into differ‐
1287 ent arguments), D = add Decimal suffixes (e.g. 10M) (flag # to use
1288 1024 as factor), and S = Sanitize as filename (flag # for restrict‐
1289 ed)
1290 8. Unicode normalization: The format type U can be used for NFC Unicode
1292 normalization (https://docs.python.org/3/library/unicodeda‐
1293 ta.html#unicodedata.normalize). The alternate form flag (#) changes
1294 the normalization to NFD and the conversion flag + can be used for
1295 NFKC/NFKD compatibility equivalence normalization. E.g. %(ti‐
1296 tle)+.100U is NFKC
1297 To summarize, the general syntax for a field is:
1299 %(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
1301 Additionally, you can set different output templates for the various
1303 metadata files separately from the general output template by specify‐
1304 ing the type of file followed by the template separated by a colon :.
1305 The different file types supported are subtitle, thumbnail, descrip‐
1306 tion, annotation (deprecated), infojson, link, pl_thumbnail, pl_de‐
1307 scription, pl_infojson, chapter, pl_video. E.g. -o "%(ti‐
1308 tle)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s" will put the
1309 thumbnails in a folder with the same name as the video. If any of the
1310 templates is empty, that type of file will not be written. E.g.
1311 --write-thumbnail -o "thumbnail:" will write thumbnails only for
1312 playlists and not for video.
1313 Note: Due to post-processing (i.e. merging etc.), the actual output
1315 filename might differ. Use --print after_move:filepath to get the name
1316 after all post-processing is complete.
1317 The available fields are:
1319 • id (string): Video identifier
1321 • title (string): Video title
1323 • fulltitle (string): Video title ignoring live timestamp and generic
1325 title
1326 • ext (string): Video filename extension
1328 • alt_title (string): A secondary title of the video
1330 • description (string): The description of the video
1332 • display_id (string): An alternative identifier for the video
1334 • uploader (string): Full name of the video uploader
1336 • license (string): License name the video is licensed under
1338 • creator (string): The creator of the video
1340 • timestamp (numeric): UNIX timestamp of the moment the video became
1342 available
1343 • upload_date (string): Video upload date in UTC (YYYYMMDD)
1345 • release_timestamp (numeric): UNIX timestamp of the moment the video
1347 was released
1348 • release_date (string): The date (YYYYMMDD) when the video was re‐
1350 leased in UTC
1351 • modified_timestamp (numeric): UNIX timestamp of the moment the video
1353 was last modified
1354 • modified_date (string): The date (YYYYMMDD) when the video was last
1356 modified in UTC
1357 • uploader_id (string): Nickname or id of the video uploader
1359 • channel (string): Full name of the channel the video is uploaded on
1361 • channel_id (string): Id of the channel
1363 • channel_follower_count (numeric): Number of followers of the channel
1365 • channel_is_verified (boolean): Whether the channel is verified on the
1367 platform
1368 • location (string): Physical location where the video was filmed
1370 • duration (numeric): Length of the video in seconds
1372 • duration_string (string): Length of the video (HH:mm:ss)
1374 • view_count (numeric): How many users have watched the video on the
1376 platform
1377 • concurrent_view_count (numeric): How many users are currently watch‐
1379 ing the video on the platform.
1380 • like_count (numeric): Number of positive ratings of the video
1382 • dislike_count (numeric): Number of negative ratings of the video
1384 • repost_count (numeric): Number of reposts of the video
1386 • average_rating (numeric): Average rating give by users, the scale
1388 used depends on the webpage
1389 • comment_count (numeric): Number of comments on the video (For some
1391 extractors, comments are only downloaded at the end, and so this
1392 field cannot be used)
1393 • age_limit (numeric): Age restriction for the video (years)
1395 • live_status (string): One of “not_live”, “is_live”, “is_upcoming”,
1397 “was_live”, “post_live” (was live, but VOD is not yet processed)
1398 • is_live (boolean): Whether this video is a live stream or a fixed-
1400 length video
1401 • was_live (boolean): Whether this video was originally a live stream
1403 • playable_in_embed (string): Whether this video is allowed to play in
1405 embedded players on other sites
1406 • availability (string): Whether the video is “private”, “premium_on‐
1408 ly”, “subscriber_only”, “needs_auth”, “unlisted” or “public”
1409 • start_time (numeric): Time in seconds where the reproduction should
1411 start, as specified in the URL
1412 • end_time (numeric): Time in seconds where the reproduction should
1414 end, as specified in the URL
1415 • extractor (string): Name of the extractor
1417 • extractor_key (string): Key name of the extractor
1419 • epoch (numeric): Unix epoch of when the information extraction was
1421 completed
1422 • autonumber (numeric): Number that will be increased with each down‐
1424 load, starting at --autonumber-start, padded with leading zeros to 5
1425 digits
1426 • video_autonumber (numeric): Number that will be increased with each
1428 video
1429 • n_entries (numeric): Total number of extracted items in the playlist
1431 • playlist_id (string): Identifier of the playlist that contains the
1433 video
1434 • playlist_title (string): Name of the playlist that contains the video
1436 • playlist (string): playlist_id or playlist_title
1438 • playlist_count (numeric): Total number of items in the playlist. May
1440 not be known if entire playlist is not extracted
1441 • playlist_index (numeric): Index of the video in the playlist padded
1443 with leading zeros according the final index
1444 • playlist_autonumber (numeric): Position of the video in the playlist
1446 download queue padded with leading zeros according to the total
1447 length of the playlist
1448 • playlist_uploader (string): Full name of the playlist uploader
1450 • playlist_uploader_id (string): Nickname or id of the playlist upload‐
1452 er
1453 • webpage_url (string): A URL to the video webpage which if given to
1455 yt-dlp should allow to get the same result again
1456 • webpage_url_basename (string): The basename of the webpage URL
1458 • webpage_url_domain (string): The domain of the webpage URL
1460 • original_url (string): The URL given by the user (or same as web‐
1462 page_url for playlist entries)
1463 All the fields in Filtering Formats can also be used
1465 Available for the video that belongs to some logical chapter or sec‐
1467 tion:
1468 • chapter (string): Name or title of the chapter the video belongs to
1470 • chapter_number (numeric): Number of the chapter the video belongs to
1472 • chapter_id (string): Id of the chapter the video belongs to
1474 Available for the video that is an episode of some series or programme:
1476 • series (string): Title of the series or programme the video episode
1478 belongs to
1479 • season (string): Title of the season the video episode belongs to
1481 • season_number (numeric): Number of the season the video episode be‐
1483 longs to
1484 • season_id (string): Id of the season the video episode belongs to
1486 • episode (string): Title of the video episode
1488 • episode_number (numeric): Number of the video episode within a season
1490 • episode_id (string): Id of the video episode
1492 Available for the media that is a track or a part of a music album:
1494 • track (string): Title of the track
1496 • track_number (numeric): Number of the track within an album or a disc
1498 • track_id (string): Id of the track
1500 • artist (string): Artist(s) of the track
1502 • genre (string): Genre(s) of the track
1504 • album (string): Title of the album the track belongs to
1506 • album_type (string): Type of the album
1508 • album_artist (string): List of all artists appeared on the album
1510 • disc_number (numeric): Number of the disc or other physical medium
1512 the track belongs to
1513 • release_year (numeric): Year (YYYY) when the album was released
1515 Available only when using --download-sections and for chapter: prefix
1517 when using --split-chapters for videos with internal chapters:
1518 • section_title (string): Title of the chapter
1520 • section_number (numeric): Number of the chapter within the file
1522 • section_start (numeric): Start time of the chapter in seconds
1524 • section_end (numeric): End time of the chapter in seconds
1526 Available only when used in --print:
1528 • urls (string): The URLs of all requested formats, one in each line
1530 • filename (string): Name of the video file. Note that the actual
1532 filename may differ
1533 • formats_table (table): The video format table as printed by --list-
1535 formats
1536 • thumbnails_table (table): The thumbnail format table as printed by
1538 --list-thumbnails
1539 • subtitles_table (table): The subtitle format table as printed by
1541 --list-subs
1542 • automatic_captions_table (table): The automatic subtitle format table
1544 as printed by --list-subs
1545 Available only after the video is downloaded (post_process/after_move):
1547 • filepath: Actual path of downloaded video file
1549 Available only in --sponsorblock-chapter-title:
1551 • start_time (numeric): Start time of the chapter in seconds
1553 • end_time (numeric): End time of the chapter in seconds
1555 • categories (list): The SponsorBlock categories (https://wiki.spon‐
1557 sor.ajay.app/w/Types#Category) the chapter belongs to
1558 • category (string): The smallest SponsorBlock category the chapter be‐
1560 longs to
1561 • category_names (list): Friendly names of the categories
1563 • name (string): Friendly name of the smallest category
1565 • type (string): The SponsorBlock action type (https://wiki.spon‐
1567 sor.ajay.app/w/Types#Action_Type) of the chapter
1568 Each aforementioned sequence when referenced in an output template will
1570 be replaced by the actual value corresponding to the sequence name.
1571 E.g. for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title yt-
1572 dlp test video and id BaW_jenozKc, this will result in a yt-dlp test
1573 video-BaW_jenozKc.mp4 file created in the current directory.
1574 Note: Some of the sequences are not guaranteed to be present since they
1576 depend on the metadata obtained by a particular extractor. Such se‐
1577 quences will be replaced with placeholder value provided with --output-
1578 na-placeholder (NA by default).
1579 Tip: Look at the -j output to identify which fields are available for
1581 the particular URL
1582 For numeric sequences you can use numeric related formatting
1584 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1585 formatting); e.g. %(view_count)05d will result in a string with view
1586 count padded with zeros up to 5 characters, like in 00042.
1587 Output templates can also contain arbitrary hierarchical path, e.g. -o
1589 "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" which will result
1590 in downloading each video in a directory corresponding to this path
1591 template. Any missing directory will be automatically created for you.
1592 To use percent literals in an output template use %%. To output to
1594 stdout use -o -.
1595 The current default template is %(title)s [%(id)s].%(ext)s.
1597 In some cases, you don’t want special characters such as 中, spaces, or
1599 &, such as when transferring the downloaded filename to a Windows sys‐
1600 tem or the filename through an 8bit-unsafe channel. In these cases,
1601 add the --restrict-filenames flag to get a shorter title.
1602 Output template examples
1604 $ yt-dlp --print filename -o "test video.%(ext)s" BaW_jenozKc
1605 test video.webm # Literal name with correct extension
1606 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc
1608 youtube-dl test video ''_ä↭𝕐.webm # All kinds of weird characters
1609 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
1611 youtube-dl_test_video_.webm # Restricted file name
1612 # Download YouTube playlist videos in separate directory indexed by video order in a playlist
1614 $ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1615 # Download YouTube playlist videos in separate directories according to their uploaded year
1617 $ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1618 # Prefix playlist index with " - " separator, but only if it is available
1620 $ yt-dlp -o "%(playlist_index&{} - |)s%(title)s.%(ext)s" BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1621 # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
1623 $ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1624 # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
1626 $ 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"
1627 # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
1629 $ 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"
1630 # Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
1632 # and put all temporary files in "C:\MyVideos\tmp"
1633 $ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs
1634 # Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
1636 $ 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
1637 # Stream the video being downloaded to stdout
1639 $ yt-dlp -o - BaW_jenozKc
1640
1642 By default, yt-dlp tries to download the best available quality if you
1643 don’t pass any options. This is generally equivalent to using -f
1644 bestvideo*+bestaudio/best. However, if multiple audiostreams is en‐
1645 abled (--audio-multistreams), the default format changes to -f
1646 bestvideo+bestaudio/best. Similarly, if ffmpeg is unavailable, or if
1647 you use yt-dlp to stream to stdout (-o -), the default becomes -f
1648 best/bestvideo+bestaudio.
1649 Deprecation warning: Latest versions of yt-dlp can stream multiple for‐
1651 mats to the stdout simultaneously using ffmpeg. So, in future ver‐
1652 sions, the default for this will be set to -f bv*+ba/b similar to nor‐
1653 mal downloads. If you want to preserve the -f b/bv+ba setting, it is
1654 recommended to explicitly specify it in the configuration options.
1655 The general syntax for format selection is -f FORMAT (or --format FOR‐
1657 MAT) where FORMAT is a selector expression, i.e. an expression that de‐
1658 scribes format or formats you would like to download.
1659 The simplest case is requesting a specific format; e.g. with -f 22 you
1661 can download the format with format code equal to 22. You can get the
1662 list of available format codes for particular video using --list-for‐
1663 mats or -F. Note that these format codes are extractor specific.
1664 You can also use a file extension (currently 3gp, aac, flv, m4a, mp3,
1666 mp4, ogg, wav, webm are supported) to download the best quality format
1667 of a particular file extension served as a single file, e.g. -f webm
1668 will download the best quality format with the webm extension served as
1669 a single file.
1670 You can use -f - to interactively provide the format selector for each
1672 video
1673 You can also use special names to select particular edge case formats:
1675 • all: Select all formats separately
1677 • mergeall: Select and merge all formats (Must be used with --audio-
1679 multistreams, --video-multistreams or both)
1680 • b*, best*: Select the best quality format that contains either a
1682 video or an audio or both (ie; vcodec!=none or acodec!=none)
1683 • b, best: Select the best quality format that contains both video and
1685 audio. Equivalent to best*[vcodec!=none][acodec!=none]
1686 • bv, bestvideo: Select the best quality video-only format. Equivalent
1688 to best*[acodec=none]
1689 • bv*, bestvideo*: Select the best quality format that contains video.
1691 It may also contain audio. Equivalent to best*[vcodec!=none]
1692 • ba, bestaudio: Select the best quality audio-only format. Equivalent
1694 to best*[vcodec=none]
1695 • ba*, bestaudio*: Select the best quality format that contains audio.
1697 It may also contain video. Equivalent to best*[acodec!=none] (Do not
1698 use! (https://github.com/yt-dlp/yt-dlp/issues/979#issuecom‐
1699 ment-919629354))
1700 • w*, worst*: Select the worst quality format that contains either a
1702 video or an audio
1703 • w, worst: Select the worst quality format that contains both video
1705 and audio. Equivalent to worst*[vcodec!=none][acodec!=none]
1706 • wv, worstvideo: Select the worst quality video-only format. Equiva‐
1708 lent to worst*[acodec=none]
1709 • wv*, worstvideo*: Select the worst quality format that contains
1711 video. It may also contain audio. Equivalent to
1712 worst*[vcodec!=none]
1713 • wa, worstaudio: Select the worst quality audio-only format. Equiva‐
1715 lent to worst*[vcodec=none]
1716 • wa*, worstaudio*: Select the worst quality format that contains au‐
1718 dio. It may also contain video. Equivalent to worst*[acodec!=none]
1719 For example, to download the worst quality video-only format you can
1721 use -f worstvideo. It is however recommended not to use worst and re‐
1722 lated options. When your format selector is worst, the format which is
1723 worst in all respects is selected. Most of the time, what you actually
1724 want is the video with the smallest filesize instead. So it is gener‐
1725 ally better to use -S +size or more rigorously, -S +size,+br,+res,+fps
1726 instead of -f worst. See Sorting Formats for more details.
1727 You can select the n’th best format of a type by using best<type>.<n>.
1729 For example, best.2 will select the 2nd best combined format. Similar‐
1730 ly, bv*.3 will select the 3rd best format that contains a video stream.
1731 If you want to download multiple videos, and they don’t have the same
1733 formats available, you can specify the order of preference using slash‐
1734 es. Note that formats on the left hand side are preferred; e.g. -f
1735 22/17/18 will download format 22 if it’s available, otherwise it will
1736 download format 17 if it’s available, otherwise it will download format
1737 18 if it’s available, otherwise it will complain that no suitable for‐
1738 mats are available for download.
1739 If you want to download several formats of the same video use a comma
1741 as a separator, e.g. -f 22,17,18 will download all these three formats,
1742 of course if they are available. Or a more sophisticated example com‐
1743 bined with the precedence feature: -f
1744 136/137/mp4/bestvideo,140/m4a/bestaudio.
1745 You can merge the video and audio of multiple formats into a single
1747 file using -f <format1>+<format2>+... (requires ffmpeg installed);
1748 e.g. -f bestvideo+bestaudio will download the best video-only format,
1749 the best audio-only format and mux them together with ffmpeg.
1750 Deprecation warning: Since the below described behavior is complex and
1752 counter-intuitive, this will be removed and multistreams will be en‐
1753 abled by default in the future. A new operator will be instead added
1754 to limit formats to single audio/video
1755 Unless --video-multistreams is used, all formats with a video stream
1757 except the first one are ignored. Similarly, unless --audio-multi‐
1758 streams is used, all formats with an audio stream except the first one
1759 are ignored. E.g. -f bestvideo+best+bestaudio --video-multistreams
1760 --audio-multistreams will download and merge all 3 given formats. The
1761 resulting file will have 2 video streams and 2 audio streams. But -f
1762 bestvideo+best+bestaudio --no-video-multistreams will download and
1763 merge only bestvideo and bestaudio. best is ignored since another for‐
1764 mat containing a video stream (bestvideo) has already been selected.
1765 The order of the formats is therefore important. -f best+bestaudio
1766 --no-audio-multistreams will download only best while -f bestaudio+best
1767 --no-audio-multistreams will ignore best and download only bestaudio.
1768 Filtering Formats
1770 You can also filter the video formats by putting a condition in brack‐
1771 ets, as in -f "best[height=720]" (or -f "[filesize>10M]" since filters
1772 without a selector are interpreted as best).
1773 The following numeric meta fields can be used with comparisons <, <=,
1775 >, >=, = (equals), != (not equals):
1776 • filesize: The number of bytes, if known in advance
1778 • filesize_approx: An estimate for the number of bytes
1780 • width: Width of the video, if known
1782 • height: Height of the video, if known
1784 • aspect_ratio: Aspect ratio of the video, if known
1786 • tbr: Average bitrate of audio and video in KBit/s
1788 • abr: Average audio bitrate in KBit/s
1790 • vbr: Average video bitrate in KBit/s
1792 • asr: Audio sampling rate in Hertz
1794 • fps: Frame rate
1796 • audio_channels: The number of audio channels
1798 • stretched_ratio: width:height of the video’s pixels, if not square
1800 Also filtering work for comparisons = (equals), ^= (starts with), $=
1802 (ends with), *= (contains), ~= (matches regex) and following string
1803 meta fields:
1804 • url: Video URL
1806 • ext: File extension
1808 • acodec: Name of the audio codec in use
1810 • vcodec: Name of the video codec in use
1812 • container: Name of the container format
1814 • protocol: The protocol that will be used for the actual download,
1816 lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, ism,
1817 http_dash_segments, m3u8, or m3u8_native)
1818 • language: Language code
1820 • dynamic_range: The dynamic range of the video
1822 • format_id: A short description of the format
1824 • format: A human-readable description of the format
1826 • format_note: Additional info about the format
1828 • resolution: Textual description of width and height
1830 Any string comparison may be prefixed with negation ! in order to pro‐
1832 duce an opposite comparison, e.g. !*= (does not contain). The compar‐
1833 and of a string comparison needs to be quoted with either double or
1834 single quotes if it contains spaces or special characters other than
1835 ._-.
1836 Note: None of the aforementioned meta fields are guaranteed to be
1838 present since this solely depends on the metadata obtained by particu‐
1839 lar extractor, i.e. the metadata offered by the website. Any other
1840 field made available by the extractor can also be used for filtering.
1841 Formats for which the value is not known are excluded unless you put a
1843 question mark (?) after the operator. You can combine format filters,
1844 so -f "bv[height<=?720][tbr>500]" selects up to 720p videos (or videos
1845 where the height is not known) with a bitrate of at least 500 KBit/s.
1846 You can also use the filters with all to download all formats that sat‐
1847 isfy the filter, e.g. -f "all[vcodec=none]" selects all audio-only for‐
1848 mats.
1849 Format selectors can also be grouped using parentheses; e.g. -f
1851 "(mp4,webm)[height<480]" will download the best pre-merged mp4 and webm
1852 formats with a height lower than 480.
1853 Sorting Formats
1855 You can change the criteria for being considered the best by using -S
1856 (--format-sort). The general format for this is --format-sort
1857 field1,field2....
1858 The available fields are:
1860 • hasvid: Gives priority to formats that have a video stream
1862 • hasaud: Gives priority to formats that have an audio stream
1864 • ie_pref: The format preference
1866 • lang: The language preference
1868 • quality: The quality of the format
1870 • source: The preference of the source
1872 • proto: Protocol used for download (https/ftps > http/ftp > m3u8_na‐
1874 tive/m3u8 > http_dash_segments> websocket_frag > mms/rtsp > f4f/f4m)
1875 • vcodec: Video Codec (av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 >
1877 theora > other)
1878 • acodec: Audio Codec (flac/alac > wav/aiff > opus > vorbis > aac >
1880 mp4a > mp3 > ac4 > eac3 > ac3 > dts > other)
1881 • codec: Equivalent to vcodec,acodec
1883 • vext: Video Extension (mp4 > mov > webm > flv > other). If --prefer-
1885 free-formats is used, webm is preferred.
1886 • aext: Audio Extension (m4a > aac > mp3 > ogg > opus > webm > other).
1888 If --prefer-free-formats is used, the order changes to ogg > opus >
1889 webm > mp3 > m4a > aac
1890 • ext: Equivalent to vext,aext
1892 • filesize: Exact filesize, if known in advance
1894 • fs_approx: Approximate filesize
1896 • size: Exact filesize if available, otherwise approximate filesize
1898 • height: Height of video
1900 • width: Width of video
1902 • res: Video resolution, calculated as the smallest dimension.
1904 • fps: Framerate of video
1906 • hdr: The dynamic range of the video (DV > HDR12 > HDR10+ > HDR10 >
1908 HLG > SDR)
1909 • channels: The number of audio channels
1911 • tbr: Total average bitrate in KBit/s
1913 • vbr: Average video bitrate in KBit/s
1915 • abr: Average audio bitrate in KBit/s
1917 • br: Average bitrate in KBit/s, tbr/vbr/abr
1919 • asr: Audio sample rate in Hz
1921 Deprecation warning: Many of these fields have (currently undocumented)
1923 aliases, that may be removed in a future version. It is recommended to
1924 use only the documented field names.
1925 All fields, unless specified otherwise, are sorted in descending order.
1927 To reverse this, prefix the field with a +. E.g. +res prefers format
1928 with the smallest resolution. Additionally, you can suffix a preferred
1929 value for the fields, separated by a :. E.g. res:720 prefers larger
1930 videos, but no larger than 720p and the smallest video if there are no
1931 videos less than 720p. For codec and ext, you can provide two pre‐
1932 ferred values, the first for video and the second for audio. E.g.
1933 +codec:avc:m4a (equivalent to +vcodec:avc,+acodec:m4a) sets the video
1934 codec preference to h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 >
1935 theora and audio codec preference to mp4a > aac > vorbis > opus > mp3 >
1936 ac3 > dts. You can also make the sorting prefer the nearest values to
1937 the provided by using ~ as the delimiter. E.g. filesize~1G prefers
1938 the format with filesize closest to 1 GiB.
1939 The fields hasvid and ie_pref are always given highest priority in
1941 sorting, irrespective of the user-defined order. This behaviour can be
1942 changed by using --format-sort-force. Apart from these, the default
1943 order used is: lang,quality,res,fps,hdr:12,vcodec:vp9.2,chan‐
1944 nels,acodec,size,br,asr,proto,ext,hasaud,source,id. The extractors may
1945 override this default order, but they cannot override the user-provided
1946 order.
1947 Note that the default has vcodec:vp9.2; i.e. av1 is not preferred.
1949 Similarly, the default for hdr is hdr:12; i.e. dolby vision is not pre‐
1950 ferred. These choices are made since DV and AV1 formats are not yet
1951 fully compatible with most devices. This may be changed in the future
1952 as more devices become capable of smoothly playing back these formats.
1953 If your format selector is worst, the last item is selected after sort‐
1955 ing. This means it will select the format that is worst in all re‐
1956 spects. Most of the time, what you actually want is the video with the
1957 smallest filesize instead. So it is generally better to use -f best -S
1958 +size,+br,+res,+fps.
1959 Tip: You can use the -v -F to see how the formats have been sorted
1961 (worst to best).
1962 Format Selection examples
1964 # Download and merge the best video-only format and the best audio-only format,
1965 # or download the best combined format if video-only format is not available
1966 $ yt-dlp -f "bv+ba/b"
1967 # Download best format that contains video,
1969 # and if it doesn't already have an audio stream, merge it with best audio-only format
1970 $ yt-dlp -f "bv*+ba/b"
1971 # Same as above
1973 $ yt-dlp
1974 # Download the best video-only format and the best audio-only format without merging them
1976 # For this case, an output template should be used since
1977 # by default, bestvideo and bestaudio will have the same file name.
1978 $ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"
1979 # Download and merge the best format that has a video stream,
1981 # and all audio-only formats into one file
1982 $ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams
1983 # Download and merge the best format that has a video stream,
1985 # and the best 2 audio-only formats into one file
1986 $ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams
1987 # The following examples show the old method (without -S) of format selection
1990 # and how to use -S to achieve a similar but (generally) better result
1991 # Download the worst video available (old method)
1993 $ yt-dlp -f "wv*+wa/w"
1994 # Download the best video available but with the smallest resolution
1996 $ yt-dlp -S "+res"
1997 # Download the smallest video available
1999 $ yt-dlp -S "+size,+br"
2000 # Download the best mp4 video available, or the best video if no mp4 available
2004 $ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"
2005 # Download the best video with the best extension
2007 # (For video, mp4 > mov > webm > flv. For audio, m4a > aac > mp3 ...)
2008 $ yt-dlp -S "ext"
2009 # Download the best video available but no better than 480p,
2013 # or the worst video if there is no video under 480p
2014 $ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"
2015 # Download the best video available with the largest height but no better than 480p,
2017 # or the best video with the smallest resolution if there is no video under 480p
2018 $ yt-dlp -S "height:480"
2019 # Download the best video available with the largest resolution but no better than 480p,
2021 # or the best video with the smallest resolution if there is no video under 480p
2022 # Resolution is determined by using the smallest dimension.
2023 # So this works correctly for vertical videos as well
2024 $ yt-dlp -S "res:480"
2025 # Download the best video (that also has audio) but no bigger than 50 MB,
2029 # or the worst video (that also has audio) if there is no video under 50 MB
2030 $ yt-dlp -f "b[filesize<50M] / w"
2031 # Download largest video (that also has audio) but no bigger than 50 MB,
2033 # or the smallest video (that also has audio) if there is no video under 50 MB
2034 $ yt-dlp -f "b" -S "filesize:50M"
2035 # Download best video (that also has audio) that is closest in size to 50 MB
2037 $ yt-dlp -f "b" -S "filesize~50M"
2038 # Download best video available via direct link over HTTP/HTTPS protocol,
2042 # or the best video available via any protocol if there is no such video
2043 $ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"
2044 # Download best video available via the best protocol
2046 # (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
2047 $ yt-dlp -S "proto"
2048 # Download the best video with either h264 or h265 codec,
2052 # or the best video if there is no such video
2053 $ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"
2054 # Download the best video with best codec no better than h264,
2056 # or the best video with worst codec if there is no such video
2057 $ yt-dlp -S "codec:h264"
2058 # Download the best video with worst codec no worse than h264,
2060 # or the best video with best codec if there is no such video
2061 $ yt-dlp -S "+codec:h264"
2062 # More complex examples
2066 # Download the best video no better than 720p preferring framerate greater than 30,
2068 # or the worst video (still preferring framerate greater than 30) if there is no such video
2069 $ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"
2070 # Download the video with the largest resolution no better than 720p,
2072 # or the video with the smallest resolution available if there is no such video,
2073 # preferring larger framerate for formats with the same resolution
2074 $ yt-dlp -S "res:720,fps"
2075 # Download the video with smallest resolution no worse than 480p,
2079 # or the video with the largest resolution available if there is no such video,
2080 # preferring better codec and then larger total bitrate for the same resolution
2081 $ yt-dlp -S "+res:480,codec,br"
2082
2084 The metadata obtained by the extractors can be modified by using
2085 --parse-metadata and --replace-in-metadata
2086 --replace-in-metadata FIELDS REGEX REPLACE is used to replace text in
2088 any metadata field using python regular expression
2089 (https://docs.python.org/3/library/re.html#regular-expression-syntax).
2090 Backreferences (https://docs.python.org/3/library/re.html?high‐
2091 light=backreferences#re.sub) can be used in the replace string for ad‐
2092 vanced use.
2093 The general syntax of --parse-metadata FROM:TO is to give the name of a
2095 field or an output template to extract data from, and the format to in‐
2096 terpret it as, separated by a colon :. Either a python regular expres‐
2097 sion (https://docs.python.org/3/library/re.html#regular-expression-syn‐
2098 tax) with named capture groups, a single field name, or a similar syn‐
2099 tax to the output template (only %(field)s formatting is supported) can
2100 be used for TO. The option can be used multiple times to parse and
2101 modify various fields.
2102 Note that these options preserve their relative order, allowing re‐
2104 placements to be made in parsed fields and viceversa. Also, any field
2105 thus created can be used in the output template and will also affect
2106 the media file’s metadata added when using --embed-metadata.
2107 This option also has a few special uses:
2109 • You can download an additional URL based on the metadata of the cur‐
2111 rently downloaded video. To do this, set the field additional_urls
2112 to the URL that you want to download. E.g. --parse-metadata "de‐
2113 scription:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" will
2114 download the first vimeo video found in the description
2115 • You can use this to change the metadata that is embedded in the media
2117 file. To do this, set the value of the corresponding field with a
2118 meta_ prefix. For example, any value you set to meta_description
2119 field will be added to the description field in the file - you can
2120 use this to set a different “description” and “synopsis”. To modify
2121 the metadata of individual streams, use the meta<n>_ prefix
2122 (e.g. meta1_language). Any value set to the meta_ field will over‐
2123 write all default values.
2124 Note: Metadata modification happens before format selection, post-ex‐
2126 traction and other post-processing operations. Some fields may be
2127 added or changed during these steps, overriding your changes.
2128 For reference, these are the fields yt-dlp adds by default to the file
2130 metadata:
2131 Metadata fields From
2133 ──────────────────────────────────────────────────────────────────────────
2134 title track or title
2135 date upload_date
2136 description, synopsis description
2137 purl, comment webpage_url
2138 track track_number
2139 artist artist, creator, uploader or uploader_id
2140 genre genre
2141 album album
2142 album_artist album_artist
2143 disc disc_number
2144 show series
2145 season_number season_number
2146 episode_id episode or episode_id
2147 episode_sort episode_number
2148 language of each stream the format’s language
2149 Note: The file format may not support some of these fields
2151 Modifying metadata examples
2153 # Interpret the title as "Artist - Title"
2154 $ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"
2155 # Regex example
2157 $ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"
2158 # Set title as "Series name S01E05"
2160 $ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"
2161 # Prioritize uploader as the "artist" field in video metadata
2163 $ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --embed-metadata
2164 # Set "comment" field in video metadata using description instead of webpage_url,
2166 # handling multiple lines correctly
2167 $ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --embed-metadata
2168 # Do not set any "synopsis" in the video metadata
2170 $ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"
2171 # Remove "formats" field from the infojson by setting it to an empty string
2173 $ yt-dlp --parse-metadata "video::(?P<formats>)" --write-info-json
2174 # Replace all spaces and "_" in title and uploader with a `-`
2176 $ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"
2177
2179 Some extractors accept additional arguments which can be passed using
2180 --extractor-args KEY:ARGS. ARGS is a ; (semicolon) separated string of
2181 ARG=VAL1,VAL2. E.g. --extractor-args "youtube:player-client=an‐
2182 droid_embedded,web;include_live_dash" --extractor-args "funimation:ver‐
2183 sion=uncut"
2184 Note: In CLI, ARG can use - instead of _; e.g. youtube:player-client"
2186 becomes youtube:player_client"
2187 The following extractors use this feature:
2189 youtube
2191 • lang: Prefer translated metadata (title, description etc) of this
2192 language code (case-sensitive). By default, the video primary lan‐
2193 guage metadata is preferred, with a fallback to en translated. See
2194 youtube.py (https://github.com/yt-dlp/yt-
2195 dlp/blob/c26f9b991a0681fd3ea548d535919cec1fbbd430/yt_dlp/extrac‐
2196 tor/youtube.py#L381-L390) for list of supported content language
2197 codes
2198 • skip: One or more of hls, dash or translated_subs to skip extraction
2200 of the m3u8 manifests, dash manifests and auto-translated subtitles
2201 (https://github.com/yt-dlp/yt-dlp/issues/4090#issuecom‐
2202 ment-1158102032) respectively
2203 • player_client: Clients to extract video data from. The main clients
2205 are web, android and ios with variants _music, _embedded, _embed‐
2206 screen, _creator (e.g. web_embedded); and mweb, mweb_embedscreen and
2207 tv_embedded (agegate bypass) with no variants. By default, ios,an‐
2208 droid,web is used, but tv_embedded and creator variants are added as
2209 required for age-gated videos. Similarly, the music variants are
2210 added for music.youtube.com urls. You can use all to use all the
2211 clients, and default for the default clients.
2212 • player_skip: Skip some network requests that are generally needed for
2214 robust extraction. One or more of configs (skip client configs),
2215 webpage (skip initial webpage), js (skip js player). While these op‐
2216 tions can help reduce the number of requests needed or avoid some
2217 rate-limiting, they could cause some issues. See #860
2218 (https://github.com/yt-dlp/yt-dlp/pull/860) for more details
2219 • player_params: YouTube player parameters to use for player requests.
2221 Will overwrite any default ones set by yt-dlp.
2222 • comment_sort: top or new (default) - choose comment sorting mode (on
2224 YouTube’s side)
2225 • max_comments: Limit the amount of comments to gather. Comma-separat‐
2227 ed list of integers representing max-comments,max-parents,max-
2228 replies,max-replies-per-thread. Default is all,all,all,all
2229 • E.g. all,all,1000,10 will get a maximum of 1000 replies total,
2231 with up to 10 replies per thread. 1000,all,100 will get a maximum
2232 of 1000 comments, with a maximum of 100 replies total
2233 • formats: Change the types of formats to return. dashy (convert HTTP
2235 to DASH), duplicate (identical content but different URLs or proto‐
2236 col; includes dashy), incomplete (cannot be downloaded completely -
2237 live dash and post-live m3u8)
2238 • innertube_host: Innertube API host to use for all API requests;
2240 e.g. studio.youtube.com, youtubei.googleapis.com. Note that cookies
2241 exported from one subdomain will not work on others
2242 • innertube_key: Innertube API key to use for all API requests
2244 • raise_incomplete_data: Incomplete Data Received raises an error in‐
2246 stead of reporting a warning
2247 youtubetab (YouTube playlists, channels, feeds, etc.)
2249 • skip: One or more of webpage (skip initial webpage download), au‐
2250 thcheck (allow the download of playlists requiring authentication
2251 when no initial webpage is downloaded. This may cause unwanted be‐
2252 havior, see #1122 (https://github.com/yt-dlp/yt-dlp/pull/1122) for
2253 more details)
2254 • approximate_date: Extract approximate upload_date and timestamp in
2256 flat-playlist. This may cause date-based filters to be slightly off
2257 generic
2259 • fragment_query: Passthrough any query in mpd/m3u8 manifest URLs to
2260 their fragments if no value is provided, or else apply the query
2261 string given as fragment_query=VALUE. Does not apply to ffmpeg
2262 • variant_query: Passthrough the master m3u8 URL query to its variant
2264 playlist URLs if no value is provided, or else apply the query string
2265 given as variant_query=VALUE
2266 • hls_key: An HLS AES-128 key URI or key (as hex), and optionally the
2268 IV (as hex), in the form of (URI|KEY)[,IV]; e.g. gener‐
2269 ic:hls_key=ABCDEF1234567980,0xFEDCBA0987654321. Passing any of these
2270 values will force usage of the native HLS downloader and override the
2271 corresponding values found in the m3u8 playlist
2272 • is_live: Bypass live HLS detection and manually set live_status - a
2274 value of false will set not_live, any other value (or no value) will
2275 set is_live
2276 funimation
2278 • language: Audio languages to extract, e.g. funimation:language=eng‐
2279 lish,japanese
2280 • version: The video version to extract - uncut or simulcast
2282 crunchyrollbeta (Crunchyroll)
2284 • format: Which stream type(s) to extract (default: adaptive_hls). Po‐
2285 tentially useful values include adaptive_hls, adaptive_dash, vo_adap‐
2286 tive_hls, vo_adaptive_dash, download_hls, download_dash, multi‐
2287 track_adaptive_hls_v2
2288 • hardsub: Preference order for which hardsub versions to extract, or
2290 all (default: None = no hardsubs), e.g. crunchyrollbeta:hardsub=en-
2291 US,None
2292 vikichannel
2294 • video_types: Types of videos to download - one or more of episodes,
2295 movies, clips, trailers
2296 niconico
2298 • segment_duration: Segment duration in milliseconds for HLS-DMC for‐
2299 mats. Use it at your own risk since this feature may result in your
2300 account termination.
2301 youtubewebarchive
2303 • check_all: Try to check more at the cost of more requests. One or
2304 more of thumbnails, captures
2305 gamejolt
2307 • comment_sort: hot (default), you (cookies needed), top, new - choose
2308 comment sorting mode (on GameJolt’s side)
2309 hotstar
2311 • res: resolution to ignore - one or more of sd, hd, fhd
2312 • vcodec: vcodec to ignore - one or more of h264, h265, dvh265
2314 • dr: dynamic range to ignore - one or more of sdr, hdr10, dv
2316 niconicochannelplus
2318 • max_comments: Maximum number of comments to extract - default is 120
2319 tiktok
2321 • api_hostname: Hostname to use for mobile API requests, e.g. api-
2322 h2.tiktokv.com
2323 • app_version: App version to call mobile APIs with - should be set
2325 along with manifest_app_version, e.g. 20.2.1
2326 • manifest_app_version: Numeric app version to call mobile APIs with,
2328 e.g. 221
2329 rokfinchannel
2331 • tab: Which tab to download - one of new, top, videos, podcasts,
2332 streams, stacks
2333 twitter
2335 • api: Select one of graphql (default), legacy or syndication as the
2336 API for tweet extraction. Has no effect if logged in
2337 stacommu, wrestleuniverse
2339 • device_id: UUID value assigned by the website and used to enforce de‐
2340 vice limits for paid livestream content. Can be found in browser lo‐
2341 cal storage
2342 twitch
2344 • client_id: Client ID value to be sent with GraphQL requests,
2345 e.g. twitch:client_id=kimne78kx3ncx6brgo4mv6wki5h1ko
2346 nhkradirulive (NHK らじる★らじる LIVE)
2348 • area: Which regional variation to extract. Valid areas are: sapporo,
2349 sendai, tokyo, nagoya, osaka, hiroshima, matsuyama, fukuoka. De‐
2350 faults to tokyo
2351 nflplusreplay
2353 • type: Type(s) of game replays to extract. Valid types are:
2354 full_game, full_game_spanish, condensed_game and all_22. You can use
2355 all to extract all available replay types, which is the default
2356 Note: These options may be changed/removed in the future without con‐
2358 cern for backward compatibility
2359
2361 You can install yt-dlp using the binaries, pip
2362 (https://pypi.org/project/yt-dlp) or one using a third-party package
2363 manager. See the wiki (https://github.com/yt-dlp/yt-dlp/wiki/Installa‐
2364 tion) for detailed instructions
2365 UPDATE
2367 You can use yt-dlp -U to update if you are using the release binaries
2368 If you installed with pip (https://github.com/yt-dlp/yt-dlp/wiki/In‐
2370 stallation#with-pip), simply re-run the same command that was used to
2371 install the program
2372 For other third-party package managers, see the wiki
2374 (https://github.com/yt-dlp/yt-dlp/wiki/Installation#third-party-pack‐
2375 age-managers) or refer their documentation
2376 There are currently two release channels for binaries, stable and
2378 nightly. stable is the default channel, and many of its changes have
2379 been tested by users of the nightly channel. The nightly channel has
2380 releases built after each push to the master branch, and will have the
2381 most recent fixes and additions, but also have more risk of regres‐
2382 sions. They are available in their own repo (https://github.com/yt-
2383 dlp/yt-dlp-nightly-builds/releases).
2384 When using --update/-U, a release binary will only update to its cur‐
2386 rent channel. --update-to CHANNEL can be used to switch to a different
2387 channel when a newer version is available. --update-to [CHANNEL@]TAG
2388 can also be used to upgrade or downgrade to specific tags from a chan‐
2389 nel.
2390 You may also use --update-to <repository> (<owner>/<repository>) to up‐
2392 date to a channel on a completely different repository. Be careful
2393 with what repository you are updating to though, there is no verifica‐
2394 tion done for binaries from different repositories.
2395 Example usage: * yt-dlp --update-to nightly change to nightly channel
2397 and update to its latest release * yt-dlp --update-to stable@2023.02.17
2398 upgrade/downgrade to release to stable channel tag 2023.02.17 * yt-dlp
2399 --update-to 2023.01.06 upgrade/downgrade to tag 2023.01.06 if it exists
2400 on the current channel * yt-dlp --update-to example/yt-dlp@2023.03.01
2401 upgrade/downgrade to the release from the example/yt-dlp repository,
2402 tag 2023.03.01
2403 Note: The manpages, shell completion (autocomplete) files etc. are
2405 available inside the source tarball (https://github.com/yt-dlp/yt-
2406 dlp/releases/latest/download/yt-dlp.tar.gz)
2407 DEPENDENCIES
2409 Python versions 3.7+ (CPython and PyPy) are supported. Other versions
2410 and implementations may or may not work correctly.
2411 While all the other dependencies are optional, ffmpeg and ffprobe are
2413 highly recommended
2414 Strongly recommended
2416 • ffmpeg and ffprobe (https://www.ffmpeg.org) - Required for merging
2417 separate video and audio files as well as for various post-processing
2418 tasks. License depends on the build (https://www.ffmpeg.org/le‐
2419 gal.html)
2420 There are bugs in ffmpeg that causes various issues when used along‐
2422 side yt-dlp. Since ffmpeg is such an important dependency, we pro‐
2423 vide custom builds (https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-
2424 static-auto-builds) with patches for some of these issues at yt-
2425 dlp/FFmpeg-Builds (https://github.com/yt-dlp/FFmpeg-Builds). See the
2426 readme (https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for
2427 details on the specific issues solved by these builds
2428 Important: What you need is ffmpeg binary, NOT the python package of
2430 the same name (https://pypi.org/project/ffmpeg)
2431 Networking
2433 • certifi (https://github.com/certifi/python-certifi)* - Provides
2434 Mozilla’s root certificate bundle. Licensed under MPLv2
2435 (https://github.com/certifi/python-certifi/blob/master/LICENSE)
2436 • brotli (https://github.com/google/brotli)* or brotlicffi
2438 (https://github.com/python-hyper/brotlicffi) - Brotli
2439 (https://en.wikipedia.org/wiki/Brotli) content encoding support.
2440 Both licensed under MIT 1 (https://github.com/google/brotli/blob/mas‐
2441 ter/LICENSE) 2 (https://github.com/python-hyper/brotlicffi/blob/mas‐
2442 ter/LICENSE)
2443 • websockets (https://github.com/aaugustin/websockets)* - For download‐
2445 ing over websocket. Licensed under BSD-3-Clause
2446 (https://github.com/aaugustin/websockets/blob/main/LICENSE)
2447 Metadata
2449 • mutagen (https://github.com/quodlibet/mutagen)* - For --embed-thumb‐
2450 nail in certain formats. Licensed under GPLv2+
2451 (https://github.com/quodlibet/mutagen/blob/master/COPYING)
2452 • AtomicParsley (https://github.com/wez/atomicparsley) - For --embed-
2454 thumbnail in mp4/m4a files when mutagen/ffmpeg cannot. Licensed un‐
2455 der GPLv2+ (https://github.com/wez/atomicparsley/blob/master/COPYING)
2456 • xattr (https://github.com/xattr/xattr), pyxattr
2458 (https://github.com/iustin/pyxattr) or setfattr (http://savan‐
2459 nah.nongnu.org/projects/attr) - For writing xattr metadata (--xattr)
2460 on Linux. Licensed under MIT (https://github.com/xattr/xat‐
2461 tr/blob/master/LICENSE.txt), LGPL2.1 (https://github.com/iustin/pyx‐
2462 attr/blob/master/COPYING) and GPLv2+ (http://git.savan‐
2463 nah.nongnu.org/cgit/attr.git/tree/doc/COPYING) respectively
2464 Misc
2466 • pycryptodomex (https://github.com/Legrandin/pycryptodome)* - For de‐
2467 crypting AES-128 HLS streams and various other data. Licensed under
2468 BSD-2-Clause (https://github.com/Legrandin/pycryptodome/blob/mas‐
2469 ter/LICENSE.rst)
2470 • phantomjs (https://github.com/ariya/phantomjs) - Used in extractors
2472 where javascript needs to be run. Licensed under BSD-3-Clause
2473 (https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
2474 • secretstorage (https://github.com/mitya57/secretstorage) - For
2476 --cookies-from-browser to access the Gnome keyring while decrypting
2477 cookies of Chromium-based browsers on Linux. Licensed under
2478 BSD-3-Clause (https://github.com/mitya57/secretstorage/blob/mas‐
2479 ter/LICENSE)
2480 • Any external downloader that you want to use with --downloader
2482 Deprecated
2484 • avconv and avprobe (https://www.libav.org) - Now deprecated alterna‐
2485 tive to ffmpeg. License depends on the build (https://libav.org/le‐
2486 gal)
2487 • sponskrub (https://github.com/faissaloo/SponSkrub) - For using the
2489 now deprecated sponskrub options. Licensed under GPLv3+
2490 (https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
2491 • rtmpdump (http://rtmpdump.mplayerhq.hu) - For downloading rtmp
2493 streams. ffmpeg can be used instead with --downloader ffmpeg. Li‐
2494 censed under GPLv2+ (http://rtmpdump.mplayerhq.hu)
2495 • mplayer (http://mplayerhq.hu/design7/info.html) or mpv
2497 (https://mpv.io) - For downloading rstp/mms streams. ffmpeg can be
2498 used instead with --downloader ffmpeg. Licensed under GPLv2+
2499 (https://github.com/mpv-player/mpv/blob/master/Copyright)
2500 To use or redistribute the dependencies, you must agree to their re‐
2502 spective licensing terms.
2503 The standalone release binaries are built with the Python interpreter
2505 and the packages marked with * included.
2506 If you do not have the necessary dependencies for a task you are at‐
2508 tempting, yt-dlp will warn you. All the currently available dependen‐
2509 cies are visible at the top of the --verbose output
2510 COMPILE
2512 Standalone PyInstaller Builds
2513 To build the standalone executable, you must have Python and pyin‐
2514 staller (plus any of yt-dlp’s optional dependencies if needed). Once
2515 you have all the necessary dependencies installed, simply run
2516 pyinst.py. The executable will be built for the same architecture
2517 (x86/ARM, 32/64 bit) as the Python used.
2518 python3 -m pip install -U pyinstaller -r requirements.txt
2520 python3 devscripts/make_lazy_extractors.py
2521 python3 pyinst.py
2522 On some systems, you may need to use py or python instead of python3.
2524 pyinst.py accepts any arguments that can be passed to pyinstaller, such
2526 as --onefile/-F or --onedir/-D, which is further documented here
2527 (https://pyinstaller.org/en/stable/usage.html#what-to-generate).
2528 Note: Pyinstaller versions below 4.4 do not support
2530 (https://github.com/pyinstaller/pyinstaller#requirements-and-tested-
2531 platforms) Python installed from the Windows store without using a vir‐
2532 tual environment.
2533 Important: Running pyinstaller directly without using pyinst.py is not
2535 officially supported. This may or may not work correctly.
2536 Platform-independent Binary (UNIX)
2538 You will need the build tools python (3.7+), zip, make (GNU), pandoc*
2539 and pytest*.
2540 After installing these, simply run make.
2542 You can also run make yt-dlp instead to compile only the binary without
2544 updating any of the additional files. (The build tools marked with *
2545 are not needed for this)
2546 Standalone Py2Exe Builds (Windows)
2548 While we provide the option to build with py2exe
2549 (https://www.py2exe.org), it is recommended to build using PyInstaller
2550 instead since the py2exe builds cannot contain pycryptodomex/certifi
2551 and needs VC++14 on the target computer to run.
2552 If you wish to build it anyway, install Python and py2exe, and then
2554 simply run setup.py py2exe
2555 py -m pip install -U py2exe -r requirements.txt
2557 py devscripts/make_lazy_extractors.py
2558 py setup.py py2exe
2559 Related scripts
2561 • devscripts/update-version.py - Update the version number based on
2562 current date.
2563 • devscripts/set-variant.py - Set the build variant of the executable.
2565 • devscripts/make_changelog.py - Create a markdown changelog using
2567 short commit messages and update CONTRIBUTORS file.
2568 • devscripts/make_lazy_extractors.py - Create lazy extractors. Running
2570 this before building the binaries (any variant) will improve their
2571 startup performance. Set the environment variable YTDLP_NO_LAZY_EX‐
2572 TRACTORS=1 if you wish to forcefully disable lazy extractor loading.
2573 Note: See their --help for more info.
2575 Forking the project
2577 If you fork the project on GitHub, you can run your fork’s build work‐
2578 flow to automatically build the selected version(s) as artifacts. Al‐
2579 ternatively, you can run the release workflow or enable the nightly
2580 workflow to create full (pre-)releases.
2581
2583 Note that all plugins are imported even if not invoked, and that there
2584 are no checks performed on plugin code. Use plugins at your own risk
2585 and only if you trust the code!
2586 Plugins can be of <type>s extractor or postprocessor. - Extractor
2588 plugins do not need to be enabled from the CLI and are automatically
2589 invoked when the input URL is suitable for it. - Extractor plugins
2590 take priority over builtin extractors. - Postprocessor plugins can be
2591 invoked using --use-postprocessor NAME.
2592 Plugins are loaded from the namespace packages yt_dlp_plugins.extractor
2594 and yt_dlp_plugins.postprocessor.
2595 In other words, the file structure on the disk looks something like:
2597 yt_dlp_plugins/
2599 extractor/
2600 myplugin.py
2601 postprocessor/
2602 myplugin.py
2603 yt-dlp looks for these yt_dlp_plugins namespace folders in many loca‐
2605 tions (see below) and loads in plugins from all of them.
2606 See the wiki for some known plugins (https://github.com/yt-dlp/yt-
2608 dlp/wiki/Plugins)
2609 Installing Plugins
2611 Plugins can be installed using various methods and locations.
2612 1. Configuration directories: Plugin packages (containing a
2614 yt_dlp_plugins namespace folder) can be dropped into the following
2615 standard configuration locations:
2616 • User Plugins
2618 • ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plug‐
2620 ins/ (recommended on Linux/macOS)
2621 • ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plug‐
2623 ins/
2624 • ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/ (rec‐
2626 ommended on Windows)
2627 • ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2629 • ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
2631 • ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2633 • System Plugins
2635 • /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
2637 • /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2639 2. Executable location: Plugin packages can similarly be installed in a
2641 yt-dlp-plugins directory under the executable location (recommended
2642 for portable installations):
2643 • Binary: where <root-dir>/yt-dlp.exe, <root-dir>/yt-dlp-plug‐
2645 ins/<package name>/yt_dlp_plugins/
2646 • Source: where <root-dir>/yt_dlp/__main__.py, <root-dir>/yt-dlp-
2648 plugins/<package name>/yt_dlp_plugins/
2649 3. pip and other locations in PYTHONPATH
2651 • Plugin packages can be installed and managed using pip. See yt-
2653 dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-plug‐
2654 ins) for an example.
2655 • Note: plugin files between plugin packages installed with pip
2657 must have unique filenames.
2658 • Any path in PYTHONPATH is searched in for the yt_dlp_plugins
2660 namespace folder.
2661 • Note: This does not apply for Pyinstaller/py2exe builds.
2663 .zip, .egg and .whl archives containing a yt_dlp_plugins namespace
2665 folder in their root are also supported as plugin packages. *
2666 e.g. ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip where myplug‐
2667 inpkg.zip contains yt_dlp_plugins/<type>/myplugin.py
2668 Run yt-dlp with --verbose to check if the plugin has been loaded.
2670 Developing Plugins
2672 See the yt-dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-
2673 plugins) repo for a template plugin package and the Plugin Development
2674 (https://github.com/yt-dlp/yt-dlp/wiki/Plugin-Development) section of
2675 the wiki for a plugin development guide.
2676 All public classes with a name ending in IE/PP are imported from each
2678 file for extractors and postprocessors repectively. This respects un‐
2679 derscore prefix (e.g. _MyBasePluginIE is private) and __all__. Modules
2680 can similarly be excluded by prefixing the module name with an under‐
2681 score (e.g. _myplugin.py).
2682 To replace an existing extractor with a subclass of one, set the plug‐
2684 in_name class keyword argument (e.g. class MyPluginIE(ABuiltInIE, plug‐
2685 in_name='myplugin') will replace ABuiltInIE with MyPluginIE). Since
2686 the extractor replaces the parent, you should exclude the subclass ex‐
2687 tractor from being imported separately by making it private using one
2688 of the methods described above.
2689 If you are a plugin author, add yt-dlp-plugins (https://github.com/top‐
2691 ics/yt-dlp-plugins) as a topic to your repository for discoverability.
2692 See the Developer Instructions (https://github.com/yt-dlp/yt-
2694 dlp/blob/master/CONTRIBUTING.md#developer-instructions) on how to write
2695 and test an extractor.
2696
2698 yt-dlp makes the best effort to be a good command-line program, and
2699 thus should be callable from any programming language.
2700 Your program should avoid parsing the normal stdout since they may
2702 change in future versions. Instead they should use options such as -J,
2703 --print, --progress-template, --exec etc to create console output that
2704 you can reliably reproduce and parse.
2705 From a Python program, you can embed yt-dlp in a more powerful fashion,
2707 like this:
2708 from yt_dlp import YoutubeDL
2710 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2712 with YoutubeDL() as ydl:
2713 ydl.download(URLS)
2714 Most likely, you’ll want to use various options. For a list of options
2716 available, have a look at yt_dlp/YoutubeDL.py or help(yt_dlp.YoutubeDL)
2717 in a Python shell. If you are already familiar with the CLI, you can
2718 use devscripts/cli_to_api.py (https://github.com/yt-dlp/yt-
2719 dlp/blob/master/devscripts/cli_to_api.py) to translate any CLI switches
2720 to YoutubeDL params.
2721 Tip: If you are porting your code from youtube-dl to yt-dlp, one impor‐
2723 tant point to look out for is that we do not guarantee the return value
2724 of YoutubeDL.extract_info to be json serializable, or even be a dictio‐
2725 nary. It will be dictionary-like, but if you want to ensure it is a
2726 serializable dictionary, pass it through YoutubeDL.sanitize_info as
2727 shown in the example below
2728 Embedding examples
2730 Extracting information
2731 import json
2732 import yt_dlp
2733 URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'
2735 # ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
2737 ydl_opts = {}
2738 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2739 info = ydl.extract_info(URL, download=False)
2740 # ℹ️ ydl.sanitize_info makes the info json-serializable
2742 print(json.dumps(ydl.sanitize_info(info)))
2743 Download using an info-json
2745 import yt_dlp
2746 INFO_FILE = 'path/to/video.info.json'
2748 with yt_dlp.YoutubeDL() as ydl:
2750 error_code = ydl.download_with_info_file(INFO_FILE)
2751 print('Some videos failed to download' if error_code
2753 else 'All videos successfully downloaded')
2754 Extract audio
2756 import yt_dlp
2757 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2759 ydl_opts = {
2761 'format': 'm4a/bestaudio/best',
2762 # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
2763 'postprocessors': [{ # Extract audio using ffmpeg
2764 'key': 'FFmpegExtractAudio',
2765 'preferredcodec': 'm4a',
2766 }]
2767 }
2768 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2770 error_code = ydl.download(URLS)
2771 Filter videos
2773 import yt_dlp
2774 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2776 def longer_than_a_minute(info, *, incomplete):
2778 """Download only videos longer than a minute (or with unknown duration)"""
2779 duration = info.get('duration')
2780 if duration and duration < 60:
2781 return 'The video is too short'
2782 ydl_opts = {
2784 'match_filter': longer_than_a_minute,
2785 }
2786 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2788 error_code = ydl.download(URLS)
2789 Adding logger and progress hook
2791 import yt_dlp
2792 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2794 class MyLogger:
2796 def debug(self, msg):
2797 # For compatibility with youtube-dl, both debug and info are passed into debug
2798 # You can distinguish them by the prefix '[debug] '
2799 if msg.startswith('[debug] '):
2800 pass
2801 else:
2802 self.info(msg)
2803 def info(self, msg):
2805 pass
2806 def warning(self, msg):
2808 pass
2809 def error(self, msg):
2811 print(msg)
2812 # ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
2815 def my_hook(d):
2816 if d['status'] == 'finished':
2817 print('Done downloading, now post-processing ...')
2818 ydl_opts = {
2821 'logger': MyLogger(),
2822 'progress_hooks': [my_hook],
2823 }
2824 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2826 ydl.download(URLS)
2827 Add a custom PostProcessor
2829 import yt_dlp
2830 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2832 # ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
2834 class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
2835 def run(self, info):
2836 self.to_screen('Doing stuff')
2837 return [], info
2838 with yt_dlp.YoutubeDL() as ydl:
2841 # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
2842 ydl.add_post_processor(MyCustomPP(), when='pre_process')
2843 ydl.download(URLS)
2844 Use a custom format selector
2846 import yt_dlp
2847 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2849 def format_selector(ctx):
2851 """ Select the best video and the best audio that won't result in an mkv.
2852 NOTE: This is just an example and does not handle all cases """
2853 # formats are already sorted worst to best
2855 formats = ctx.get('formats')[::-1]
2856 # acodec='none' means there is no audio
2858 best_video = next(f for f in formats
2859 if f['vcodec'] != 'none' and f['acodec'] == 'none')
2860 # find compatible audio extension
2862 audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
2863 # vcodec='none' means there is no video
2864 best_audio = next(f for f in formats if (
2865 f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))
2866 # These are the minimum required fields for a merged format
2868 yield {
2869 'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
2870 'ext': best_video['ext'],
2871 'requested_formats': [best_video, best_audio],
2872 # Must be + separated list of protocols
2873 'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
2874 }
2875 ydl_opts = {
2878 'format': format_selector,
2879 }
2880 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2882 ydl.download(URLS)
2883
2885 • Forked from yt-dlc@f9401f2 (https://github.com/blackjack4494/yt-
2886 dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee) and merged with
2887 youtube-dl@66ab08 (https://github.com/ytdl-org/youtube-dl/com‐
2888 mit/66ab0814c4baa2dc79c2dd5287bc0ad61a37c5b9) (exceptions
2889 (https://github.com/yt-dlp/yt-dlp/issues/21))
2890 • SponsorBlock Integration: You can mark/remove sponsor sections in
2892 YouTube videos by utilizing the SponsorBlock (https://spon‐
2893 sor.ajay.app) API
2894 • Format Sorting: The default format sorting options have been changed
2896 so that higher resolution and better codecs will be now preferred in‐
2897 stead of simply using larger bitrate. Furthermore, you can now spec‐
2898 ify the sort order using -S. This allows for much easier format se‐
2899 lection than what is possible by simply using --format (examples)
2900 • Merged with animelover1984/youtube-dl: You get most of the features
2902 and improvements from animelover1984/youtube-dl
2903 (https://github.com/animelover1984/youtube-dl) including --write-com‐
2904 ments, BiliBiliSearch, BilibiliChannel, Embedding thumbnail in
2905 mp4/ogg/opus, playlist infojson etc. Note that NicoNico livestreams
2906 are not available. See #31 (https://github.com/yt-dlp/yt-
2907 dlp/pull/31) for details.
2908 • YouTube improvements:
2910 • Supports Clips, Stories (ytstories:<channel UCID>), Search (includ‐
2912 ing filters)*, YouTube Music Search, Channel-specific search,
2913 Search prefixes (ytsearch:, ytsearchdate:)*, Mixes, and Feeds (:yt‐
2914 fav, :ytwatchlater, :ytsubs, :ythistory, :ytrec, :ytnotif)
2915 • Fix for n-sig based throttling (https://github.com/ytdl-
2917 org/youtube-dl/issues/29326) *
2918 • Supports some (but not all) age-gated content without cookies
2920 • Download livestreams from the start using --live-from-start (exper‐
2922 imental)
2923 • 255kbps audio is extracted (if available) from YouTube Music when
2925 premium cookies are given
2926 • Channel URLs download all uploads of the channel, including shorts
2928 and live
2929 • Cookies from browser: Cookies can be automatically extracted from all
2931 major web browsers using --cookies-from-browser BROWS‐
2932 ER[+KEYRING][:PROFILE][::CONTAINER]
2933 • Download time range: Videos can be downloaded partially based on ei‐
2935 ther timestamps or chapters using --download-sections
2936 • Split video by chapters: Videos can be split into multiple files
2938 based on chapters using --split-chapters
2939 • Multi-threaded fragment downloads: Download multiple fragments of
2941 m3u8/mpd videos in parallel. Use --concurrent-fragments (-N) option
2942 to set the number of threads used
2943 • Aria2c with HLS/DASH: You can use aria2c as the external downloader
2945 for DASH(mpd) and HLS(m3u8) formats
2946 • New and fixed extractors: Many new extractors have been added and a
2948 lot of existing ones have been fixed. See the changelog or the list
2949 of supported sites
2950 • New MSOs: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
2952 • Subtitle extraction from manifests: Subtitles can be extracted from
2954 streaming media manifests. See commit/be6202f
2955 (https://github.com/yt-dlp/yt-dlp/com‐
2956 mit/be6202f12b97858b9d716e608394b51065d0419f) for details
2957 • Multiple paths and output templates: You can give different output
2959 templates and download paths for different types of files. You can
2960 also set a temporary path where intermediary files are downloaded to
2961 using --paths (-P)
2962 • Portable Configuration: Configuration files are automatically loaded
2964 from the home and root directories. See CONFIGURATION for details
2965 • Output template improvements: Output templates can now have date-time
2967 formatting, numeric offsets, object traversal etc. See output tem‐
2968 plate for details. Even more advanced operations can also be done
2969 with the help of --parse-metadata and --replace-in-metadata
2970 • Other new options: Many new options have been added such as --alias,
2972 --print, --concat-playlist, --wait-for-video, --retry-sleep, --sleep-
2973 requests, --convert-thumbnails, --force-download-archive, --force-
2974 overwrites, --break-match-filter etc
2975 • Improvements: Regex and other operators in --format/--match-filter,
2977 multiple --postprocessor-args and --downloader-args, faster archive
2978 checking, more format selection options, merge multi-video/audio,
2979 multiple --config-locations, --exec at different stages, etc
2980 • Plugins: Extractors and PostProcessors can be loaded from an external
2982 file. See plugins for details
2983 • Self updater: The releases can be updated using yt-dlp -U, and down‐
2985 graded using --update-to if required
2986 • Nightly builds: Automated nightly builds can be used with --update-to
2988 nightly
2989 See changelog or commits (https://github.com/yt-dlp/yt-dlp/commits) for
2991 the full list of changes
2992 Features marked with a * have been back-ported to youtube-dl
2994 Differences in default behavior
2996 Some of yt-dlp’s default options are different from that of youtube-dl
2997 and youtube-dlc:
2998 • yt-dlp supports only Python 3.7+, and may remove support for more
3000 versions as they become EOL (https://devguide.python.org/ver‐
3001 sions/#python-release-cycle); while youtube-dl still supports Python
3002 2.6+ and 3.2+ (https://github.com/ytdl-org/youtube-dl/is‐
3003 sues/30568#issue-1118238743)
3004 • The options --auto-number (-A), --title (-t) and --literal (-l), no
3006 longer work. See removed options for details
3007 • avconv is not supported as an alternative to ffmpeg
3009 • yt-dlp stores config files in slightly different locations to
3011 youtube-dl. See CONFIGURATION for a list of correct locations
3012 • The default output template is %(title)s [%(id)s].%(ext)s. There is
3014 no real reason for this change. This was changed before yt-dlp was
3015 ever made public and now there are no plans to change it back to
3016 %(title)s-%(id)s.%(ext)s. Instead, you may use --compat-options
3017 filename
3018 • The default format sorting is different from youtube-dl and prefers
3020 higher resolution and better codecs rather than higher bitrates. You
3021 can use the --format-sort option to change this to any order you pre‐
3022 fer, or use --compat-options format-sort to use youtube-dl’s sorting
3023 order
3024 • The default format selector is bv*+ba/b. This means that if a com‐
3026 bined video + audio format that is better than the best video-only
3027 format is found, the former will be preferred. Use -f bv+ba/b or
3028 --compat-options format-spec to revert this
3029 • Unlike youtube-dlc, yt-dlp does not allow merging multiple au‐
3031 dio/video streams into one file by default (since this conflicts with
3032 the use of -f bv*+ba). If needed, this feature must be enabled using
3033 --audio-multistreams and --video-multistreams. You can also use
3034 --compat-options multistreams to enable both
3035 • --no-abort-on-error is enabled by default. Use --abort-on-error or
3037 --compat-options abort-on-error to abort on errors instead
3038 • When writing metadata files such as thumbnails, description or infoj‐
3040 son, the same information (if available) is also written for
3041 playlists. Use --no-write-playlist-metafiles or --compat-options no-
3042 playlist-metafiles to not write these files
3043 • --add-metadata attaches the infojson to mkv files in addition to
3045 writing the metadata when used with --write-info-json. Use --no-em‐
3046 bed-info-json or --compat-options no-attach-info-json to revert this
3047 • Some metadata are embedded into different fields when using --add-
3049 metadata as compared to youtube-dl. Most notably, comment field con‐
3050 tains the webpage_url and synopsis contains the description. You can
3051 use --parse-metadata to modify this to your liking or use --compat-
3052 options embed-metadata to revert this
3053 • playlist_index behaves differently when used with options like
3055 --playlist-reverse and --playlist-items. See #302
3056 (https://github.com/yt-dlp/yt-dlp/issues/302) for details. You can
3057 use --compat-options playlist-index if you want to keep the earlier
3058 behavior
3059 • The output of -F is listed in a new format. Use --compat-options
3061 list-formats to revert this
3062 • Live chats (if available) are considered as subtitles. Use --sub-
3064 langs all,-live_chat to download all subtitles except live chat. You
3065 can also use --compat-options no-live-chat to prevent any live
3066 chat/danmaku from downloading
3067 • YouTube channel URLs download all uploads of the channel. To down‐
3069 load only the videos in a specific tab, pass the tab’s URL. If the
3070 channel does not show the requested tab, an error will be raised.
3071 Also, /live URLs raise an error if there are no live videos instead
3072 of silently downloading the entire channel. You may use --compat-op‐
3073 tions no-youtube-channel-redirect to revert all these redirections
3074 • Unavailable videos are also listed for YouTube playlists. Use --com‐
3076 pat-options no-youtube-unavailable-videos to remove this
3077 • The upload dates extracted from YouTube are in UTC when available
3079 (https://github.com/yt-dlp/yt-
3080 dlp/blob/89e4d86171c7b7c997c77d4714542e0383bf0db0/yt_dlp/extrac‐
3081 tor/youtube.py#L3898-L3900). Use --compat-options no-youtube-prefer-
3082 utc-upload-date to prefer the non-UTC upload date.
3083 • If ffmpeg is used as the downloader, the downloading and merging of
3085 formats happen in a single step when possible. Use --compat-options
3086 no-direct-merge to revert this
3087 • Thumbnail embedding in mp4 is done with mutagen if possible. Use
3089 --compat-options embed-thumbnail-atomicparsley to force the use of
3090 AtomicParsley instead
3091 • Some internal metadata such as filenames are removed by default from
3093 the infojson. Use --no-clean-infojson or --compat-options no-clean-
3094 infojson to revert this
3095 • When --embed-subs and --write-subs are used together, the subtitles
3097 are written to disk and also embedded in the media file. You can use
3098 just --embed-subs to embed the subs and automatically delete the sep‐
3099 arate file. See #630 (comment) (https://github.com/yt-dlp/yt-dlp/is‐
3100 sues/630#issuecomment-893659460) for more info. --compat-options no-
3101 keep-subs can be used to revert this
3102 • certifi will be used for SSL root certificates, if installed. If you
3104 want to use system certificates (e.g. self-signed), use --compat-op‐
3105 tions no-certifi
3106 • yt-dlp’s sanitization of invalid characters in filenames is differ‐
3108 ent/smarter than in youtube-dl. You can use --compat-options file‐
3109 name-sanitization to revert to youtube-dl’s behavior
3110 • yt-dlp tries to parse the external downloader outputs into the stan‐
3112 dard progress output if possible (Currently implemented: [STRIKE‐
3113 OUT:aria2c] (https://github.com/yt-dlp/yt-dlp/issues/5931)). You can
3114 use --compat-options no-external-downloader-progress to get the down‐
3115 loader output as-is
3116 • yt-dlp versions between 2021.09.01 and 2023.01.02 applies --match-
3118 filter to nested playlists. This was an unintentional side-effect of
3119 8f18ac (https://github.com/yt-dlp/yt-dlp/com‐
3120 mit/8f18aca8717bb0dd49054555af8d386e5eda3a88) and is fixed in d7b460
3121 (https://github.com/yt-dlp/yt-dlp/com‐
3122 mit/d7b460d0e5fc710950582baed2e3fc616ed98a80). Use --compat-options
3123 playlist-match-filter to revert this
3124 For ease of use, a few more compat options are available:
3126 • --compat-options all: Use all compat options (Do NOT use)
3128 • --compat-options youtube-dl: Same as --compat-options all,-multi‐
3130 streams,-playlist-match-filter
3131 • --compat-options youtube-dlc: Same as --compat-options all,-no-live-
3133 chat,-no-youtube-channel-redirect,-playlist-match-filter
3134 • --compat-options 2021: Same as --compat-options 2022,no-certifi,file‐
3136 name-sanitization,no-youtube-prefer-utc-upload-date
3137 • --compat-options 2022: Same as --compat-options playlist-match-fil‐
3139 ter,no-external-downloader-progress. Use this to enable all future
3140 compat options
3141
3143 These are all the deprecated options and the current alternative to
3144 achieve the same effect
3145 Almost redundant options
3147 While these options are almost the same as their new counterparts,
3148 there are some differences that prevents them being redundant
3149 -j, --dump-json --print "%()j"
3151 -F, --list-formats --print formats_table
3152 --list-thumbnails --print thumbnails_table --print playlist:thumbnails_table
3153 --list-subs --print automatic_captions_table --print subtitles_table
3154 Redundant options
3156 While these options are redundant, they are still expected to be used
3157 due to their ease of use
3158 --get-description --print description
3160 --get-duration --print duration_string
3161 --get-filename --print filename
3162 --get-format --print format
3163 --get-id --print id
3164 --get-thumbnail --print thumbnail
3165 -e, --get-title --print title
3166 -g, --get-url --print urls
3167 --match-title REGEX --match-filter "title ~= (?i)REGEX"
3168 --reject-title REGEX --match-filter "title !~= (?i)REGEX"
3169 --min-views COUNT --match-filter "view_count >=? COUNT"
3170 --max-views COUNT --match-filter "view_count <=? COUNT"
3171 --break-on-reject Use --break-match-filter
3172 --user-agent UA --add-header "User-Agent:UA"
3173 --referer URL --add-header "Referer:URL"
3174 --playlist-start NUMBER -I NUMBER:
3175 --playlist-end NUMBER -I :NUMBER
3176 --playlist-reverse -I ::-1
3177 --no-playlist-reverse Default
3178 --no-colors --color no_color
3179 Not recommended
3181 While these options still work, their use is not recommended since
3182 there are other alternatives to achieve the same
3183 --force-generic-extractor --ies generic,default
3185 --exec-before-download CMD --exec "before_dl:CMD"
3186 --no-exec-before-download --no-exec
3187 --all-formats -f all
3188 --all-subs --sub-langs all --write-subs
3189 --print-json -j --no-simulate
3190 --autonumber-size NUMBER Use string formatting, e.g. %(autonumber)03d
3191 --autonumber-start NUMBER Use internal field formatting like %(autonumber+NUMBER)s
3192 --id -o "%(id)s.%(ext)s"
3193 --metadata-from-title FORMAT --parse-metadata "%(title)s:FORMAT"
3194 --hls-prefer-native --downloader "m3u8:native"
3195 --hls-prefer-ffmpeg --downloader "m3u8:ffmpeg"
3196 --list-formats-old --compat-options list-formats (Alias: --no-list-formats-as-table)
3197 --list-formats-as-table --compat-options -list-formats [Default] (Alias: --no-list-formats-old)
3198 --youtube-skip-dash-manifest --extractor-args "youtube:skip=dash" (Alias: --no-youtube-include-dash-manifest)
3199 --youtube-skip-hls-manifest --extractor-args "youtube:skip=hls" (Alias: --no-youtube-include-hls-manifest)
3200 --youtube-include-dash-manifest Default (Alias: --no-youtube-skip-dash-manifest)
3201 --youtube-include-hls-manifest Default (Alias: --no-youtube-skip-hls-manifest)
3202 --geo-bypass --xff "default"
3203 --no-geo-bypass --xff "never"
3204 --geo-bypass-country CODE --xff CODE
3205 --geo-bypass-ip-block IP_BLOCK --xff IP_BLOCK
3206 Developer options
3208 These options are not intended to be used by the end-user
3209 --test Download only part of video for testing extractors
3211 --load-pages Load pages dumped by --write-pages
3212 --youtube-print-sig-code For testing youtube signatures
3213 --allow-unplayable-formats List unplayable formats also
3214 --no-allow-unplayable-formats Default
3215 Old aliases
3217 These are aliases that are no longer documented for various reasons
3218 --avconv-location --ffmpeg-location
3220 --clean-infojson --clean-info-json
3221 --cn-verification-proxy URL --geo-verification-proxy URL
3222 --dump-headers --print-traffic
3223 --dump-intermediate-pages --dump-pages
3224 --force-write-download-archive --force-write-archive
3225 --load-info --load-info-json
3226 --no-clean-infojson --no-clean-info-json
3227 --no-split-tracks --no-split-chapters
3228 --no-write-srt --no-write-subs
3229 --prefer-unsecure --prefer-insecure
3230 --rate-limit RATE --limit-rate RATE
3231 --split-tracks --split-chapters
3232 --srt-lang LANGS --sub-langs LANGS
3233 --trim-file-names LENGTH --trim-filenames LENGTH
3234 --write-srt --write-subs
3235 --yes-overwrites --force-overwrites
3236 Sponskrub Options
3238 Support for SponSkrub (https://github.com/faissaloo/SponSkrub) has been
3239 deprecated in favor of the --sponsorblock options
3240 --sponskrub --sponsorblock-mark all
3242 --no-sponskrub --no-sponsorblock
3243 --sponskrub-cut --sponsorblock-remove all
3244 --no-sponskrub-cut --sponsorblock-remove -all
3245 --sponskrub-force Not applicable
3246 --no-sponskrub-force Not applicable
3247 --sponskrub-location Not applicable
3248 --sponskrub-args Not applicable
3249 No longer supported
3251 These options may no longer work as intended
3252 --prefer-avconv avconv is not officially supported by yt-dlp (Alias: --no-prefer-ffmpeg)
3254 --prefer-ffmpeg Default (Alias: --no-prefer-avconv)
3255 -C, --call-home Not implemented
3256 --no-call-home Default
3257 --include-ads No longer supported
3258 --no-include-ads Default
3259 --write-annotations No supported site has annotations now
3260 --no-write-annotations Default
3261 --compat-options seperate-video-versions No longer needed
3262 Removed
3264 These options were deprecated since 2014 and have now been entirely re‐
3265 moved
3266 -A, --auto-number -o "%(autonumber)s-%(id)s.%(ext)s"
3268 -t, -l, --title, --literal -o "%(title)s-%(id)s.%(ext)s"
3269
3271 See CONTRIBUTING.md for instructions on Opening an Issue and Contribut‐
3272 ing code to the project
3273
3275 See the Wiki (https://github.com/yt-dlp/yt-dlp/wiki) for more informa‐
3276 tion
3277 yt-dlp(1)