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); e.g.
62 --ies "holodex.*,end,youtube". Prefix the name with a "-" to
63 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}"
132 creates options "--get-audio" and "-X" that takes an argument
133 (ARG0) and expands to "-S=aext:ARG0,abr -x --audio-format ARG0".
134 All defined aliases are listed in the --help output. Alias op‐
135 tions can trigger more aliases; so be careful to avoid defining
136 recursive options. As a safety measure, each alias may be trig‐
137 gered a maximum of 100 times. This option can be used multiple
138 times
139 Network Options:
141 --proxy URL
142 Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS
143 proxy, specify a proper scheme, e.g. socks5://us‐
144 er:pass@127.0.0.1:1080/. Pass in an empty string (--proxy "")
145 for direct connection
146 --socket-timeout SECONDS
148 Time to wait before giving up, in seconds
149 --source-address IP
151 Client-side IP address to bind to
152 -4, --force-ipv4
154 Make all connections via IPv4
155 -6, --force-ipv6
157 Make all connections via IPv6
158 --enable-file-urls
160 Enable file:// URLs. This is disabled by default for security
161 reasons.
162 Geo-restriction:
164 --geo-verification-proxy URL
165 Use this proxy to verify the IP address for some geo-restricted
166 sites. The default proxy specified by --proxy (or none, if the
167 option is not present) is used for the actual downloading
168 --xff VALUE
170 How to fake X-Forwarded-For HTTP header to try bypassing geo‐
171 graphic restriction. One of "default" (only when known to be
172 useful), "never", an IP block in CIDR notation, or a two-letter
173 ISO 3166-2 country code
174 Video Selection:
176 -I, --playlist-items ITEM_SPEC
177 Comma separated playlist_index of the items to download. You
178 can specify a range using "[START]:[STOP][:STEP]". For backward
179 compatibility, START-STOP is also supported. Use negative in‐
180 dices to count from the right and negative STEP to download in
181 reverse order. E.g. "-I 1:3,7,-5::2" used on a playlist of
182 size 15 will download the items at index 1,2,3,7,11,13,15
183 --min-filesize SIZE
185 Abort download if filesize is smaller than SIZE, e.g. 50k or
186 44.6M
187 --max-filesize SIZE
189 Abort download if filesize is larger than SIZE, e.g. 50k or
190 44.6M
191 --date DATE
193 Download only videos uploaded on this date. The date can be
194 "YYYYMMDD" or in the format [now|today|yester‐
195 day][-N[day|week|month|year]]. E.g. "--date today-2weeks"
196 downloads only videos uploaded on the same day two weeks ago
197 --datebefore DATE
199 Download only videos uploaded on or before this date. The date
200 formats accepted is the same as --date
201 --dateafter DATE
203 Download only videos uploaded on or after this date. The date
204 formats accepted is the same as --date
205 --match-filters FILTER
207 Generic video filter. Any "OUTPUT TEMPLATE" field can be com‐
208 pared with a number or a string using the operators defined in
209 "Filtering Formats". You can also simply specify a field to
210 match if the field is present, use "!field" to check if the
211 field is not present, and "&" to check multiple conditions. Use
212 a "" to escape "&" or quotes if needed. If used multiple times,
213 the filter matches if atleast one of the conditions are met.
214 E.g. --match-filter !is_live --match-filter "like_count>?100 &
215 description~='(?i)& dogs" matches only videos that are not live
216 OR those that have a like count more than 100 (or the like field
217 is not available) and also has a description that contains the
218 phrase "cats & dogs" (caseless). Use "--match-filter -" to in‐
219 teractively ask whether to download each video
220 --no-match-filters
222 Do not use any --match-filter (default)
223 --break-match-filters FILTER
225 Same as "--match-filters" but stops the download process when a
226 video is rejected
227 --no-break-match-filters
229 Do not use any --break-match-filters (default)
230 --no-playlist
232 Download only the video, if the URL refers to a video and a
233 playlist
234 --yes-playlist
236 Download the playlist, if the URL refers to a video and a
237 playlist
238 --age-limit YEARS
240 Download only videos suitable for the given age
241 --download-archive FILE
243 Download only videos not listed in the archive file. Record the
244 IDs of all downloaded videos in it
245 --no-download-archive
247 Do not use archive file (default)
248 --max-downloads NUMBER
250 Abort after downloading NUMBER files
251 --break-on-existing
253 Stop the download process when encountering a file that is in
254 the archive
255 --break-per-input
257 Alters --max-downloads, --break-on-existing, --break-match-fil‐
258 ter, and autonumber to reset per input URL
259 --no-break-per-input
261 --break-on-existing and similar options terminates the entire
262 download queue
263 --skip-playlist-after-errors N
265 Number of allowed failures until the rest of the playlist is
266 skipped
267 Download Options:
269 -N, --concurrent-fragments N
270 Number of fragments of a dash/hlsnative video that should be
271 downloaded concurrently (default is 1)
272 -r, --limit-rate RATE
274 Maximum download rate in bytes per second, e.g. 50K or 4.2M
275 --throttled-rate RATE
277 Minimum download rate in bytes per second below which throttling
278 is assumed and the video data is re-extracted, e.g. 100K
279 -R, --retries RETRIES
281 Number of retries (default is 10), or "infinite"
282 --file-access-retries RETRIES
284 Number of times to retry on file access error (default is 3), or
285 "infinite"
286 --fragment-retries RETRIES
288 Number of retries for a fragment (default is 10), or "infinite"
289 (DASH, hlsnative and ISM)
290 --retry-sleep [TYPE:]EXPR
292 Time to sleep between retries in seconds (optionally) prefixed
293 by the type of retry (http (default), fragment, file_access, ex‐
294 tractor) to apply the sleep to. EXPR can be a number, lin‐
295 ear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]]. This op‐
296 tion can be used multiple times to set the sleep for the differ‐
297 ent retry types, e.g. --retry-sleep linear=1::2 --retry-sleep
298 fragment:exp=1:20
299 --skip-unavailable-fragments
301 Skip unavailable fragments for DASH, hlsnative and ISM downloads
302 (default) (Alias: --no-abort-on-unavailable-fragments)
303 --abort-on-unavailable-fragments
305 Abort download if a fragment is unavailable (Alias: --no-skip-
306 unavailable-fragments)
307 --keep-fragments
309 Keep downloaded fragments on disk after downloading is finished
310 --no-keep-fragments
312 Delete downloaded fragments after downloading is finished (de‐
313 fault)
314 --buffer-size SIZE
316 Size of download buffer, e.g. 1024 or 16K (default is 1024)
317 --resize-buffer
319 The buffer size is automatically resized from an initial value
320 of --buffer-size (default)
321 --no-resize-buffer
323 Do not automatically adjust the buffer size
324 --http-chunk-size SIZE
326 Size of a chunk for chunk-based HTTP downloading, e.g. 10485760
327 or 10M (default is disabled). May be useful for bypassing band‐
328 width throttling imposed by a webserver (experimental)
329 --playlist-random
331 Download playlist videos in random order
332 --lazy-playlist
334 Process entries in the playlist as they are received. This dis‐
335 ables n_entries, --playlist-random and --playlist-reverse
336 --no-lazy-playlist
338 Process videos in the playlist only after the entire playlist is
339 parsed (default)
340 --xattr-set-filesize
342 Set file xattribute ytdl.filesize with expected file size
343 --hls-use-mpegts
345 Use the mpegts container for HLS videos; allowing some players
346 to play the video while downloading, and reducing the chance of
347 file corruption if download is interrupted. This is enabled by
348 default for live streams
349 --no-hls-use-mpegts
351 Do not use the mpegts container for HLS videos. This is default
352 when not downloading live streams
353 --download-sections REGEX
355 Download only chapters that match the regular expression. A ""
356 prefix denotes time-range instead of chapter. Negative time‐
357 stamps are calculated from the end. "from-url" can be used to
358 download between the "start_time" and "end_time" extracted from
359 the URL. Needs ffmpeg. This option can be used multiple times
360 to download multiple sections, e.g. --download-sections
361 "*10:15-inf" --download-sections "intro"
362 --downloader [PROTO:]NAME
364 Name or path of the external downloader to use (optionally) pre‐
365 fixed by the protocols (http, ftp, m3u8, dash, rstp, rtmp, mms)
366 to use it for. Currently supports native, aria2c, avconv, axel,
367 curl, ffmpeg, httpie, wget. You can use this option multiple
368 times to set different downloaders for different protocols.
369 E.g. --downloader aria2c --downloader "dash,m3u8:native" will
370 use aria2c for http/ftp downloads, and the native downloader for
371 dash/m3u8 downloads (Alias: --external-downloader)
372 --downloader-args NAME:ARGS
374 Give these arguments to the external downloader. Specify the
375 downloader name and the arguments separated by a colon ":". For
376 ffmpeg, arguments can be passed to different positions using the
377 same syntax as --postprocessor-args. You can use this option
378 multiple times to give different arguments to different down‐
379 loaders (Alias: --external-downloader-args)
380 Filesystem Options:
382 -a, --batch-file FILE
383 File containing URLs to download ("-" for stdin), one URL per
384 line. Lines starting with "#", ";" or "]" are considered as
385 comments and ignored
386 --no-batch-file
388 Do not read URLs from batch file (default)
389 -P, --paths [TYPES:]PATH
391 The paths where the files should be downloaded. Specify the
392 type of file and the path separated by a colon ":". All the
393 same TYPES as --output are supported. Additionally, you can al‐
394 so provide "home" (default) and "temp" paths. All intermediary
395 files are first downloaded to the temp path and then the final
396 files are moved over to the home path after download is fin‐
397 ished. This option is ignored if --output is an absolute path
398 -o, --output [TYPES:]TEMPLATE
400 Output filename template; see "OUTPUT TEMPLATE" for details
401 --output-na-placeholder TEXT
403 Placeholder for unavailable fields in "OUTPUT TEMPLATE" (de‐
404 fault: "NA")
405 --restrict-filenames
407 Restrict filenames to only ASCII characters, and avoid "&" and
408 spaces in filenames
409 --no-restrict-filenames
411 Allow Unicode characters, "&" and spaces in filenames (default)
412 --windows-filenames
414 Force filenames to be Windows-compatible
415 --no-windows-filenames
417 Make filenames Windows-compatible only if using Windows (de‐
418 fault)
419 --trim-filenames LENGTH
421 Limit the filename length (excluding extension) to the specified
422 number of characters
423 -w, --no-overwrites
425 Do not overwrite any files
426 --force-overwrites
428 Overwrite all video and metadata files. This option includes
429 --no-continue
430 --no-force-overwrites
432 Do not overwrite the video, but overwrite related files (de‐
433 fault)
434 -c, --continue
436 Resume partially downloaded files/fragments (default)
437 --no-continue
439 Do not resume partially downloaded fragments. If the file is
440 not fragmented, restart download of the entire file
441 --part Use .part files instead of writing directly into output file
443 (default)
444 --no-part
446 Do not use .part files - write directly into output file
447 --mtime
449 Use the Last-modified header to set the file modification time
450 (default)
451 --no-mtime
453 Do not use the Last-modified header to set the file modification
454 time
455 --write-description
457 Write video description to a .description file
458 --no-write-description
460 Do not write video description (default)
461 --write-info-json
463 Write video metadata to a .info.json file (this may contain per‐
464 sonal information)
465 --no-write-info-json
467 Do not write video metadata (default)
468 --write-playlist-metafiles
470 Write playlist metadata in addition to the video metadata when
471 using --write-info-json, --write-description etc. (default)
472 --no-write-playlist-metafiles
474 Do not write playlist metadata when using --write-info-json,
475 --write-description etc.
476 --clean-info-json
478 Remove some internal metadata such as filenames from the infoj‐
479 son (default)
480 --no-clean-info-json
482 Write all fields to the infojson
483 --write-comments
485 Retrieve video comments to be placed in the infojson. The com‐
486 ments are fetched even without this option if the extraction is
487 known to be quick (Alias: --get-comments)
488 --no-write-comments
490 Do not retrieve video comments unless the extraction is known to
491 be quick (Alias: --no-get-comments)
492 --load-info-json FILE
494 JSON file containing the video information (created with the
495 "--write-info-json" option)
496 --cookies FILE
498 Netscape formatted file to read cookies from and dump cookie jar
499 in
500 --no-cookies
502 Do not read/dump cookies from/to file (default)
503 --cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]
505 The name of the browser to load cookies from. Currently sup‐
506 ported browsers are: brave, chrome, chromium, edge, firefox,
507 opera, safari, vivaldi. Optionally, the KEYRING used for de‐
508 crypting Chromium cookies on Linux, the name/path of the PROFILE
509 to load cookies from, and the CONTAINER name (if Firefox)
510 ("none" for no container) can be given with their respective
511 seperators. By default, all containers of the most recently ac‐
512 cessed profile are used. Currently supported keyrings are: ba‐
513 sictext, gnomekeyring, kwallet, kwallet5, kwallet6
514 --no-cookies-from-browser
516 Do not load cookies from browser (default)
517 --cache-dir DIR
519 Location in the filesystem where yt-dlp can store some download‐
520 ed information (such as client ids and signatures) permanently.
521 By default ${XDG_CACHE_HOME}/yt-dlp
522 --no-cache-dir
524 Disable filesystem caching
525 --rm-cache-dir
527 Delete all filesystem cache files
528 Thumbnail Options:
530 --write-thumbnail
531 Write thumbnail image to disk
532 --no-write-thumbnail
534 Do not write thumbnail image to disk (default)
535 --write-all-thumbnails
537 Write all thumbnail image formats to disk
538 --list-thumbnails
540 List available thumbnails of each video. Simulate unless --no-
541 simulate is used
542 Internet Shortcut Options:
544 --write-link
545 Write an internet shortcut file, depending on the current plat‐
546 form (.url, .webloc or .desktop). The URL may be cached by the
547 OS
548 --write-url-link
550 Write a .url Windows internet shortcut. The OS caches the URL
551 based on the file path
552 --write-webloc-link
554 Write a .webloc macOS internet shortcut
555 --write-desktop-link
557 Write a .desktop Linux internet shortcut
558 Verbosity and Simulation Options:
560 -q, --quiet
561 Activate quiet mode. If used with --verbose, print the log to
562 stderr
563 --no-quiet
565 Deactivate quiet mode. (Default)
566 --no-warnings
568 Ignore warnings
569 -s, --simulate
571 Do not download the video and do not write anything to disk
572 --no-simulate
574 Download the video even if printing/listing options are used
575 --ignore-no-formats-error
577 Ignore "No video formats" error. Useful for extracting metadata
578 even if the videos are not actually available for download (ex‐
579 perimental)
580 --no-ignore-no-formats-error
582 Throw error when no downloadable video formats are found (de‐
583 fault)
584 --skip-download
586 Do not download the video but write all related files (Alias:
587 --no-download)
588 -O, --print [WHEN:]TEMPLATE
590 Field name or output template to print to screen, optionally
591 prefixed with when to print it, separated by a ":". Supported
592 values of "WHEN" are the same as that of --use-postprocessor
593 (default: video). Implies --quiet. Implies --simulate unless
594 --no-simulate or later stages of WHEN are used. This option can
595 be used multiple times
596 --print-to-file [WHEN:]TEMPLATE FILE
598 Append given template to the file. The values of WHEN and TEM‐
599 PLATE are same as that of --print. FILE uses the same syntax as
600 the output template. This option can be used multiple times
601 -j, --dump-json
603 Quiet, but print JSON information for each video. Simulate un‐
604 less --no-simulate is used. See "OUTPUT TEMPLATE" for a de‐
605 scription of available keys
606 -J, --dump-single-json
608 Quiet, but print JSON information for each url or infojson
609 passed. Simulate unless --no-simulate is used. If the URL
610 refers to a playlist, the whole playlist information is dumped
611 in a single line
612 --force-write-archive
614 Force download archive entries to be written as far as no errors
615 occur, even if -s or another simulation option is used (Alias:
616 --force-download-archive)
617 --newline
619 Output progress bar as new lines
620 --no-progress
622 Do not print progress bar
623 --progress
625 Show progress bar, even if in quiet mode
626 --console-title
628 Display progress in console titlebar
629 --progress-template [TYPES:]TEMPLATE
631 Template for progress outputs, optionally prefixed with one of
632 "download:" (default), "download-title:" (the console title),
633 "postprocess:", or "postprocess-title:". The video's fields are
634 accessible under the "info" key and the progress attributes are
635 accessible under "progress" key. E.g. --console-title
636 --progress-template "download-title:%(in‐
637 fo.id)s-%(progress.eta)s"
638 -v, --verbose
640 Print various debugging information
641 --dump-pages
643 Print downloaded pages encoded using base64 to debug problems
644 (very verbose)
645 --write-pages
647 Write downloaded intermediary pages to files in the current di‐
648 rectory to debug problems
649 --print-traffic
651 Display sent and read HTTP traffic
652 Workarounds:
654 --encoding ENCODING
655 Force the specified encoding (experimental)
656 --legacy-server-connect
658 Explicitly allow HTTPS connection to servers that do not support
659 RFC 5746 secure renegotiation
660 --no-check-certificates
662 Suppress HTTPS certificate validation
663 --prefer-insecure
665 Use an unencrypted connection to retrieve information about the
666 video (Currently supported only for YouTube)
667 --add-headers FIELD:VALUE
669 Specify a custom HTTP header and its value, separated by a colon
670 ":". You can use this option multiple times
671 --bidi-workaround
673 Work around terminals that lack bidirectional text support. Re‐
674 quires bidiv or fribidi executable in PATH
675 --sleep-requests SECONDS
677 Number of seconds to sleep between requests during data extrac‐
678 tion
679 --sleep-interval SECONDS
681 Number of seconds to sleep before each download. This is the
682 minimum time to sleep when used along with --max-sleep-interval
683 (Alias: --min-sleep-interval)
684 --max-sleep-interval SECONDS
686 Maximum number of seconds to sleep. Can only be used along with
687 --min-sleep-interval
688 --sleep-subtitles SECONDS
690 Number of seconds to sleep before each subtitle download
691 Video Format Options:
693 -f, --format FORMAT
694 Video format code, see "FORMAT SELECTION" for more details
695 -S, --format-sort SORTORDER
697 Sort the formats by the fields given, see "Sorting Formats" for
698 more details
699 --format-sort-force
701 Force user specified sort order to have precedence over all
702 fields, see "Sorting Formats" for more details (Alias: --S-
703 force)
704 --no-format-sort-force
706 Some fields have precedence over the user specified sort order
707 (default)
708 --video-multistreams
710 Allow multiple video streams to be merged into a single file
711 --no-video-multistreams
713 Only one video stream is downloaded for each output file (de‐
714 fault)
715 --audio-multistreams
717 Allow multiple audio streams to be merged into a single file
718 --no-audio-multistreams
720 Only one audio stream is downloaded for each output file (de‐
721 fault)
722 --prefer-free-formats
724 Prefer video formats with free containers over non-free ones of
725 same quality. Use with "-S ext" to strictly prefer free con‐
726 tainers irrespective of quality
727 --no-prefer-free-formats
729 Don't give any special preference to free containers (default)
730 --check-formats
732 Make sure formats are selected only from those that are actually
733 downloadable
734 --check-all-formats
736 Check all formats for whether they are actually downloadable
737 --no-check-formats
739 Do not check that the formats are actually downloadable
740 -F, --list-formats
742 List available formats of each video. Simulate unless --no-sim‐
743 ulate is used
744 --merge-output-format FORMAT
746 Containers that may be used when merging formats, separated by
747 "/", e.g. "mp4/mkv". Ignored if no merge is required. (cur‐
748 rently supported: avi, flv, mkv, mov, mp4, webm)
749 Subtitle Options:
751 --write-subs
752 Write subtitle file
753 --no-write-subs
755 Do not write subtitle file (default)
756 --write-auto-subs
758 Write automatically generated subtitle file (Alias: --write-au‐
759 tomatic-subs)
760 --no-write-auto-subs
762 Do not write auto-generated subtitles (default) (Alias: --no-
763 write-automatic-subs)
764 --list-subs
766 List available subtitles of each video. Simulate unless --no-
767 simulate is used
768 --sub-format FORMAT
770 Subtitle format; accepts formats preference, e.g. "srt" or
771 "ass/srt/best"
772 --sub-langs LANGS
774 Languages of the subtitles to download (can be regex) or "all"
775 separated by commas, e.g. --sub-langs "en.*,ja". You can pre‐
776 fix the language code with a "-" to exclude it from the request‐
777 ed languages, e.g. --sub-langs all,-live_chat. Use --list-subs
778 for a list of available language tags
779 Authentication Options:
781 -u, --username USERNAME
782 Login with this account ID
783 -p, --password PASSWORD
785 Account password. If this option is left out, yt-dlp will ask
786 interactively
787 -2, --twofactor TWOFACTOR
789 Two-factor authentication code
790 -n, --netrc
792 Use .netrc authentication data
793 --netrc-location PATH
795 Location of .netrc authentication data; either the path or its
796 containing directory. Defaults to ~/.netrc
797 --netrc-cmd NETRC_CMD
799 Command to execute to get the credentials for an extractor.
800 --video-password PASSWORD
802 Video password (vimeo, youku)
803 --ap-mso MSO
805 Adobe Pass multiple-system operator (TV provider) identifier,
806 use --ap-list-mso for a list of available MSOs
807 --ap-username USERNAME
809 Multiple-system operator account login
810 --ap-password PASSWORD
812 Multiple-system operator account password. If this option is
813 left out, yt-dlp will ask interactively
814 --ap-list-mso
816 List all supported multiple-system operators
817 --client-certificate CERTFILE
819 Path to client certificate file in PEM format. May include the
820 private key
821 --client-certificate-key KEYFILE
823 Path to private key file for client certificate
824 --client-certificate-password PASSWORD
826 Password for client certificate private key, if encrypted. If
827 not provided, and the key is encrypted, yt-dlp will ask interac‐
828 tively
829 Post-Processing Options:
831 -x, --extract-audio
832 Convert video files to audio-only files (requires ffmpeg and ff‐
833 probe)
834 --audio-format FORMAT
836 Format to convert the audio to when -x is used. (currently sup‐
837 ported: best (default), aac, alac, flac, m4a, mp3, opus, vorbis,
838 wav). You can specify multiple rules using similar syntax as
839 --remux-video
840 --audio-quality QUALITY
842 Specify ffmpeg audio quality to use when converting the audio
843 with -x. Insert a value between 0 (best) and 10 (worst) for VBR
844 or a specific bitrate like 128K (default 5)
845 --remux-video FORMAT
847 Remux the video into another container if necessary (currently
848 supported: avi, flv, gif, mkv, mov, mp4, webm, aac, aiff, alac,
849 flac, m4a, mka, mp3, ogg, opus, vorbis, wav). If target con‐
850 tainer does not support the video/audio codec, remuxing will
851 fail. You can specify multiple rules; e.g.
852 "aac>m4a/mov>mp4/mkv" will remux aac to m4a, mov to mp4 and any‐
853 thing else to mkv
854 --recode-video FORMAT
856 Re-encode the video into another format if necessary. The syn‐
857 tax and supported formats are the same as --remux-video
858 --postprocessor-args NAME:ARGS
860 Give these arguments to the postprocessors. Specify the post‐
861 processor/executable name and the arguments separated by a colon
862 ":" to give the argument to the specified postprocessor/exe‐
863 cutable. Supported PP are: Merger, ModifyChapters, SplitChap‐
864 ters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, Em‐
865 bedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsCon‐
866 vertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp and
867 FixupDuration. The supported executables are: AtomicParsley,
868 FFmpeg and FFprobe. You can also specify "PP+EXE:ARGS" to give
869 the arguments to the specified executable only when being used
870 by the specified postprocessor. Additionally, for ffmpeg/ff‐
871 probe, "_i"/"_o" can be appended to the prefix optionally fol‐
872 lowed by a number to pass the argument before the specified in‐
873 put/output file, e.g. --ppa "Merger+ffmpeg_i1:-v quiet". You
874 can use this option multiple times to give different arguments
875 to different postprocessors. (Alias: --ppa)
876 -k, --keep-video
878 Keep the intermediate video file on disk after post-processing
879 --no-keep-video
881 Delete the intermediate video file after post-processing (de‐
882 fault)
883 --post-overwrites
885 Overwrite post-processed files (default)
886 --no-post-overwrites
888 Do not overwrite post-processed files
889 --embed-subs
891 Embed subtitles in the video (only for mp4, webm and mkv videos)
892 --no-embed-subs
894 Do not embed subtitles (default)
895 --embed-thumbnail
897 Embed thumbnail in the video as cover art
898 --no-embed-thumbnail
900 Do not embed thumbnail (default)
901 --embed-metadata
903 Embed metadata to the video file. Also embeds chapters/infojson
904 if present unless --no-embed-chapters/--no-embed-info-json are
905 used (Alias: --add-metadata)
906 --no-embed-metadata
908 Do not add metadata to file (default) (Alias: --no-add-metadata)
909 --embed-chapters
911 Add chapter markers to the video file (Alias: --add-chapters)
912 --no-embed-chapters
914 Do not add chapter markers (default) (Alias: --no-add-chapters)
915 --embed-info-json
917 Embed the infojson as an attachment to mkv/mka video files
918 --no-embed-info-json
920 Do not embed the infojson as an attachment to the video file
921 --parse-metadata [WHEN:]FROM:TO
923 Parse additional metadata like title/artist from other fields;
924 see "MODIFYING METADATA" for details. Supported values of
925 "WHEN" are the same as that of --use-postprocessor (default:
926 pre_process)
927 --replace-in-metadata [WHEN:]FIELDS REGEX REPLACE
929 Replace text in a metadata field using the given regex. This
930 option can be used multiple times. Supported values of "WHEN"
931 are the same as that of --use-postprocessor (default:
932 pre_process)
933 --xattrs
935 Write metadata to the video file's xattrs (using dublin core and
936 xdg standards)
937 --concat-playlist POLICY
939 Concatenate videos in a playlist. One of "never", "always", or
940 "multi_video" (default; only when the videos form a single
941 show). All the video files must have same codecs and number of
942 streams to be concatable. The "pl_video:" prefix can be used
943 with "--paths" and "--output" to set the output filename for the
944 concatenated files. See "OUTPUT TEMPLATE" for details
945 --fixup POLICY
947 Automatically correct known faults of the file. One of never
948 (do nothing), warn (only emit a warning), detect_or_warn (the
949 default; fix file if we can, warn otherwise), force (try fixing
950 even if file already exists)
951 --ffmpeg-location PATH
953 Location of the ffmpeg binary; either the path to the binary or
954 its containing directory
955 --exec [WHEN:]CMD
957 Execute a command, optionally prefixed with when to execute it,
958 separated by a ":". Supported values of "WHEN" are the same as
959 that of --use-postprocessor (default: after_move). Same syntax
960 as the output template can be used to pass any field as argu‐
961 ments to the command. If no fields are passed,
962 %(filepath,_filename|)q is appended to the end of the command.
963 This option can be used multiple times
964 --no-exec
966 Remove any previously defined --exec
967 --convert-subs FORMAT
969 Convert the subtitles to another format (currently supported:
970 ass, lrc, srt, vtt) (Alias: --convert-subtitles)
971 --convert-thumbnails FORMAT
973 Convert the thumbnails to another format (currently supported:
974 jpg, png, webp). You can specify multiple rules using similar
975 syntax as --remux-video
976 --split-chapters
978 Split video into multiple files based on internal chapters. The
979 "chapter:" prefix can be used with "--paths" and "--output" to
980 set the output filename for the split files. See "OUTPUT TEM‐
981 PLATE" for details
982 --no-split-chapters
984 Do not split video based on chapters (default)
985 --remove-chapters REGEX
987 Remove chapters whose title matches the given regular expres‐
988 sion. The syntax is the same as --download-sections. This op‐
989 tion can be used multiple times
990 --no-remove-chapters
992 Do not remove any chapters from the file (default)
993 --force-keyframes-at-cuts
995 Force keyframes at cuts when downloading/splitting/removing sec‐
996 tions. This is slow due to needing a re-encode, but the result‐
997 ing video may have fewer artifacts around the cuts
998 --no-force-keyframes-at-cuts
1000 Do not force keyframes around the chapters when cutting/split‐
1001 ting (default)
1002 --use-postprocessor NAME[:ARGS]
1004 The (case sensitive) name of plugin postprocessors to be en‐
1005 abled, and (optionally) arguments to be passed to it, separated
1006 by a colon ":". ARGS are a semicolon ";" delimited list of
1007 NAME=VALUE. The "when" argument determines when the postproces‐
1008 sor is invoked. It can be one of "pre_process" (after video ex‐
1009 traction), "after_filter" (after video passes filter), "video"
1010 (after --format; before --print/--output), "before_dl" (before
1011 each video download), "post_process" (after each video download;
1012 default), "after_move" (after moving video file to it's final
1013 locations), "after_video" (after downloading and processing all
1014 formats of a video), or "playlist" (at end of playlist). This
1015 option can be used multiple times to add different postproces‐
1016 sors
1017 SponsorBlock Options:
1019 Make chapter entries for, or remove various segments (sponsor, intro‐
1020 ductions, etc.) from downloaded YouTube videos using the SponsorBlock
1021 API (https://sponsor.ajay.app)
1022 --sponsorblock-mark CATS
1024 SponsorBlock categories to create chapters for, separated by
1025 commas. Available categories are sponsor, intro, outro, self‐
1026 promo, preview, filler, interaction, music_offtopic, poi_high‐
1027 light, chapter, all and default (=all). You can prefix the cat‐
1028 egory with a "-" to exclude it. See [1] for description of the
1029 categories. E.g. --sponsorblock-mark all,-preview [1]
1030 https://wiki.sponsor.ajay.app/w/Segment_Categories
1031 --sponsorblock-remove CATS
1033 SponsorBlock categories to be removed from the video file, sepa‐
1034 rated by commas. If a category is present in both mark and re‐
1035 move, remove takes precedence. The syntax and available cate‐
1036 gories are the same as for --sponsorblock-mark except that "de‐
1037 fault" refers to "all,-filler" and poi_highlight, chapter are
1038 not available
1039 --sponsorblock-chapter-title TEMPLATE
1041 An output template for the title of the SponsorBlock chapters
1042 created by --sponsorblock-mark. The only available fields are
1043 start_time, end_time, category, categories, name, catego‐
1044 ry_names. Defaults to "[SponsorBlock]: %(category_names)l"
1045 --no-sponsorblock
1047 Disable both --sponsorblock-mark and --sponsorblock-remove
1048 --sponsorblock-api URL
1050 SponsorBlock API location, defaults to https://sponsor.ajay.app
1051 Extractor Options:
1053 --extractor-retries RETRIES
1054 Number of retries for known extractor errors (default is 3), or
1055 "infinite"
1056 --allow-dynamic-mpd
1058 Process dynamic DASH manifests (default) (Alias: --no-ignore-dy‐
1059 namic-mpd)
1060 --ignore-dynamic-mpd
1062 Do not process dynamic DASH manifests (Alias: --no-allow-dynam‐
1063 ic-mpd)
1064 --hls-split-discontinuity
1066 Split HLS playlists to different formats at discontinuities such
1067 as ad breaks
1068 --no-hls-split-discontinuity
1070 Do not split HLS playlists to different formats at discontinu‐
1071 ities such as ad breaks (default)
1072 --extractor-args IE_KEY:ARGS
1074 Pass ARGS arguments to the IE_KEY extractor. See "EXTRACTOR AR‐
1075 GUMENTS" for details. You can use this option multiple times to
1076 give arguments for different extractors
1077
1079 You can configure yt-dlp by placing any supported command line option
1080 to a configuration file. The configuration is loaded from the follow‐
1081 ing locations:
1082 1. Main Configuration:
1084 • The file given by --config-location
1086 2. Portable Configuration: (Recommended for portable installations)
1088 • If using a binary, yt-dlp.conf in the same directory as the bina‐
1090 ry
1091 • If running from source-code, yt-dlp.conf in the parent directory
1093 of yt_dlp
1094 3. Home Configuration:
1096 • yt-dlp.conf in the home path given by -P
1098 • If -P is not given, the current directory is searched
1100 4. User Configuration:
1102 • ${XDG_CONFIG_HOME}/yt-dlp.conf
1104 • ${XDG_CONFIG_HOME}/yt-dlp/config (recommended on Linux/macOS)
1106 • ${XDG_CONFIG_HOME}/yt-dlp/config.txt
1108 • ${APPDATA}/yt-dlp.conf
1110 • ${APPDATA}/yt-dlp/config (recommended on Windows)
1112 • ${APPDATA}/yt-dlp/config.txt
1114 • ~/yt-dlp.conf
1116 • ~/yt-dlp.conf.txt
1118 • ~/.yt-dlp/config
1120 • ~/.yt-dlp/config.txt See also: Notes about environment variables
1122 5. System Configuration:
1124 • /etc/yt-dlp.conf
1126 • /etc/yt-dlp/config
1128 • /etc/yt-dlp/config.txt
1130 E.g. with the following configuration file yt-dlp will always extract
1132 the audio, not copy the mtime, use a proxy and save all videos under
1133 YouTube directory in your home directory:
1134 # Lines starting with # are comments
1136 # Always extract audio
1138 -x
1139 # Do not copy the mtime
1141 --no-mtime
1142 # Use this proxy
1144 --proxy 127.0.0.1:3128
1145 # Save all videos under YouTube directory in your home directory
1147 -o ~/YouTube/%(title)s.%(ext)s
1148 Note: Options in configuration file are just the same options aka
1150 switches used in regular command line calls; thus there must be no
1151 whitespace after - or --, e.g. -o or --proxy but not - o or -- proxy.
1152 They must also be quoted when necessary as-if it were a UNIX shell.
1153 You can use --ignore-config if you want to disable all configuration
1155 files for a particular yt-dlp run. If --ignore-config is found inside
1156 any configuration file, no further configuration will be loaded. For
1157 example, having the option in the portable configuration file prevents
1158 loading of home, user, and system configurations. Additionally, (for
1159 backward compatibility) if --ignore-config is found inside the system
1160 configuration file, the user configuration is not loaded.
1161 Configuration file encoding
1163 The configuration files are decoded according to the UTF BOM if
1164 present, and in the encoding from system locale otherwise.
1165 If you want your file to be decoded differently, add # coding: ENCODING
1167 to the beginning of the file (e.g. # coding: shift-jis). There must
1168 be no characters before that, even spaces or BOM.
1169 Authentication with netrc
1171 You may also want to configure automatic credentials storage for ex‐
1172 tractors that support authentication (by providing login and password
1173 with --username and --password) in order not to pass credentials as
1174 command line arguments on every yt-dlp execution and prevent tracking
1175 plain text passwords in the shell command history. You can achieve
1176 this using a .netrc file (https://stackoverflow.com/tags/.netrc/info)
1177 on a per-extractor basis. For that you will need to create a .netrc
1178 file in --netrc-location and restrict permissions to read/write by only
1179 you:
1180 touch ${HOME}/.netrc
1182 chmod a-rwx,u+rw ${HOME}/.netrc
1183 After that you can add credentials for an extractor in the following
1185 format, where extractor is the name of the extractor in lowercase:
1186 machine <extractor> login <username> password <password>
1188 E.g.
1190 machine youtube login myaccount@gmail.com password my_youtube_password
1192 machine twitch login my_twitch_account_name password my_twitch_password
1193 To activate authentication with the .netrc file you should pass --netrc
1195 to yt-dlp or place it in the configuration file.
1196 The default location of the .netrc file is ~ (see below).
1198 As an alternative to using the .netrc file, which has the disadvantage
1200 of keeping your passwords in a plain text file, you can configure a
1201 custom shell command to provide the credentials for an extractor. This
1202 is done by providing the --netrc-cmd parameter, it shall output the
1203 credentials in the netrc format and return 0 on success, other values
1204 will be treated as an error. {} in the command will be replaced by the
1205 name of the extractor to make it possible to select the credentials for
1206 the right extractor.
1207 E.g. To use an encrypted .netrc file stored as .authinfo.gpg
1209 yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' https://www.youtube.com/watch?v=BaW_jenozKc
1211 Notes about environment variables
1213 • Environment variables are normally specified as ${VARIABLE}/$VARIABLE
1214 on UNIX and %VARIABLE% on Windows; but is always shown as ${VARIABLE}
1215 in this documentation
1216 • yt-dlp also allow using UNIX-style variables on Windows for path-like
1218 options; e.g. --output, --config-location
1219 • If unset, ${XDG_CONFIG_HOME} defaults to ~/.config and
1221 ${XDG_CACHE_HOME} to ~/.cache
1222 • On Windows, ~ points to ${HOME} if present; or, ${USERPROFILE} or
1224 ${HOMEDRIVE}${HOMEPATH} otherwise
1225 • On Windows, ${USERPROFILE} generally points to C:\Users\<user name>
1227 and ${APPDATA} to ${USERPROFILE}\AppData\Roaming
1228
1230 The -o option is used to indicate a template for the output file names
1231 while -P option is used to specify the path each type of file should be
1232 saved to.
1233 The simplest usage of -o is not to set any template arguments when
1235 downloading a single file, like in yt-dlp -o funny_video.flv
1236 "https://some/video" (hard-coding file extension like this is not rec‐
1237 ommended and could break some post-processing).
1238 It may however also contain special sequences that will be replaced
1240 when downloading each video. The special sequences may be formatted
1241 according to Python string formatting operations
1242 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1243 formatting), e.g. %(NAME)s or %(NAME)05d. To clarify, that is a per‐
1244 cent symbol followed by a name in parentheses, followed by formatting
1245 operations.
1246 The field names themselves (the part inside the parenthesis) can also
1248 have some special formatting:
1249 1. Object traversal: The dictionaries and lists available in metadata
1251 can be traversed by using a dot . separator; e.g. %(tags.0)s,
1252 %(subtitles.en.-1.ext)s. You can do Python slicing with colon :;
1253 E.g. %(id.3:7:-1)s, %(formats.:.format_id)s. Curly braces {} can
1254 be used to build dictionaries with only specific keys; e.g. %(for‐
1255 mats.:.{format_id,height})#j. An empty field name %()s refers to
1256 the entire infodict; e.g. %(.{id,title})s. Note that all the
1257 fields that become available using this method are not listed below.
1258 Use -j to see such fields
1259 2. Addition: Addition and subtraction of numeric fields can be done us‐
1261 ing + and - respectively. E.g. %(playlist_index+10)03d, %(n_en‐
1262 tries+1-playlist_index)d
1263 3. Date/time Formatting: Date/time fields can be formatted according to
1265 strftime formatting (https://docs.python.org/3/library/date‐
1266 time.html#strftime-and-strptime-format-codes) by specifying it sepa‐
1267 rated from the field name using a >. E.g. %(duration>%H-%M-%S)s,
1268 %(upload_date>%Y-%m-%d)s, %(epoch-3600>%H-%M-%S)s
1269 4. Alternatives: Alternate fields can be specified separated with a ,.
1271 E.g. %(release_date>%Y,upload_date>%Y|Unknown)s
1272 5. Replacement: A replacement value can be specified using a & separa‐
1274 tor according to the str.format mini-language
1275 (https://docs.python.org/3/library/string.html#format-specification-
1276 mini-language). If the field is not empty, this replacement value
1277 will be used instead of the actual field content. This is done af‐
1278 ter alternate fields are considered; thus the replacement is used if
1279 any of the alternative fields is not empty. E.g. %(chapters&has
1280 chapters|no chapters)s, %(title&TITLE={:>20}|NO TITLE)s
1281 6. Default: A literal default value can be specified for when the field
1283 is empty using a | separator. This overrides --output-na-placehold‐
1284 er. E.g. %(uploader|Unknown)s
1285 7. More Conversions: In addition to the normal format types diouxXeEf‐
1287 FgGcrs, yt-dlp additionally supports converting to B = Bytes, j =
1288 json (flag # for pretty-printing, + for Unicode), h = HTML escaping,
1289 l = a comma separated list (flag # for \n newline-separated), q = a
1290 string quoted for the terminal (flag # to split a list into differ‐
1291 ent arguments), D = add Decimal suffixes (e.g. 10M) (flag # to use
1292 1024 as factor), and S = Sanitize as filename (flag # for restrict‐
1293 ed)
1294 8. Unicode normalization: The format type U can be used for NFC Unicode
1296 normalization (https://docs.python.org/3/library/unicodeda‐
1297 ta.html#unicodedata.normalize). The alternate form flag (#) changes
1298 the normalization to NFD and the conversion flag + can be used for
1299 NFKC/NFKD compatibility equivalence normalization. E.g. %(ti‐
1300 tle)+.100U is NFKC
1301 To summarize, the general syntax for a field is:
1303 %(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
1305 Additionally, you can set different output templates for the various
1307 metadata files separately from the general output template by specify‐
1308 ing the type of file followed by the template separated by a colon :.
1309 The different file types supported are subtitle, thumbnail, descrip‐
1310 tion, annotation (deprecated), infojson, link, pl_thumbnail, pl_de‐
1311 scription, pl_infojson, chapter, pl_video. E.g. -o "%(ti‐
1312 tle)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s" will put the
1313 thumbnails in a folder with the same name as the video. If any of the
1314 templates is empty, that type of file will not be written. E.g.
1315 --write-thumbnail -o "thumbnail:" will write thumbnails only for
1316 playlists and not for video.
1317 Note: Due to post-processing (i.e. merging etc.), the actual output
1319 filename might differ. Use --print after_move:filepath to get the name
1320 after all post-processing is complete.
1321 The available fields are:
1323 • id (string): Video identifier
1325 • title (string): Video title
1327 • fulltitle (string): Video title ignoring live timestamp and generic
1329 title
1330 • ext (string): Video filename extension
1332 • alt_title (string): A secondary title of the video
1334 • description (string): The description of the video
1336 • display_id (string): An alternative identifier for the video
1338 • uploader (string): Full name of the video uploader
1340 • license (string): License name the video is licensed under
1342 • creator (string): The creator of the video
1344 • timestamp (numeric): UNIX timestamp of the moment the video became
1346 available
1347 • upload_date (string): Video upload date in UTC (YYYYMMDD)
1349 • release_timestamp (numeric): UNIX timestamp of the moment the video
1351 was released
1352 • release_date (string): The date (YYYYMMDD) when the video was re‐
1354 leased in UTC
1355 • modified_timestamp (numeric): UNIX timestamp of the moment the video
1357 was last modified
1358 • modified_date (string): The date (YYYYMMDD) when the video was last
1360 modified in UTC
1361 • uploader_id (string): Nickname or id of the video uploader
1363 • channel (string): Full name of the channel the video is uploaded on
1365 • channel_id (string): Id of the channel
1367 • channel_follower_count (numeric): Number of followers of the channel
1369 • channel_is_verified (boolean): Whether the channel is verified on the
1371 platform
1372 • location (string): Physical location where the video was filmed
1374 • duration (numeric): Length of the video in seconds
1376 • duration_string (string): Length of the video (HH:mm:ss)
1378 • view_count (numeric): How many users have watched the video on the
1380 platform
1381 • concurrent_view_count (numeric): How many users are currently watch‐
1383 ing the video on the platform.
1384 • like_count (numeric): Number of positive ratings of the video
1386 • dislike_count (numeric): Number of negative ratings of the video
1388 • repost_count (numeric): Number of reposts of the video
1390 • average_rating (numeric): Average rating give by users, the scale
1392 used depends on the webpage
1393 • comment_count (numeric): Number of comments on the video (For some
1395 extractors, comments are only downloaded at the end, and so this
1396 field cannot be used)
1397 • age_limit (numeric): Age restriction for the video (years)
1399 • live_status (string): One of "not_live", "is_live", "is_upcoming",
1401 "was_live", "post_live" (was live, but VOD is not yet processed)
1402 • is_live (boolean): Whether this video is a live stream or a fixed-
1404 length video
1405 • was_live (boolean): Whether this video was originally a live stream
1407 • playable_in_embed (string): Whether this video is allowed to play in
1409 embedded players on other sites
1410 • availability (string): Whether the video is "private", "premium_on‐
1412 ly", "subscriber_only", "needs_auth", "unlisted" or "public"
1413 • start_time (numeric): Time in seconds where the reproduction should
1415 start, as specified in the URL
1416 • end_time (numeric): Time in seconds where the reproduction should
1418 end, as specified in the URL
1419 • extractor (string): Name of the extractor
1421 • extractor_key (string): Key name of the extractor
1423 • epoch (numeric): Unix epoch of when the information extraction was
1425 completed
1426 • autonumber (numeric): Number that will be increased with each down‐
1428 load, starting at --autonumber-start, padded with leading zeros to 5
1429 digits
1430 • video_autonumber (numeric): Number that will be increased with each
1432 video
1433 • n_entries (numeric): Total number of extracted items in the playlist
1435 • playlist_id (string): Identifier of the playlist that contains the
1437 video
1438 • playlist_title (string): Name of the playlist that contains the video
1440 • playlist (string): playlist_id or playlist_title
1442 • playlist_count (numeric): Total number of items in the playlist. May
1444 not be known if entire playlist is not extracted
1445 • playlist_index (numeric): Index of the video in the playlist padded
1447 with leading zeros according the final index
1448 • playlist_autonumber (numeric): Position of the video in the playlist
1450 download queue padded with leading zeros according to the total
1451 length of the playlist
1452 • playlist_uploader (string): Full name of the playlist uploader
1454 • playlist_uploader_id (string): Nickname or id of the playlist upload‐
1456 er
1457 • webpage_url (string): A URL to the video webpage which if given to
1459 yt-dlp should allow to get the same result again
1460 • webpage_url_basename (string): The basename of the webpage URL
1462 • webpage_url_domain (string): The domain of the webpage URL
1464 • original_url (string): The URL given by the user (or same as web‐
1466 page_url for playlist entries)
1467 All the fields in Filtering Formats can also be used
1469 Available for the video that belongs to some logical chapter or sec‐
1471 tion:
1472 • chapter (string): Name or title of the chapter the video belongs to
1474 • chapter_number (numeric): Number of the chapter the video belongs to
1476 • chapter_id (string): Id of the chapter the video belongs to
1478 Available for the video that is an episode of some series or programme:
1480 • series (string): Title of the series or programme the video episode
1482 belongs to
1483 • season (string): Title of the season the video episode belongs to
1485 • season_number (numeric): Number of the season the video episode be‐
1487 longs to
1488 • season_id (string): Id of the season the video episode belongs to
1490 • episode (string): Title of the video episode
1492 • episode_number (numeric): Number of the video episode within a season
1494 • episode_id (string): Id of the video episode
1496 Available for the media that is a track or a part of a music album:
1498 • track (string): Title of the track
1500 • track_number (numeric): Number of the track within an album or a disc
1502 • track_id (string): Id of the track
1504 • artist (string): Artist(s) of the track
1506 • genre (string): Genre(s) of the track
1508 • album (string): Title of the album the track belongs to
1510 • album_type (string): Type of the album
1512 • album_artist (string): List of all artists appeared on the album
1514 • disc_number (numeric): Number of the disc or other physical medium
1516 the track belongs to
1517 • release_year (numeric): Year (YYYY) when the album was released
1519 Available only when using --download-sections and for chapter: prefix
1521 when using --split-chapters for videos with internal chapters:
1522 • section_title (string): Title of the chapter
1524 • section_number (numeric): Number of the chapter within the file
1526 • section_start (numeric): Start time of the chapter in seconds
1528 • section_end (numeric): End time of the chapter in seconds
1530 Available only when used in --print:
1532 • urls (string): The URLs of all requested formats, one in each line
1534 • filename (string): Name of the video file. Note that the actual
1536 filename may differ
1537 • formats_table (table): The video format table as printed by --list-
1539 formats
1540 • thumbnails_table (table): The thumbnail format table as printed by
1542 --list-thumbnails
1543 • subtitles_table (table): The subtitle format table as printed by
1545 --list-subs
1546 • automatic_captions_table (table): The automatic subtitle format table
1548 as printed by --list-subs
1549 Available only after the video is downloaded (post_process/after_move):
1551 • filepath: Actual path of downloaded video file
1553 Available only in --sponsorblock-chapter-title:
1555 • start_time (numeric): Start time of the chapter in seconds
1557 • end_time (numeric): End time of the chapter in seconds
1559 • categories (list): The SponsorBlock categories (https://wiki.spon‐
1561 sor.ajay.app/w/Types#Category) the chapter belongs to
1562 • category (string): The smallest SponsorBlock category the chapter be‐
1564 longs to
1565 • category_names (list): Friendly names of the categories
1567 • name (string): Friendly name of the smallest category
1569 • type (string): The SponsorBlock action type (https://wiki.spon‐
1571 sor.ajay.app/w/Types#Action_Type) of the chapter
1572 Each aforementioned sequence when referenced in an output template will
1574 be replaced by the actual value corresponding to the sequence name.
1575 E.g. for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title yt-
1576 dlp test video and id BaW_jenozKc, this will result in a yt-dlp test
1577 video-BaW_jenozKc.mp4 file created in the current directory.
1578 Note: Some of the sequences are not guaranteed to be present since they
1580 depend on the metadata obtained by a particular extractor. Such se‐
1581 quences will be replaced with placeholder value provided with --output-
1582 na-placeholder (NA by default).
1583 Tip: Look at the -j output to identify which fields are available for
1585 the particular URL
1586 For numeric sequences you can use numeric related formatting
1588 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1589 formatting); e.g. %(view_count)05d will result in a string with view
1590 count padded with zeros up to 5 characters, like in 00042.
1591 Output templates can also contain arbitrary hierarchical path, e.g. -o
1593 "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" which will result
1594 in downloading each video in a directory corresponding to this path
1595 template. Any missing directory will be automatically created for you.
1596 To use percent literals in an output template use %%. To output to
1598 stdout use -o -.
1599 The current default template is %(title)s [%(id)s].%(ext)s.
1601 In some cases, you don't want special characters such as 中, spaces, or
1603 &, such as when transferring the downloaded filename to a Windows sys‐
1604 tem or the filename through an 8bit-unsafe channel. In these cases,
1605 add the --restrict-filenames flag to get a shorter title.
1606 Output template examples
1608 $ yt-dlp --print filename -o "test video.%(ext)s" BaW_jenozKc
1609 test video.webm # Literal name with correct extension
1610 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc
1612 youtube-dl test video ''_ä↭𝕐.webm # All kinds of weird characters
1613 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
1615 youtube-dl_test_video_.webm # Restricted file name
1616 # Download YouTube playlist videos in separate directory indexed by video order in a playlist
1618 $ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1619 # Download YouTube playlist videos in separate directories according to their uploaded year
1621 $ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1622 # Prefix playlist index with " - " separator, but only if it is available
1624 $ yt-dlp -o "%(playlist_index&{} - |)s%(title)s.%(ext)s" BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1625 # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
1627 $ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1628 # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
1630 $ 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"
1631 # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
1633 $ 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"
1634 # Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
1636 # and put all temporary files in "C:\MyVideos\tmp"
1637 $ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs
1638 # Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
1640 $ 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
1641 # Stream the video being downloaded to stdout
1643 $ yt-dlp -o - BaW_jenozKc
1644
1646 By default, yt-dlp tries to download the best available quality if you
1647 don't pass any options. This is generally equivalent to using -f
1648 bestvideo*+bestaudio/best. However, if multiple audiostreams is en‐
1649 abled (--audio-multistreams), the default format changes to -f
1650 bestvideo+bestaudio/best. Similarly, if ffmpeg is unavailable, or if
1651 you use yt-dlp to stream to stdout (-o -), the default becomes -f
1652 best/bestvideo+bestaudio.
1653 Deprecation warning: Latest versions of yt-dlp can stream multiple for‐
1655 mats to the stdout simultaneously using ffmpeg. So, in future ver‐
1656 sions, the default for this will be set to -f bv*+ba/b similar to nor‐
1657 mal downloads. If you want to preserve the -f b/bv+ba setting, it is
1658 recommended to explicitly specify it in the configuration options.
1659 The general syntax for format selection is -f FORMAT (or --format FOR‐
1661 MAT) where FORMAT is a selector expression, i.e. an expression that
1662 describes format or formats you would like to download.
1663 The simplest case is requesting a specific format; e.g. with -f 22 you
1665 can download the format with format code equal to 22. You can get the
1666 list of available format codes for particular video using --list-for‐
1667 mats or -F. Note that these format codes are extractor specific.
1668 You can also use a file extension (currently 3gp, aac, flv, m4a, mp3,
1670 mp4, ogg, wav, webm are supported) to download the best quality format
1671 of a particular file extension served as a single file, e.g. -f webm
1672 will download the best quality format with the webm extension served as
1673 a single file.
1674 You can use -f - to interactively provide the format selector for each
1676 video
1677 You can also use special names to select particular edge case formats:
1679 • all: Select all formats separately
1681 • mergeall: Select and merge all formats (Must be used with --audio-
1683 multistreams, --video-multistreams or both)
1684 • b*, best*: Select the best quality format that contains either a
1686 video or an audio or both (ie; vcodec!=none or acodec!=none)
1687 • b, best: Select the best quality format that contains both video and
1689 audio. Equivalent to best*[vcodec!=none][acodec!=none]
1690 • bv, bestvideo: Select the best quality video-only format. Equivalent
1692 to best*[acodec=none]
1693 • bv*, bestvideo*: Select the best quality format that contains video.
1695 It may also contain audio. Equivalent to best*[vcodec!=none]
1696 • ba, bestaudio: Select the best quality audio-only format. Equivalent
1698 to best*[vcodec=none]
1699 • ba*, bestaudio*: Select the best quality format that contains audio.
1701 It may also contain video. Equivalent to best*[acodec!=none] (Do not
1702 use! (https://github.com/yt-dlp/yt-dlp/issues/979#issuecom‐
1703 ment-919629354))
1704 • w*, worst*: Select the worst quality format that contains either a
1706 video or an audio
1707 • w, worst: Select the worst quality format that contains both video
1709 and audio. Equivalent to worst*[vcodec!=none][acodec!=none]
1710 • wv, worstvideo: Select the worst quality video-only format. Equiva‐
1712 lent to worst*[acodec=none]
1713 • wv*, worstvideo*: Select the worst quality format that contains
1715 video. It may also contain audio. Equivalent to
1716 worst*[vcodec!=none]
1717 • wa, worstaudio: Select the worst quality audio-only format. Equiva‐
1719 lent to worst*[vcodec=none]
1720 • wa*, worstaudio*: Select the worst quality format that contains au‐
1722 dio. It may also contain video. Equivalent to worst*[acodec!=none]
1723 For example, to download the worst quality video-only format you can
1725 use -f worstvideo. It is however recommended not to use worst and re‐
1726 lated options. When your format selector is worst, the format which is
1727 worst in all respects is selected. Most of the time, what you actually
1728 want is the video with the smallest filesize instead. So it is gener‐
1729 ally better to use -S +size or more rigorously, -S +size,+br,+res,+fps
1730 instead of -f worst. See Sorting Formats for more details.
1731 You can select the n'th best format of a type by using best<type>.<n>.
1733 For example, best.2 will select the 2nd best combined format. Similar‐
1734 ly, bv*.3 will select the 3rd best format that contains a video stream.
1735 If you want to download multiple videos, and they don't have the same
1737 formats available, you can specify the order of preference using slash‐
1738 es. Note that formats on the left hand side are preferred; e.g. -f
1739 22/17/18 will download format 22 if it's available, otherwise it will
1740 download format 17 if it's available, otherwise it will download format
1741 18 if it's available, otherwise it will complain that no suitable for‐
1742 mats are available for download.
1743 If you want to download several formats of the same video use a comma
1745 as a separator, e.g. -f 22,17,18 will download all these three for‐
1746 mats, of course if they are available. Or a more sophisticated example
1747 combined with the precedence feature: -f
1748 136/137/mp4/bestvideo,140/m4a/bestaudio.
1749 You can merge the video and audio of multiple formats into a single
1751 file using -f <format1>+<format2>+... (requires ffmpeg installed); e.g.
1752 -f bestvideo+bestaudio will download the best video-only format, the
1753 best audio-only format and mux them together with ffmpeg.
1754 Deprecation warning: Since the below described behavior is complex and
1756 counter-intuitive, this will be removed and multistreams will be en‐
1757 abled by default in the future. A new operator will be instead added
1758 to limit formats to single audio/video
1759 Unless --video-multistreams is used, all formats with a video stream
1761 except the first one are ignored. Similarly, unless --audio-multi‐
1762 streams is used, all formats with an audio stream except the first one
1763 are ignored. E.g. -f bestvideo+best+bestaudio --video-multistreams
1764 --audio-multistreams will download and merge all 3 given formats. The
1765 resulting file will have 2 video streams and 2 audio streams. But -f
1766 bestvideo+best+bestaudio --no-video-multistreams will download and
1767 merge only bestvideo and bestaudio. best is ignored since another for‐
1768 mat containing a video stream (bestvideo) has already been selected.
1769 The order of the formats is therefore important. -f best+bestaudio
1770 --no-audio-multistreams will download only best while -f bestaudio+best
1771 --no-audio-multistreams will ignore best and download only bestaudio.
1772 Filtering Formats
1774 You can also filter the video formats by putting a condition in brack‐
1775 ets, as in -f "best[height=720]" (or -f "[filesize>10M]" since filters
1776 without a selector are interpreted as best).
1777 The following numeric meta fields can be used with comparisons <, <=,
1779 >, >=, = (equals), != (not equals):
1780 • filesize: The number of bytes, if known in advance
1782 • filesize_approx: An estimate for the number of bytes
1784 • width: Width of the video, if known
1786 • height: Height of the video, if known
1788 • aspect_ratio: Aspect ratio of the video, if known
1790 • tbr: Average bitrate of audio and video in KBit/s
1792 • abr: Average audio bitrate in KBit/s
1794 • vbr: Average video bitrate in KBit/s
1796 • asr: Audio sampling rate in Hertz
1798 • fps: Frame rate
1800 • audio_channels: The number of audio channels
1802 • stretched_ratio: width:height of the video's pixels, if not square
1804 Also filtering work for comparisons = (equals), ^= (starts with), $=
1806 (ends with), *= (contains), ~= (matches regex) and following string
1807 meta fields:
1808 • url: Video URL
1810 • ext: File extension
1812 • acodec: Name of the audio codec in use
1814 • vcodec: Name of the video codec in use
1816 • container: Name of the container format
1818 • protocol: The protocol that will be used for the actual download,
1820 lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, ism,
1821 http_dash_segments, m3u8, or m3u8_native)
1822 • language: Language code
1824 • dynamic_range: The dynamic range of the video
1826 • format_id: A short description of the format
1828 • format: A human-readable description of the format
1830 • format_note: Additional info about the format
1832 • resolution: Textual description of width and height
1834 Any string comparison may be prefixed with negation ! in order to pro‐
1836 duce an opposite comparison, e.g. !*= (does not contain). The compar‐
1837 and of a string comparison needs to be quoted with either double or
1838 single quotes if it contains spaces or special characters other than
1839 ._-.
1840 Note: None of the aforementioned meta fields are guaranteed to be
1842 present since this solely depends on the metadata obtained by particu‐
1843 lar extractor, i.e. the metadata offered by the website. Any other
1844 field made available by the extractor can also be used for filtering.
1845 Formats for which the value is not known are excluded unless you put a
1847 question mark (?) after the operator. You can combine format filters,
1848 so -f "bv[height<=?720][tbr>500]" selects up to 720p videos (or videos
1849 where the height is not known) with a bitrate of at least 500 KBit/s.
1850 You can also use the filters with all to download all formats that sat‐
1851 isfy the filter, e.g. -f "all[vcodec=none]" selects all audio-only
1852 formats.
1853 Format selectors can also be grouped using parentheses; e.g. -f
1855 "(mp4,webm)[height<480]" will download the best pre-merged mp4 and webm
1856 formats with a height lower than 480.
1857 Sorting Formats
1859 You can change the criteria for being considered the best by using -S
1860 (--format-sort). The general format for this is --format-sort
1861 field1,field2....
1862 The available fields are:
1864 • hasvid: Gives priority to formats that have a video stream
1866 • hasaud: Gives priority to formats that have an audio stream
1868 • ie_pref: The format preference
1870 • lang: The language preference
1872 • quality: The quality of the format
1874 • source: The preference of the source
1876 • proto: Protocol used for download (https/ftps > http/ftp > m3u8_na‐
1878 tive/m3u8 > http_dash_segments> websocket_frag > mms/rtsp > f4f/f4m)
1879 • vcodec: Video Codec (av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 >
1881 theora > other)
1882 • acodec: Audio Codec (flac/alac > wav/aiff > opus > vorbis > aac >
1884 mp4a > mp3 > ac4 > eac3 > ac3 > dts > other)
1885 • codec: Equivalent to vcodec,acodec
1887 • vext: Video Extension (mp4 > mov > webm > flv > other). If --prefer-
1889 free-formats is used, webm is preferred.
1890 • aext: Audio Extension (m4a > aac > mp3 > ogg > opus > webm > other).
1892 If --prefer-free-formats is used, the order changes to ogg > opus >
1893 webm > mp3 > m4a > aac
1894 • ext: Equivalent to vext,aext
1896 • filesize: Exact filesize, if known in advance
1898 • fs_approx: Approximate filesize
1900 • size: Exact filesize if available, otherwise approximate filesize
1902 • height: Height of video
1904 • width: Width of video
1906 • res: Video resolution, calculated as the smallest dimension.
1908 • fps: Framerate of video
1910 • hdr: The dynamic range of the video (DV > HDR12 > HDR10+ > HDR10 >
1912 HLG > SDR)
1913 • channels: The number of audio channels
1915 • tbr: Total average bitrate in KBit/s
1917 • vbr: Average video bitrate in KBit/s
1919 • abr: Average audio bitrate in KBit/s
1921 • br: Average bitrate in KBit/s, tbr/vbr/abr
1923 • asr: Audio sample rate in Hz
1925 Deprecation warning: Many of these fields have (currently undocumented)
1927 aliases, that may be removed in a future version. It is recommended to
1928 use only the documented field names.
1929 All fields, unless specified otherwise, are sorted in descending order.
1931 To reverse this, prefix the field with a +. E.g. +res prefers format
1932 with the smallest resolution. Additionally, you can suffix a preferred
1933 value for the fields, separated by a :. E.g. res:720 prefers larger
1934 videos, but no larger than 720p and the smallest video if there are no
1935 videos less than 720p. For codec and ext, you can provide two pre‐
1936 ferred values, the first for video and the second for audio. E.g.
1937 +codec:avc:m4a (equivalent to +vcodec:avc,+acodec:m4a) sets the video
1938 codec preference to h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 >
1939 theora and audio codec preference to mp4a > aac > vorbis > opus > mp3 >
1940 ac3 > dts. You can also make the sorting prefer the nearest values to
1941 the provided by using ~ as the delimiter. E.g. filesize~1G prefers
1942 the format with filesize closest to 1 GiB.
1943 The fields hasvid and ie_pref are always given highest priority in
1945 sorting, irrespective of the user-defined order. This behaviour can be
1946 changed by using --format-sort-force. Apart from these, the default
1947 order used is: lang,quality,res,fps,hdr:12,vcodec:vp9.2,chan‐
1948 nels,acodec,size,br,asr,proto,ext,hasaud,source,id. The extractors may
1949 override this default order, but they cannot override the user-provided
1950 order.
1951 Note that the default has vcodec:vp9.2; i.e. av1 is not preferred.
1953 Similarly, the default for hdr is hdr:12; i.e. dolby vision is not
1954 preferred. These choices are made since DV and AV1 formats are not yet
1955 fully compatible with most devices. This may be changed in the future
1956 as more devices become capable of smoothly playing back these formats.
1957 If your format selector is worst, the last item is selected after sort‐
1959 ing. This means it will select the format that is worst in all re‐
1960 spects. Most of the time, what you actually want is the video with the
1961 smallest filesize instead. So it is generally better to use -f best -S
1962 +size,+br,+res,+fps.
1963 Tip: You can use the -v -F to see how the formats have been sorted
1965 (worst to best).
1966 Format Selection examples
1968 # Download and merge the best video-only format and the best audio-only format,
1969 # or download the best combined format if video-only format is not available
1970 $ yt-dlp -f "bv+ba/b"
1971 # Download best format that contains video,
1973 # and if it doesn't already have an audio stream, merge it with best audio-only format
1974 $ yt-dlp -f "bv*+ba/b"
1975 # Same as above
1977 $ yt-dlp
1978 # Download the best video-only format and the best audio-only format without merging them
1980 # For this case, an output template should be used since
1981 # by default, bestvideo and bestaudio will have the same file name.
1982 $ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"
1983 # Download and merge the best format that has a video stream,
1985 # and all audio-only formats into one file
1986 $ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams
1987 # Download and merge the best format that has a video stream,
1989 # and the best 2 audio-only formats into one file
1990 $ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams
1991 # The following examples show the old method (without -S) of format selection
1994 # and how to use -S to achieve a similar but (generally) better result
1995 # Download the worst video available (old method)
1997 $ yt-dlp -f "wv*+wa/w"
1998 # Download the best video available but with the smallest resolution
2000 $ yt-dlp -S "+res"
2001 # Download the smallest video available
2003 $ yt-dlp -S "+size,+br"
2004 # Download the best mp4 video available, or the best video if no mp4 available
2008 $ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"
2009 # Download the best video with the best extension
2011 # (For video, mp4 > mov > webm > flv. For audio, m4a > aac > mp3 ...)
2012 $ yt-dlp -S "ext"
2013 # Download the best video available but no better than 480p,
2017 # or the worst video if there is no video under 480p
2018 $ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"
2019 # Download the best video available with the largest height but no better than 480p,
2021 # or the best video with the smallest resolution if there is no video under 480p
2022 $ yt-dlp -S "height:480"
2023 # Download the best video available with the largest resolution but no better than 480p,
2025 # or the best video with the smallest resolution if there is no video under 480p
2026 # Resolution is determined by using the smallest dimension.
2027 # So this works correctly for vertical videos as well
2028 $ yt-dlp -S "res:480"
2029 # Download the best video (that also has audio) but no bigger than 50 MB,
2033 # or the worst video (that also has audio) if there is no video under 50 MB
2034 $ yt-dlp -f "b[filesize<50M] / w"
2035 # Download largest video (that also has audio) but no bigger than 50 MB,
2037 # or the smallest video (that also has audio) if there is no video under 50 MB
2038 $ yt-dlp -f "b" -S "filesize:50M"
2039 # Download best video (that also has audio) that is closest in size to 50 MB
2041 $ yt-dlp -f "b" -S "filesize~50M"
2042 # Download best video available via direct link over HTTP/HTTPS protocol,
2046 # or the best video available via any protocol if there is no such video
2047 $ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"
2048 # Download best video available via the best protocol
2050 # (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
2051 $ yt-dlp -S "proto"
2052 # Download the best video with either h264 or h265 codec,
2056 # or the best video if there is no such video
2057 $ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"
2058 # Download the best video with best codec no better than h264,
2060 # or the best video with worst codec if there is no such video
2061 $ yt-dlp -S "codec:h264"
2062 # Download the best video with worst codec no worse than h264,
2064 # or the best video with best codec if there is no such video
2065 $ yt-dlp -S "+codec:h264"
2066 # More complex examples
2070 # Download the best video no better than 720p preferring framerate greater than 30,
2072 # or the worst video (still preferring framerate greater than 30) if there is no such video
2073 $ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"
2074 # Download the video with the largest resolution no better than 720p,
2076 # or the video with the smallest resolution available if there is no such video,
2077 # preferring larger framerate for formats with the same resolution
2078 $ yt-dlp -S "res:720,fps"
2079 # Download the video with smallest resolution no worse than 480p,
2083 # or the video with the largest resolution available if there is no such video,
2084 # preferring better codec and then larger total bitrate for the same resolution
2085 $ yt-dlp -S "+res:480,codec,br"
2086
2088 The metadata obtained by the extractors can be modified by using
2089 --parse-metadata and --replace-in-metadata
2090 --replace-in-metadata FIELDS REGEX REPLACE is used to replace text in
2092 any metadata field using python regular expression
2093 (https://docs.python.org/3/library/re.html#regular-expression-syntax).
2094 Backreferences (https://docs.python.org/3/library/re.html?high‐
2095 light=backreferences#re.sub) can be used in the replace string for ad‐
2096 vanced use.
2097 The general syntax of --parse-metadata FROM:TO is to give the name of a
2099 field or an output template to extract data from, and the format to in‐
2100 terpret it as, separated by a colon :. Either a python regular expres‐
2101 sion (https://docs.python.org/3/library/re.html#regular-expression-syn‐
2102 tax) with named capture groups, a single field name, or a similar syn‐
2103 tax to the output template (only %(field)s formatting is supported) can
2104 be used for TO. The option can be used multiple times to parse and
2105 modify various fields.
2106 Note that these options preserve their relative order, allowing re‐
2108 placements to be made in parsed fields and viceversa. Also, any field
2109 thus created can be used in the output template and will also affect
2110 the media file's metadata added when using --embed-metadata.
2111 This option also has a few special uses:
2113 • You can download an additional URL based on the metadata of the cur‐
2115 rently downloaded video. To do this, set the field additional_urls
2116 to the URL that you want to download. E.g. --parse-metadata "de‐
2117 scription:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" will
2118 download the first vimeo video found in the description
2119 • You can use this to change the metadata that is embedded in the media
2121 file. To do this, set the value of the corresponding field with a
2122 meta_ prefix. For example, any value you set to meta_description
2123 field will be added to the description field in the file - you can
2124 use this to set a different "description" and "synopsis". To modify
2125 the metadata of individual streams, use the meta<n>_ prefix (e.g.
2126 meta1_language). Any value set to the meta_ field will overwrite all
2127 default values.
2128 Note: Metadata modification happens before format selection, post-ex‐
2130 traction and other post-processing operations. Some fields may be
2131 added or changed during these steps, overriding your changes.
2132 For reference, these are the fields yt-dlp adds by default to the file
2134 metadata:
2135 Metadata fields From
2137 ──────────────────────────────────────────────────────────────────────────
2138 title track or title
2139 date upload_date
2140 description, synopsis description
2141 purl, comment webpage_url
2142 track track_number
2143 artist artist, creator, uploader or uploader_id
2144 genre genre
2145 album album
2146 album_artist album_artist
2147 disc disc_number
2148 show series
2149 season_number season_number
2150 episode_id episode or episode_id
2151 episode_sort episode_number
2152 language of each stream the format's language
2153 Note: The file format may not support some of these fields
2155 Modifying metadata examples
2157 # Interpret the title as "Artist - Title"
2158 $ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"
2159 # Regex example
2161 $ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"
2162 # Set title as "Series name S01E05"
2164 $ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"
2165 # Prioritize uploader as the "artist" field in video metadata
2167 $ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --embed-metadata
2168 # Set "comment" field in video metadata using description instead of webpage_url,
2170 # handling multiple lines correctly
2171 $ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --embed-metadata
2172 # Do not set any "synopsis" in the video metadata
2174 $ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"
2175 # Remove "formats" field from the infojson by setting it to an empty string
2177 $ yt-dlp --parse-metadata "video::(?P<formats>)" --write-info-json
2178 # Replace all spaces and "_" in title and uploader with a `-`
2180 $ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"
2181
2183 Some extractors accept additional arguments which can be passed using
2184 --extractor-args KEY:ARGS. ARGS is a ; (semicolon) separated string of
2185 ARG=VAL1,VAL2. E.g. --extractor-args "youtube:player-client=an‐
2186 droid_embedded,web;include_live_dash" --extractor-args "funimation:ver‐
2187 sion=uncut"
2188 Note: In CLI, ARG can use - instead of _; e.g. youtube:player-client"
2190 becomes youtube:player_client"
2191 The following extractors use this feature:
2193 youtube
2195 • lang: Prefer translated metadata (title, description etc) of this
2196 language code (case-sensitive). By default, the video primary lan‐
2197 guage metadata is preferred, with a fallback to en translated. See
2198 youtube.py (https://github.com/yt-dlp/yt-
2199 dlp/blob/c26f9b991a0681fd3ea548d535919cec1fbbd430/yt_dlp/extrac‐
2200 tor/youtube.py#L381-L390) for list of supported content language
2201 codes
2202 • skip: One or more of hls, dash or translated_subs to skip extraction
2204 of the m3u8 manifests, dash manifests and auto-translated subtitles
2205 (https://github.com/yt-dlp/yt-dlp/issues/4090#issuecom‐
2206 ment-1158102032) respectively
2207 • player_client: Clients to extract video data from. The main clients
2209 are web, android and ios with variants _music, _embedded, _embed‐
2210 screen, _creator (e.g. web_embedded); and mweb, mweb_embedscreen and
2211 tv_embedded (agegate bypass) with no variants. By default, ios,an‐
2212 droid,web is used, but tv_embedded and creator variants are added as
2213 required for age-gated videos. Similarly, the music variants are
2214 added for music.youtube.com urls. You can use all to use all the
2215 clients, and default for the default clients.
2216 • player_skip: Skip some network requests that are generally needed for
2218 robust extraction. One or more of configs (skip client configs),
2219 webpage (skip initial webpage), js (skip js player). While these op‐
2220 tions can help reduce the number of requests needed or avoid some
2221 rate-limiting, they could cause some issues. See #860
2222 (https://github.com/yt-dlp/yt-dlp/pull/860) for more details
2223 • player_params: YouTube player parameters to use for player requests.
2225 Will overwrite any default ones set by yt-dlp.
2226 • comment_sort: top or new (default) - choose comment sorting mode (on
2228 YouTube's side)
2229 • max_comments: Limit the amount of comments to gather. Comma-separat‐
2231 ed list of integers representing max-comments,max-parents,max-
2232 replies,max-replies-per-thread. Default is all,all,all,all
2233 • E.g. all,all,1000,10 will get a maximum of 1000 replies total,
2235 with up to 10 replies per thread. 1000,all,100 will get a maximum
2236 of 1000 comments, with a maximum of 100 replies total
2237 • formats: Change the types of formats to return. dashy (convert HTTP
2239 to DASH), duplicate (identical content but different URLs or proto‐
2240 col; includes dashy), incomplete (cannot be downloaded completely -
2241 live dash and post-live m3u8)
2242 • innertube_host: Innertube API host to use for all API requests; e.g.
2244 studio.youtube.com, youtubei.googleapis.com. Note that cookies ex‐
2245 ported from one subdomain will not work on others
2246 • innertube_key: Innertube API key to use for all API requests
2248 • raise_incomplete_data: Incomplete Data Received raises an error in‐
2250 stead of reporting a warning
2251 youtubetab (YouTube playlists, channels, feeds, etc.)
2253 • skip: One or more of webpage (skip initial webpage download), au‐
2254 thcheck (allow the download of playlists requiring authentication
2255 when no initial webpage is downloaded. This may cause unwanted be‐
2256 havior, see #1122 (https://github.com/yt-dlp/yt-dlp/pull/1122) for
2257 more details)
2258 • approximate_date: Extract approximate upload_date and timestamp in
2260 flat-playlist. This may cause date-based filters to be slightly off
2261 generic
2263 • fragment_query: Passthrough any query in mpd/m3u8 manifest URLs to
2264 their fragments if no value is provided, or else apply the query
2265 string given as fragment_query=VALUE. Does not apply to ffmpeg
2266 • variant_query: Passthrough the master m3u8 URL query to its variant
2268 playlist URLs if no value is provided, or else apply the query string
2269 given as variant_query=VALUE
2270 • hls_key: An HLS AES-128 key URI or key (as hex), and optionally the
2272 IV (as hex), in the form of (URI|KEY)[,IV]; e.g. gener‐
2273 ic:hls_key=ABCDEF1234567980,0xFEDCBA0987654321. Passing any of these
2274 values will force usage of the native HLS downloader and override the
2275 corresponding values found in the m3u8 playlist
2276 • is_live: Bypass live HLS detection and manually set live_status - a
2278 value of false will set not_live, any other value (or no value) will
2279 set is_live
2280 funimation
2282 • language: Audio languages to extract, e.g. funimation:language=eng‐
2283 lish,japanese
2284 • version: The video version to extract - uncut or simulcast
2286 crunchyrollbeta (Crunchyroll)
2288 • format: Which stream type(s) to extract (default: adaptive_hls). Po‐
2289 tentially useful values include adaptive_hls, adaptive_dash, vo_adap‐
2290 tive_hls, vo_adaptive_dash, download_hls, download_dash, multi‐
2291 track_adaptive_hls_v2
2292 • hardsub: Preference order for which hardsub versions to extract, or
2294 all (default: None = no hardsubs), e.g. crunchyrollbeta:hardsub=en-
2295 US,None
2296 vikichannel
2298 • video_types: Types of videos to download - one or more of episodes,
2299 movies, clips, trailers
2300 niconico
2302 • segment_duration: Segment duration in milliseconds for HLS-DMC for‐
2303 mats. Use it at your own risk since this feature may result in your
2304 account termination.
2305 youtubewebarchive
2307 • check_all: Try to check more at the cost of more requests. One or
2308 more of thumbnails, captures
2309 gamejolt
2311 • comment_sort: hot (default), you (cookies needed), top, new - choose
2312 comment sorting mode (on GameJolt's side)
2313 hotstar
2315 • res: resolution to ignore - one or more of sd, hd, fhd
2316 • vcodec: vcodec to ignore - one or more of h264, h265, dvh265
2318 • dr: dynamic range to ignore - one or more of sdr, hdr10, dv
2320 niconicochannelplus
2322 • max_comments: Maximum number of comments to extract - default is 120
2323 tiktok
2325 • api_hostname: Hostname to use for mobile API requests, e.g. api-
2326 h2.tiktokv.com
2327 • app_version: App version to call mobile APIs with - should be set
2329 along with manifest_app_version, e.g. 20.2.1
2330 • manifest_app_version: Numeric app version to call mobile APIs with,
2332 e.g. 221
2333 rokfinchannel
2335 • tab: Which tab to download - one of new, top, videos, podcasts,
2336 streams, stacks
2337 twitter
2339 • api: Select one of graphql (default), legacy or syndication as the
2340 API for tweet extraction. Has no effect if logged in
2341 stacommu, wrestleuniverse
2343 • device_id: UUID value assigned by the website and used to enforce de‐
2344 vice limits for paid livestream content. Can be found in browser lo‐
2345 cal storage
2346 twitch
2348 • client_id: Client ID value to be sent with GraphQL requests, e.g.
2349 twitch:client_id=kimne78kx3ncx6brgo4mv6wki5h1ko
2350 nhkradirulive (NHK らじる★らじる LIVE)
2352 • area: Which regional variation to extract. Valid areas are: sapporo,
2353 sendai, tokyo, nagoya, osaka, hiroshima, matsuyama, fukuoka. De‐
2354 faults to tokyo
2355 nflplusreplay
2357 • type: Type(s) of game replays to extract. Valid types are:
2358 full_game, full_game_spanish, condensed_game and all_22. You can use
2359 all to extract all available replay types, which is the default
2360 Note: These options may be changed/removed in the future without con‐
2362 cern for backward compatibility
2363
2365 You can install yt-dlp using the binaries, pip
2366 (https://pypi.org/project/yt-dlp) or one using a third-party package
2367 manager. See the wiki (https://github.com/yt-dlp/yt-dlp/wiki/Installa‐
2368 tion) for detailed instructions
2369 UPDATE
2371 You can use yt-dlp -U to update if you are using the release binaries
2372 If you installed with pip (https://github.com/yt-dlp/yt-dlp/wiki/In‐
2374 stallation#with-pip), simply re-run the same command that was used to
2375 install the program
2376 For other third-party package managers, see the wiki
2378 (https://github.com/yt-dlp/yt-dlp/wiki/Installation#third-party-pack‐
2379 age-managers) or refer their documentation
2380 There are currently two release channels for binaries, stable and
2382 nightly. stable is the default channel, and many of its changes have
2383 been tested by users of the nightly channel. The nightly channel has
2384 releases built after each push to the master branch, and will have the
2385 most recent fixes and additions, but also have more risk of regres‐
2386 sions. They are available in their own repo (https://github.com/yt-
2387 dlp/yt-dlp-nightly-builds/releases).
2388 When using --update/-U, a release binary will only update to its cur‐
2390 rent channel. --update-to CHANNEL can be used to switch to a different
2391 channel when a newer version is available. --update-to [CHANNEL@]TAG
2392 can also be used to upgrade or downgrade to specific tags from a chan‐
2393 nel.
2394 You may also use --update-to <repository> (<owner>/<repository>) to up‐
2396 date to a channel on a completely different repository. Be careful
2397 with what repository you are updating to though, there is no verifica‐
2398 tion done for binaries from different repositories.
2399 Example usage: * yt-dlp --update-to nightly change to nightly channel
2401 and update to its latest release * yt-dlp --update-to stable@2023.02.17
2402 upgrade/downgrade to release to stable channel tag 2023.02.17 * yt-dlp
2403 --update-to 2023.01.06 upgrade/downgrade to tag 2023.01.06 if it exists
2404 on the current channel * yt-dlp --update-to example/yt-dlp@2023.03.01
2405 upgrade/downgrade to the release from the example/yt-dlp repository,
2406 tag 2023.03.01
2407 Note: The manpages, shell completion (autocomplete) files etc. are
2409 available inside the source tarball (https://github.com/yt-dlp/yt-
2410 dlp/releases/latest/download/yt-dlp.tar.gz)
2411 DEPENDENCIES
2413 Python versions 3.7+ (CPython and PyPy) are supported. Other versions
2414 and implementations may or may not work correctly.
2415 While all the other dependencies are optional, ffmpeg and ffprobe are
2417 highly recommended
2418 Strongly recommended
2420 • ffmpeg and ffprobe (https://www.ffmpeg.org) - Required for merging
2421 separate video and audio files as well as for various post-processing
2422 tasks. License depends on the build (https://www.ffmpeg.org/le‐
2423 gal.html)
2424 There are bugs in ffmpeg that causes various issues when used along‐
2426 side yt-dlp. Since ffmpeg is such an important dependency, we pro‐
2427 vide custom builds (https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-
2428 static-auto-builds) with patches for some of these issues at yt-
2429 dlp/FFmpeg-Builds (https://github.com/yt-dlp/FFmpeg-Builds). See the
2430 readme (https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for
2431 details on the specific issues solved by these builds
2432 Important: What you need is ffmpeg binary, NOT the python package of
2434 the same name (https://pypi.org/project/ffmpeg)
2435 Networking
2437 • certifi (https://github.com/certifi/python-certifi)* - Provides
2438 Mozilla's root certificate bundle. Licensed under MPLv2
2439 (https://github.com/certifi/python-certifi/blob/master/LICENSE)
2440 • brotli (https://github.com/google/brotli)* or brotlicffi
2442 (https://github.com/python-hyper/brotlicffi) - Brotli
2443 (https://en.wikipedia.org/wiki/Brotli) content encoding support.
2444 Both licensed under MIT 1 (https://github.com/google/brotli/blob/mas‐
2445 ter/LICENSE) 2 (https://github.com/python-hyper/brotlicffi/blob/mas‐
2446 ter/LICENSE)
2447 • websockets (https://github.com/aaugustin/websockets)* - For download‐
2449 ing over websocket. Licensed under BSD-3-Clause
2450 (https://github.com/aaugustin/websockets/blob/main/LICENSE)
2451 Metadata
2453 • mutagen (https://github.com/quodlibet/mutagen)* - For --embed-thumb‐
2454 nail in certain formats. Licensed under GPLv2+
2455 (https://github.com/quodlibet/mutagen/blob/master/COPYING)
2456 • AtomicParsley (https://github.com/wez/atomicparsley) - For --embed-
2458 thumbnail in mp4/m4a files when mutagen/ffmpeg cannot. Licensed un‐
2459 der GPLv2+ (https://github.com/wez/atomicparsley/blob/master/COPYING)
2460 • xattr (https://github.com/xattr/xattr), pyxattr
2462 (https://github.com/iustin/pyxattr) or setfattr (http://savan‐
2463 nah.nongnu.org/projects/attr) - For writing xattr metadata (--xattr)
2464 on Linux. Licensed under MIT (https://github.com/xattr/xat‐
2465 tr/blob/master/LICENSE.txt), LGPL2.1 (https://github.com/iustin/pyx‐
2466 attr/blob/master/COPYING) and GPLv2+ (http://git.savan‐
2467 nah.nongnu.org/cgit/attr.git/tree/doc/COPYING) respectively
2468 Misc
2470 • pycryptodomex (https://github.com/Legrandin/pycryptodome)* - For de‐
2471 crypting AES-128 HLS streams and various other data. Licensed under
2472 BSD-2-Clause (https://github.com/Legrandin/pycryptodome/blob/mas‐
2473 ter/LICENSE.rst)
2474 • phantomjs (https://github.com/ariya/phantomjs) - Used in extractors
2476 where javascript needs to be run. Licensed under BSD-3-Clause
2477 (https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
2478 • secretstorage (https://github.com/mitya57/secretstorage) - For
2480 --cookies-from-browser to access the Gnome keyring while decrypting
2481 cookies of Chromium-based browsers on Linux. Licensed under
2482 BSD-3-Clause (https://github.com/mitya57/secretstorage/blob/mas‐
2483 ter/LICENSE)
2484 • Any external downloader that you want to use with --downloader
2486 Deprecated
2488 • avconv and avprobe (https://www.libav.org) - Now deprecated alterna‐
2489 tive to ffmpeg. License depends on the build (https://libav.org/le‐
2490 gal)
2491 • sponskrub (https://github.com/faissaloo/SponSkrub) - For using the
2493 now deprecated sponskrub options. Licensed under GPLv3+
2494 (https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
2495 • rtmpdump (http://rtmpdump.mplayerhq.hu) - For downloading rtmp
2497 streams. ffmpeg can be used instead with --downloader ffmpeg. Li‐
2498 censed under GPLv2+ (http://rtmpdump.mplayerhq.hu)
2499 • mplayer (http://mplayerhq.hu/design7/info.html) or mpv
2501 (https://mpv.io) - For downloading rstp/mms streams. ffmpeg can be
2502 used instead with --downloader ffmpeg. Licensed under GPLv2+
2503 (https://github.com/mpv-player/mpv/blob/master/Copyright)
2504 To use or redistribute the dependencies, you must agree to their re‐
2506 spective licensing terms.
2507 The standalone release binaries are built with the Python interpreter
2509 and the packages marked with * included.
2510 If you do not have the necessary dependencies for a task you are at‐
2512 tempting, yt-dlp will warn you. All the currently available dependen‐
2513 cies are visible at the top of the --verbose output
2514 COMPILE
2516 Standalone PyInstaller Builds
2517 To build the standalone executable, you must have Python and pyin‐
2518 staller (plus any of yt-dlp's optional dependencies if needed). Once
2519 you have all the necessary dependencies installed, simply run
2520 pyinst.py. The executable will be built for the same architecture
2521 (x86/ARM, 32/64 bit) as the Python used.
2522 python3 -m pip install -U pyinstaller -r requirements.txt
2524 python3 devscripts/make_lazy_extractors.py
2525 python3 pyinst.py
2526 On some systems, you may need to use py or python instead of python3.
2528 pyinst.py accepts any arguments that can be passed to pyinstaller, such
2530 as --onefile/-F or --onedir/-D, which is further documented here
2531 (https://pyinstaller.org/en/stable/usage.html#what-to-generate).
2532 Note: Pyinstaller versions below 4.4 do not support
2534 (https://github.com/pyinstaller/pyinstaller#requirements-and-tested-
2535 platforms) Python installed from the Windows store without using a vir‐
2536 tual environment.
2537 Important: Running pyinstaller directly without using pyinst.py is not
2539 officially supported. This may or may not work correctly.
2540 Platform-independent Binary (UNIX)
2542 You will need the build tools python (3.7+), zip, make (GNU), pandoc*
2543 and pytest*.
2544 After installing these, simply run make.
2546 You can also run make yt-dlp instead to compile only the binary without
2548 updating any of the additional files. (The build tools marked with *
2549 are not needed for this)
2550 Standalone Py2Exe Builds (Windows)
2552 While we provide the option to build with py2exe
2553 (https://www.py2exe.org), it is recommended to build using PyInstaller
2554 instead since the py2exe builds cannot contain pycryptodomex/certifi
2555 and needs VC++14 on the target computer to run.
2556 If you wish to build it anyway, install Python and py2exe, and then
2558 simply run setup.py py2exe
2559 py -m pip install -U py2exe -r requirements.txt
2561 py devscripts/make_lazy_extractors.py
2562 py setup.py py2exe
2563 Related scripts
2565 • devscripts/update-version.py - Update the version number based on
2566 current date.
2567 • devscripts/set-variant.py - Set the build variant of the executable.
2569 • devscripts/make_changelog.py - Create a markdown changelog using
2571 short commit messages and update CONTRIBUTORS file.
2572 • devscripts/make_lazy_extractors.py - Create lazy extractors. Running
2574 this before building the binaries (any variant) will improve their
2575 startup performance. Set the environment variable YTDLP_NO_LAZY_EX‐
2576 TRACTORS=1 if you wish to forcefully disable lazy extractor loading.
2577 Note: See their --help for more info.
2579 Forking the project
2581 If you fork the project on GitHub, you can run your fork's build work‐
2582 flow to automatically build the selected version(s) as artifacts. Al‐
2583 ternatively, you can run the release workflow or enable the nightly
2584 workflow to create full (pre-)releases.
2585
2587 Note that all plugins are imported even if not invoked, and that there
2588 are no checks performed on plugin code. Use plugins at your own risk
2589 and only if you trust the code!
2590 Plugins can be of <type>s extractor or postprocessor. - Extractor
2592 plugins do not need to be enabled from the CLI and are automatically
2593 invoked when the input URL is suitable for it. - Extractor plugins
2594 take priority over builtin extractors. - Postprocessor plugins can be
2595 invoked using --use-postprocessor NAME.
2596 Plugins are loaded from the namespace packages yt_dlp_plugins.extractor
2598 and yt_dlp_plugins.postprocessor.
2599 In other words, the file structure on the disk looks something like:
2601 yt_dlp_plugins/
2603 extractor/
2604 myplugin.py
2605 postprocessor/
2606 myplugin.py
2607 yt-dlp looks for these yt_dlp_plugins namespace folders in many loca‐
2609 tions (see below) and loads in plugins from all of them.
2610 See the wiki for some known plugins (https://github.com/yt-dlp/yt-
2612 dlp/wiki/Plugins)
2613 Installing Plugins
2615 Plugins can be installed using various methods and locations.
2616 1. Configuration directories: Plugin packages (containing a
2618 yt_dlp_plugins namespace folder) can be dropped into the following
2619 standard configuration locations:
2620 • User Plugins
2622 • ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plug‐
2624 ins/ (recommended on Linux/macOS)
2625 • ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plug‐
2627 ins/
2628 • ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/ (rec‐
2630 ommended on Windows)
2631 • ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2633 • ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
2635 • ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2637 • System Plugins
2639 • /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
2641 • /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2643 2. Executable location: Plugin packages can similarly be installed in a
2645 yt-dlp-plugins directory under the executable location (recommended
2646 for portable installations):
2647 • Binary: where <root-dir>/yt-dlp.exe, <root-dir>/yt-dlp-plug‐
2649 ins/<package name>/yt_dlp_plugins/
2650 • Source: where <root-dir>/yt_dlp/__main__.py, <root-dir>/yt-dlp-
2652 plugins/<package name>/yt_dlp_plugins/
2653 3. pip and other locations in PYTHONPATH
2655 • Plugin packages can be installed and managed using pip. See yt-
2657 dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-plug‐
2658 ins) for an example.
2659 • Note: plugin files between plugin packages installed with pip
2661 must have unique filenames.
2662 • Any path in PYTHONPATH is searched in for the yt_dlp_plugins
2664 namespace folder.
2665 • Note: This does not apply for Pyinstaller/py2exe builds.
2667 .zip, .egg and .whl archives containing a yt_dlp_plugins namespace
2669 folder in their root are also supported as plugin packages. * e.g.
2670 ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip where mypluginpkg.zip
2671 contains yt_dlp_plugins/<type>/myplugin.py
2672 Run yt-dlp with --verbose to check if the plugin has been loaded.
2674 Developing Plugins
2676 See the yt-dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-
2677 plugins) repo for a template plugin package and the Plugin Development
2678 (https://github.com/yt-dlp/yt-dlp/wiki/Plugin-Development) section of
2679 the wiki for a plugin development guide.
2680 All public classes with a name ending in IE/PP are imported from each
2682 file for extractors and postprocessors repectively. This respects un‐
2683 derscore prefix (e.g. _MyBasePluginIE is private) and __all__. Mod‐
2684 ules can similarly be excluded by prefixing the module name with an un‐
2685 derscore (e.g. _myplugin.py).
2686 To replace an existing extractor with a subclass of one, set the plug‐
2688 in_name class keyword argument (e.g. class MyPluginIE(ABuiltInIE,
2689 plugin_name='myplugin') will replace ABuiltInIE with MyPluginIE).
2690 Since the extractor replaces the parent, you should exclude the sub‐
2691 class extractor from being imported separately by making it private us‐
2692 ing one of the methods described above.
2693 If you are a plugin author, add yt-dlp-plugins (https://github.com/top‐
2695 ics/yt-dlp-plugins) as a topic to your repository for discoverability.
2696 See the Developer Instructions (https://github.com/yt-dlp/yt-
2698 dlp/blob/master/CONTRIBUTING.md#developer-instructions) on how to write
2699 and test an extractor.
2700
2702 yt-dlp makes the best effort to be a good command-line program, and
2703 thus should be callable from any programming language.
2704 Your program should avoid parsing the normal stdout since they may
2706 change in future versions. Instead they should use options such as -J,
2707 --print, --progress-template, --exec etc to create console output that
2708 you can reliably reproduce and parse.
2709 From a Python program, you can embed yt-dlp in a more powerful fashion,
2711 like this:
2712 from yt_dlp import YoutubeDL
2714 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2716 with YoutubeDL() as ydl:
2717 ydl.download(URLS)
2718 Most likely, you'll want to use various options. For a list of options
2720 available, have a look at yt_dlp/YoutubeDL.py or help(yt_dlp.YoutubeDL)
2721 in a Python shell. If you are already familiar with the CLI, you can
2722 use devscripts/cli_to_api.py (https://github.com/yt-dlp/yt-
2723 dlp/blob/master/devscripts/cli_to_api.py) to translate any CLI switches
2724 to YoutubeDL params.
2725 Tip: If you are porting your code from youtube-dl to yt-dlp, one impor‐
2727 tant point to look out for is that we do not guarantee the return value
2728 of YoutubeDL.extract_info to be json serializable, or even be a dictio‐
2729 nary. It will be dictionary-like, but if you want to ensure it is a
2730 serializable dictionary, pass it through YoutubeDL.sanitize_info as
2731 shown in the example below
2732 Embedding examples
2734 Extracting information
2735 import json
2736 import yt_dlp
2737 URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'
2739 # ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
2741 ydl_opts = {}
2742 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2743 info = ydl.extract_info(URL, download=False)
2744 # ℹ️ ydl.sanitize_info makes the info json-serializable
2746 print(json.dumps(ydl.sanitize_info(info)))
2747 Download using an info-json
2749 import yt_dlp
2750 INFO_FILE = 'path/to/video.info.json'
2752 with yt_dlp.YoutubeDL() as ydl:
2754 error_code = ydl.download_with_info_file(INFO_FILE)
2755 print('Some videos failed to download' if error_code
2757 else 'All videos successfully downloaded')
2758 Extract audio
2760 import yt_dlp
2761 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2763 ydl_opts = {
2765 'format': 'm4a/bestaudio/best',
2766 # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
2767 'postprocessors': [{ # Extract audio using ffmpeg
2768 'key': 'FFmpegExtractAudio',
2769 'preferredcodec': 'm4a',
2770 }]
2771 }
2772 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2774 error_code = ydl.download(URLS)
2775 Filter videos
2777 import yt_dlp
2778 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2780 def longer_than_a_minute(info, *, incomplete):
2782 """Download only videos longer than a minute (or with unknown duration)"""
2783 duration = info.get('duration')
2784 if duration and duration < 60:
2785 return 'The video is too short'
2786 ydl_opts = {
2788 'match_filter': longer_than_a_minute,
2789 }
2790 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2792 error_code = ydl.download(URLS)
2793 Adding logger and progress hook
2795 import yt_dlp
2796 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2798 class MyLogger:
2800 def debug(self, msg):
2801 # For compatibility with youtube-dl, both debug and info are passed into debug
2802 # You can distinguish them by the prefix '[debug] '
2803 if msg.startswith('[debug] '):
2804 pass
2805 else:
2806 self.info(msg)
2807 def info(self, msg):
2809 pass
2810 def warning(self, msg):
2812 pass
2813 def error(self, msg):
2815 print(msg)
2816 # ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
2819 def my_hook(d):
2820 if d['status'] == 'finished':
2821 print('Done downloading, now post-processing ...')
2822 ydl_opts = {
2825 'logger': MyLogger(),
2826 'progress_hooks': [my_hook],
2827 }
2828 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2830 ydl.download(URLS)
2831 Add a custom PostProcessor
2833 import yt_dlp
2834 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2836 # ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
2838 class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
2839 def run(self, info):
2840 self.to_screen('Doing stuff')
2841 return [], info
2842 with yt_dlp.YoutubeDL() as ydl:
2845 # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
2846 ydl.add_post_processor(MyCustomPP(), when='pre_process')
2847 ydl.download(URLS)
2848 Use a custom format selector
2850 import yt_dlp
2851 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2853 def format_selector(ctx):
2855 """ Select the best video and the best audio that won't result in an mkv.
2856 NOTE: This is just an example and does not handle all cases """
2857 # formats are already sorted worst to best
2859 formats = ctx.get('formats')[::-1]
2860 # acodec='none' means there is no audio
2862 best_video = next(f for f in formats
2863 if f['vcodec'] != 'none' and f['acodec'] == 'none')
2864 # find compatible audio extension
2866 audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
2867 # vcodec='none' means there is no video
2868 best_audio = next(f for f in formats if (
2869 f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))
2870 # These are the minimum required fields for a merged format
2872 yield {
2873 'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
2874 'ext': best_video['ext'],
2875 'requested_formats': [best_video, best_audio],
2876 # Must be + separated list of protocols
2877 'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
2878 }
2879 ydl_opts = {
2882 'format': format_selector,
2883 }
2884 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2886 ydl.download(URLS)
2887
2889 • Forked from yt-dlc@f9401f2 (https://github.com/blackjack4494/yt-
2890 dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee) and merged with
2891 youtube-dl@66ab08 (https://github.com/ytdl-org/youtube-dl/com‐
2892 mit/66ab0814c4baa2dc79c2dd5287bc0ad61a37c5b9) (exceptions
2893 (https://github.com/yt-dlp/yt-dlp/issues/21))
2894 • SponsorBlock Integration: You can mark/remove sponsor sections in
2896 YouTube videos by utilizing the SponsorBlock (https://spon‐
2897 sor.ajay.app) API
2898 • Format Sorting: The default format sorting options have been changed
2900 so that higher resolution and better codecs will be now preferred in‐
2901 stead of simply using larger bitrate. Furthermore, you can now spec‐
2902 ify the sort order using -S. This allows for much easier format se‐
2903 lection than what is possible by simply using --format (examples)
2904 • Merged with animelover1984/youtube-dl: You get most of the features
2906 and improvements from animelover1984/youtube-dl
2907 (https://github.com/animelover1984/youtube-dl) including --write-com‐
2908 ments, BiliBiliSearch, BilibiliChannel, Embedding thumbnail in
2909 mp4/ogg/opus, playlist infojson etc. Note that NicoNico livestreams
2910 are not available. See #31 (https://github.com/yt-dlp/yt-
2911 dlp/pull/31) for details.
2912 • YouTube improvements:
2914 • Supports Clips, Stories (ytstories:<channel UCID>), Search (includ‐
2916 ing filters)*, YouTube Music Search, Channel-specific search,
2917 Search prefixes (ytsearch:, ytsearchdate:)*, Mixes, and Feeds (:yt‐
2918 fav, :ytwatchlater, :ytsubs, :ythistory, :ytrec, :ytnotif)
2919 • Fix for n-sig based throttling (https://github.com/ytdl-
2921 org/youtube-dl/issues/29326) *
2922 • Supports some (but not all) age-gated content without cookies
2924 • Download livestreams from the start using --live-from-start (exper‐
2926 imental)
2927 • 255kbps audio is extracted (if available) from YouTube Music when
2929 premium cookies are given
2930 • Channel URLs download all uploads of the channel, including shorts
2932 and live
2933 • Cookies from browser: Cookies can be automatically extracted from all
2935 major web browsers using --cookies-from-browser BROWS‐
2936 ER[+KEYRING][:PROFILE][::CONTAINER]
2937 • Download time range: Videos can be downloaded partially based on ei‐
2939 ther timestamps or chapters using --download-sections
2940 • Split video by chapters: Videos can be split into multiple files
2942 based on chapters using --split-chapters
2943 • Multi-threaded fragment downloads: Download multiple fragments of
2945 m3u8/mpd videos in parallel. Use --concurrent-fragments (-N) option
2946 to set the number of threads used
2947 • Aria2c with HLS/DASH: You can use aria2c as the external downloader
2949 for DASH(mpd) and HLS(m3u8) formats
2950 • New and fixed extractors: Many new extractors have been added and a
2952 lot of existing ones have been fixed. See the changelog or the list
2953 of supported sites
2954 • New MSOs: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
2956 • Subtitle extraction from manifests: Subtitles can be extracted from
2958 streaming media manifests. See commit/be6202f
2959 (https://github.com/yt-dlp/yt-dlp/com‐
2960 mit/be6202f12b97858b9d716e608394b51065d0419f) for details
2961 • Multiple paths and output templates: You can give different output
2963 templates and download paths for different types of files. You can
2964 also set a temporary path where intermediary files are downloaded to
2965 using --paths (-P)
2966 • Portable Configuration: Configuration files are automatically loaded
2968 from the home and root directories. See CONFIGURATION for details
2969 • Output template improvements: Output templates can now have date-time
2971 formatting, numeric offsets, object traversal etc. See output tem‐
2972 plate for details. Even more advanced operations can also be done
2973 with the help of --parse-metadata and --replace-in-metadata
2974 • Other new options: Many new options have been added such as --alias,
2976 --print, --concat-playlist, --wait-for-video, --retry-sleep, --sleep-
2977 requests, --convert-thumbnails, --force-download-archive, --force-
2978 overwrites, --break-match-filter etc
2979 • Improvements: Regex and other operators in --format/--match-filter,
2981 multiple --postprocessor-args and --downloader-args, faster archive
2982 checking, more format selection options, merge multi-video/audio,
2983 multiple --config-locations, --exec at different stages, etc
2984 • Plugins: Extractors and PostProcessors can be loaded from an external
2986 file. See plugins for details
2987 • Self updater: The releases can be updated using yt-dlp -U, and down‐
2989 graded using --update-to if required
2990 • Nightly builds: Automated nightly builds can be used with --update-to
2992 nightly
2993 See changelog or commits (https://github.com/yt-dlp/yt-dlp/commits) for
2995 the full list of changes
2996 Features marked with a * have been back-ported to youtube-dl
2998 Differences in default behavior
3000 Some of yt-dlp's default options are different from that of youtube-dl
3001 and youtube-dlc:
3002 • yt-dlp supports only Python 3.7+, and may remove support for more
3004 versions as they become EOL (https://devguide.python.org/ver‐
3005 sions/#python-release-cycle); while youtube-dl still supports Python
3006 2.6+ and 3.2+ (https://github.com/ytdl-org/youtube-dl/is‐
3007 sues/30568#issue-1118238743)
3008 • The options --auto-number (-A), --title (-t) and --literal (-l), no
3010 longer work. See removed options for details
3011 • avconv is not supported as an alternative to ffmpeg
3013 • yt-dlp stores config files in slightly different locations to
3015 youtube-dl. See CONFIGURATION for a list of correct locations
3016 • The default output template is %(title)s [%(id)s].%(ext)s. There is
3018 no real reason for this change. This was changed before yt-dlp was
3019 ever made public and now there are no plans to change it back to
3020 %(title)s-%(id)s.%(ext)s. Instead, you may use --compat-options
3021 filename
3022 • The default format sorting is different from youtube-dl and prefers
3024 higher resolution and better codecs rather than higher bitrates. You
3025 can use the --format-sort option to change this to any order you pre‐
3026 fer, or use --compat-options format-sort to use youtube-dl's sorting
3027 order
3028 • The default format selector is bv*+ba/b. This means that if a com‐
3030 bined video + audio format that is better than the best video-only
3031 format is found, the former will be preferred. Use -f bv+ba/b or
3032 --compat-options format-spec to revert this
3033 • Unlike youtube-dlc, yt-dlp does not allow merging multiple au‐
3035 dio/video streams into one file by default (since this conflicts with
3036 the use of -f bv*+ba). If needed, this feature must be enabled using
3037 --audio-multistreams and --video-multistreams. You can also use
3038 --compat-options multistreams to enable both
3039 • --no-abort-on-error is enabled by default. Use --abort-on-error or
3041 --compat-options abort-on-error to abort on errors instead
3042 • When writing metadata files such as thumbnails, description or infoj‐
3044 son, the same information (if available) is also written for
3045 playlists. Use --no-write-playlist-metafiles or --compat-options no-
3046 playlist-metafiles to not write these files
3047 • --add-metadata attaches the infojson to mkv files in addition to
3049 writing the metadata when used with --write-info-json. Use --no-em‐
3050 bed-info-json or --compat-options no-attach-info-json to revert this
3051 • Some metadata are embedded into different fields when using --add-
3053 metadata as compared to youtube-dl. Most notably, comment field con‐
3054 tains the webpage_url and synopsis contains the description. You can
3055 use --parse-metadata to modify this to your liking or use --compat-
3056 options embed-metadata to revert this
3057 • playlist_index behaves differently when used with options like
3059 --playlist-reverse and --playlist-items. See #302
3060 (https://github.com/yt-dlp/yt-dlp/issues/302) for details. You can
3061 use --compat-options playlist-index if you want to keep the earlier
3062 behavior
3063 • The output of -F is listed in a new format. Use --compat-options
3065 list-formats to revert this
3066 • Live chats (if available) are considered as subtitles. Use --sub-
3068 langs all,-live_chat to download all subtitles except live chat. You
3069 can also use --compat-options no-live-chat to prevent any live
3070 chat/danmaku from downloading
3071 • YouTube channel URLs download all uploads of the channel. To down‐
3073 load only the videos in a specific tab, pass the tab's URL. If the
3074 channel does not show the requested tab, an error will be raised.
3075 Also, /live URLs raise an error if there are no live videos instead
3076 of silently downloading the entire channel. You may use --compat-op‐
3077 tions no-youtube-channel-redirect to revert all these redirections
3078 • Unavailable videos are also listed for YouTube playlists. Use --com‐
3080 pat-options no-youtube-unavailable-videos to remove this
3081 • The upload dates extracted from YouTube are in UTC when available
3083 (https://github.com/yt-dlp/yt-
3084 dlp/blob/89e4d86171c7b7c997c77d4714542e0383bf0db0/yt_dlp/extrac‐
3085 tor/youtube.py#L3898-L3900). Use --compat-options no-youtube-prefer-
3086 utc-upload-date to prefer the non-UTC upload date.
3087 • If ffmpeg is used as the downloader, the downloading and merging of
3089 formats happen in a single step when possible. Use --compat-options
3090 no-direct-merge to revert this
3091 • Thumbnail embedding in mp4 is done with mutagen if possible. Use
3093 --compat-options embed-thumbnail-atomicparsley to force the use of
3094 AtomicParsley instead
3095 • Some internal metadata such as filenames are removed by default from
3097 the infojson. Use --no-clean-infojson or --compat-options no-clean-
3098 infojson to revert this
3099 • When --embed-subs and --write-subs are used together, the subtitles
3101 are written to disk and also embedded in the media file. You can use
3102 just --embed-subs to embed the subs and automatically delete the sep‐
3103 arate file. See #630 (comment) (https://github.com/yt-dlp/yt-dlp/is‐
3104 sues/630#issuecomment-893659460) for more info. --compat-options no-
3105 keep-subs can be used to revert this
3106 • certifi will be used for SSL root certificates, if installed. If you
3108 want to use system certificates (e.g. self-signed), use --compat-op‐
3109 tions no-certifi
3110 • yt-dlp's sanitization of invalid characters in filenames is differ‐
3112 ent/smarter than in youtube-dl. You can use --compat-options file‐
3113 name-sanitization to revert to youtube-dl's behavior
3114 • yt-dlp tries to parse the external downloader outputs into the stan‐
3116 dard progress output if possible (Currently implemented: [STRIKE‐
3117 OUT:aria2c] (https://github.com/yt-dlp/yt-dlp/issues/5931)). You can
3118 use --compat-options no-external-downloader-progress to get the down‐
3119 loader output as-is
3120 • yt-dlp versions between 2021.09.01 and 2023.01.02 applies --match-
3122 filter to nested playlists. This was an unintentional side-effect of
3123 8f18ac (https://github.com/yt-dlp/yt-dlp/com‐
3124 mit/8f18aca8717bb0dd49054555af8d386e5eda3a88) and is fixed in d7b460
3125 (https://github.com/yt-dlp/yt-dlp/com‐
3126 mit/d7b460d0e5fc710950582baed2e3fc616ed98a80). Use --compat-options
3127 playlist-match-filter to revert this
3128 For ease of use, a few more compat options are available:
3130 • --compat-options all: Use all compat options (Do NOT use)
3132 • --compat-options youtube-dl: Same as --compat-options all,-multi‐
3134 streams,-playlist-match-filter
3135 • --compat-options youtube-dlc: Same as --compat-options all,-no-live-
3137 chat,-no-youtube-channel-redirect,-playlist-match-filter
3138 • --compat-options 2021: Same as --compat-options 2022,no-certifi,file‐
3140 name-sanitization,no-youtube-prefer-utc-upload-date
3141 • --compat-options 2022: Same as --compat-options playlist-match-fil‐
3143 ter,no-external-downloader-progress. Use this to enable all future
3144 compat options
3145
3147 These are all the deprecated options and the current alternative to
3148 achieve the same effect
3149 Almost redundant options
3151 While these options are almost the same as their new counterparts,
3152 there are some differences that prevents them being redundant
3153 -j, --dump-json --print "%()j"
3155 -F, --list-formats --print formats_table
3156 --list-thumbnails --print thumbnails_table --print playlist:thumbnails_table
3157 --list-subs --print automatic_captions_table --print subtitles_table
3158 Redundant options
3160 While these options are redundant, they are still expected to be used
3161 due to their ease of use
3162 --get-description --print description
3164 --get-duration --print duration_string
3165 --get-filename --print filename
3166 --get-format --print format
3167 --get-id --print id
3168 --get-thumbnail --print thumbnail
3169 -e, --get-title --print title
3170 -g, --get-url --print urls
3171 --match-title REGEX --match-filter "title ~= (?i)REGEX"
3172 --reject-title REGEX --match-filter "title !~= (?i)REGEX"
3173 --min-views COUNT --match-filter "view_count >=? COUNT"
3174 --max-views COUNT --match-filter "view_count <=? COUNT"
3175 --break-on-reject Use --break-match-filter
3176 --user-agent UA --add-header "User-Agent:UA"
3177 --referer URL --add-header "Referer:URL"
3178 --playlist-start NUMBER -I NUMBER:
3179 --playlist-end NUMBER -I :NUMBER
3180 --playlist-reverse -I ::-1
3181 --no-playlist-reverse Default
3182 --no-colors --color no_color
3183 Not recommended
3185 While these options still work, their use is not recommended since
3186 there are other alternatives to achieve the same
3187 --force-generic-extractor --ies generic,default
3189 --exec-before-download CMD --exec "before_dl:CMD"
3190 --no-exec-before-download --no-exec
3191 --all-formats -f all
3192 --all-subs --sub-langs all --write-subs
3193 --print-json -j --no-simulate
3194 --autonumber-size NUMBER Use string formatting, e.g. %(autonumber)03d
3195 --autonumber-start NUMBER Use internal field formatting like %(autonumber+NUMBER)s
3196 --id -o "%(id)s.%(ext)s"
3197 --metadata-from-title FORMAT --parse-metadata "%(title)s:FORMAT"
3198 --hls-prefer-native --downloader "m3u8:native"
3199 --hls-prefer-ffmpeg --downloader "m3u8:ffmpeg"
3200 --list-formats-old --compat-options list-formats (Alias: --no-list-formats-as-table)
3201 --list-formats-as-table --compat-options -list-formats [Default] (Alias: --no-list-formats-old)
3202 --youtube-skip-dash-manifest --extractor-args "youtube:skip=dash" (Alias: --no-youtube-include-dash-manifest)
3203 --youtube-skip-hls-manifest --extractor-args "youtube:skip=hls" (Alias: --no-youtube-include-hls-manifest)
3204 --youtube-include-dash-manifest Default (Alias: --no-youtube-skip-dash-manifest)
3205 --youtube-include-hls-manifest Default (Alias: --no-youtube-skip-hls-manifest)
3206 --geo-bypass --xff "default"
3207 --no-geo-bypass --xff "never"
3208 --geo-bypass-country CODE --xff CODE
3209 --geo-bypass-ip-block IP_BLOCK --xff IP_BLOCK
3210 Developer options
3212 These options are not intended to be used by the end-user
3213 --test Download only part of video for testing extractors
3215 --load-pages Load pages dumped by --write-pages
3216 --youtube-print-sig-code For testing youtube signatures
3217 --allow-unplayable-formats List unplayable formats also
3218 --no-allow-unplayable-formats Default
3219 Old aliases
3221 These are aliases that are no longer documented for various reasons
3222 --avconv-location --ffmpeg-location
3224 --clean-infojson --clean-info-json
3225 --cn-verification-proxy URL --geo-verification-proxy URL
3226 --dump-headers --print-traffic
3227 --dump-intermediate-pages --dump-pages
3228 --force-write-download-archive --force-write-archive
3229 --load-info --load-info-json
3230 --no-clean-infojson --no-clean-info-json
3231 --no-split-tracks --no-split-chapters
3232 --no-write-srt --no-write-subs
3233 --prefer-unsecure --prefer-insecure
3234 --rate-limit RATE --limit-rate RATE
3235 --split-tracks --split-chapters
3236 --srt-lang LANGS --sub-langs LANGS
3237 --trim-file-names LENGTH --trim-filenames LENGTH
3238 --write-srt --write-subs
3239 --yes-overwrites --force-overwrites
3240 Sponskrub Options
3242 Support for SponSkrub (https://github.com/faissaloo/SponSkrub) has been
3243 deprecated in favor of the --sponsorblock options
3244 --sponskrub --sponsorblock-mark all
3246 --no-sponskrub --no-sponsorblock
3247 --sponskrub-cut --sponsorblock-remove all
3248 --no-sponskrub-cut --sponsorblock-remove -all
3249 --sponskrub-force Not applicable
3250 --no-sponskrub-force Not applicable
3251 --sponskrub-location Not applicable
3252 --sponskrub-args Not applicable
3253 No longer supported
3255 These options may no longer work as intended
3256 --prefer-avconv avconv is not officially supported by yt-dlp (Alias: --no-prefer-ffmpeg)
3258 --prefer-ffmpeg Default (Alias: --no-prefer-avconv)
3259 -C, --call-home Not implemented
3260 --no-call-home Default
3261 --include-ads No longer supported
3262 --no-include-ads Default
3263 --write-annotations No supported site has annotations now
3264 --no-write-annotations Default
3265 --compat-options seperate-video-versions No longer needed
3266 Removed
3268 These options were deprecated since 2014 and have now been entirely re‐
3269 moved
3270 -A, --auto-number -o "%(autonumber)s-%(id)s.%(ext)s"
3272 -t, -l, --title, --literal -o "%(title)s-%(id)s.%(ext)s"
3273
3275 See CONTRIBUTING.md for instructions on Opening an Issue and Contribut‐
3276 ing code to the project
3277
3279 See the Wiki (https://github.com/yt-dlp/yt-dlp/wiki) for more informa‐
3280 tion
3281 yt-dlp(1)