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 -i, --ignore-errors
33 Ignore download and postprocessing errors. The download will be
34 considered successful even if the postprocessing fails
35 --no-abort-on-error
37 Continue with next video on download errors; e.g. to skip un‐
38 available videos in a playlist (default)
39 --abort-on-error
41 Abort downloading of further videos if an error occurs (Alias:
42 --no-ignore-errors)
43 --dump-user-agent
45 Display the current user-agent and exit
46 --list-extractors
48 List all supported extractors and exit
49 --extractor-descriptions
51 Output descriptions of all supported extractors and exit
52 --use-extractors NAMES
54 Extractor names to use separated by commas. You can also use
55 regexes, "all", "default" and "end" (end URL matching); e.g.
56 --ies "holodex.*,end,youtube". Prefix the name with a "-" to
57 exclude it, e.g. --ies default,-generic. Use --list-extractors
58 for a list of extractor names. (Alias: --ies)
59 --default-search PREFIX
61 Use this prefix for unqualified URLs. E.g. "gvsearch2:python"
62 downloads two videos from google videos for the search term
63 "python". Use the value "auto" to let yt-dlp guess ("auto_warn‐
64 ing" to emit a warning when guessing). "error" just throws an
65 error. The default value "fixup_error" repairs broken URLs, but
66 emits an error if this is not possible instead of searching
67 --ignore-config
69 Don't load any more configuration files except those given by
70 --config-locations. For backward compatibility, if this option
71 is found inside the system configuration file, the user configu‐
72 ration is not loaded. (Alias: --no-config)
73 --no-config-locations
75 Do not load any custom configuration files (default). When giv‐
76 en inside a configuration file, ignore all previous --config-lo‐
77 cations defined in the current file
78 --config-locations PATH
80 Location of the main configuration file; either the path to the
81 config or its containing directory ("-" for stdin). Can be used
82 multiple times and inside other configuration files
83 --flat-playlist
85 Do not extract the videos of a playlist, only list them
86 --no-flat-playlist
88 Extract the videos of a playlist
89 --live-from-start
91 Download livestreams from the start. Currently only supported
92 for YouTube (Experimental)
93 --no-live-from-start
95 Download livestreams from the current time (default)
96 --wait-for-video MIN[-MAX]
98 Wait for scheduled streams to become available. Pass the mini‐
99 mum number of seconds (or range) to wait between retries
100 --no-wait-for-video
102 Do not wait for scheduled streams (default)
103 --mark-watched
105 Mark videos watched (even with --simulate)
106 --no-mark-watched
108 Do not mark videos watched (default)
109 --no-colors
111 Do not emit color codes in output (Alias: --no-colours)
112 --compat-options OPTS
114 Options that can help keep compatibility with youtube-dl or
115 youtube-dlc configurations by reverting some of the changes made
116 in yt-dlp. See "Differences in default behavior" for details
117 --alias ALIASES OPTIONS
119 Create aliases for an option string. Unless an alias starts
120 with a dash "-", it is prefixed with "--". Arguments are parsed
121 according to the Python string formatting mini-language. E.g.
122 --alias get-audio,-X "-S=aext:{0},abr -x --audio-format {0}"
123 creates options "--get-audio" and "-X" that takes an argument
124 (ARG0) and expands to "-S=aext:ARG0,abr -x --audio-format ARG0".
125 All defined aliases are listed in the --help output. Alias op‐
126 tions can trigger more aliases; so be careful to avoid defining
127 recursive options. As a safety measure, each alias may be trig‐
128 gered a maximum of 100 times. This option can be used multiple
129 times
130 Network Options:
132 --proxy URL
133 Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS
134 proxy, specify a proper scheme, e.g. socks5://us‐
135 er:pass@127.0.0.1:1080/. Pass in an empty string (--proxy "")
136 for direct connection
137 --socket-timeout SECONDS
139 Time to wait before giving up, in seconds
140 --source-address IP
142 Client-side IP address to bind to
143 -4, --force-ipv4
145 Make all connections via IPv4
146 -6, --force-ipv6
148 Make all connections via IPv6
149 --enable-file-urls
151 Enable file:// URLs. This is disabled by default for security
152 reasons.
153 Geo-restriction:
155 --geo-verification-proxy URL
156 Use this proxy to verify the IP address for some geo-restricted
157 sites. The default proxy specified by --proxy (or none, if the
158 option is not present) is used for the actual downloading
159 --geo-bypass
161 Bypass geographic restriction via faking X-Forwarded-For HTTP
162 header (default)
163 --no-geo-bypass
165 Do not bypass geographic restriction via faking X-Forwarded-For
166 HTTP header
167 --geo-bypass-country CODE
169 Force bypass geographic restriction with explicitly provided
170 two-letter ISO 3166-2 country code
171 --geo-bypass-ip-block IP_BLOCK
173 Force bypass geographic restriction with explicitly provided IP
174 block in CIDR notation
175 Video Selection:
177 -I, --playlist-items ITEM_SPEC
178 Comma separated playlist_index of the items to download. You
179 can specify a range using "[START]:[STOP][:STEP]". For backward
180 compatibility, START-STOP is also supported. Use negative in‐
181 dices to count from the right and negative STEP to download in
182 reverse order. E.g. "-I 1:3,7,-5::2" used on a playlist of
183 size 15 will download the items at index 1,2,3,7,11,13,15
184 --min-filesize SIZE
186 Abort download if filesize is smaller than SIZE, e.g. 50k or
187 44.6M
188 --max-filesize SIZE
190 Abort download if filesize is larger than SIZE, e.g. 50k or
191 44.6M
192 --date DATE
194 Download only videos uploaded on this date. The date can be
195 "YYYYMMDD" or in the format [now|today|yesterday][-
196 N[day|week|month|year]]. E.g. "--date today-2weeks" downloads
197 only videos uploaded on the same day two weeks ago
198 --datebefore DATE
200 Download only videos uploaded on or before this date. The date
201 formats accepted is the same as --date
202 --dateafter DATE
204 Download only videos uploaded on or after this date. The date
205 formats accepted is the same as --date
206 --match-filters FILTER
208 Generic video filter. Any "OUTPUT TEMPLATE" field can be com‐
209 pared with a number or a string using the operators defined in
210 "Filtering Formats". You can also simply specify a field to
211 match if the field is present, use "!field" to check if the
212 field is not present, and "&" to check multiple conditions. Use
213 a "" to escape "&" or quotes if needed. If used multiple times,
214 the filter matches if atleast one of the conditions are met.
215 E.g. --match-filter !is_live --match-filter "like_count>?100 &
216 description~='(?i)& dogs" matches only videos that are not live
217 OR those that have a like count more than 100 (or the like field
218 is not available) and also has a description that contains the
219 phrase "cats & dogs" (caseless). Use "--match-filter -" to in‐
220 teractively ask whether to download each video
221 --no-match-filter
223 Do not use generic video filter (default)
224 --no-playlist
226 Download only the video, if the URL refers to a video and a
227 playlist
228 --yes-playlist
230 Download the playlist, if the URL refers to a video and a
231 playlist
232 --age-limit YEARS
234 Download only videos suitable for the given age
235 --download-archive FILE
237 Download only videos not listed in the archive file. Record the
238 IDs of all downloaded videos in it
239 --no-download-archive
241 Do not use archive file (default)
242 --max-downloads NUMBER
244 Abort after downloading NUMBER files
245 --break-on-existing
247 Stop the download process when encountering a file that is in
248 the archive
249 --break-on-reject
251 Stop the download process when encountering a file that has been
252 filtered out
253 --break-per-input
255 Alters --max-downloads, --break-on-existing, --break-on-reject,
256 and autonumber to reset per input URL
257 --no-break-per-input
259 --break-on-existing and similar options terminates the entire
260 download queue
261 --skip-playlist-after-errors N
263 Number of allowed failures until the rest of the playlist is
264 skipped
265 Download Options:
267 -N, --concurrent-fragments N
268 Number of fragments of a dash/hlsnative video that should be
269 downloaded concurrently (default is 1)
270 -r, --limit-rate RATE
272 Maximum download rate in bytes per second, e.g. 50K or 4.2M
273 --throttled-rate RATE
275 Minimum download rate in bytes per second below which throttling
276 is assumed and the video data is re-extracted, e.g. 100K
277 -R, --retries RETRIES
279 Number of retries (default is 10), or "infinite"
280 --file-access-retries RETRIES
282 Number of times to retry on file access error (default is 3), or
283 "infinite"
284 --fragment-retries RETRIES
286 Number of retries for a fragment (default is 10), or "infinite"
287 (DASH, hlsnative and ISM)
288 --retry-sleep [TYPE:]EXPR
290 Time to sleep between retries in seconds (optionally) prefixed
291 by the type of retry (http (default), fragment, file_access, ex‐
292 tractor) to apply the sleep to. EXPR can be a number, lin‐
293 ear=START[:END[:STEP=1]] or exp=START[:END[:BASE=2]]. This op‐
294 tion can be used multiple times to set the sleep for the differ‐
295 ent retry types, e.g. --retry-sleep linear=1::2 --retry-sleep
296 fragment:exp=1:20
297 --skip-unavailable-fragments
299 Skip unavailable fragments for DASH, hlsnative and ISM downloads
300 (default) (Alias: --no-abort-on-unavailable-fragments)
301 --abort-on-unavailable-fragments
303 Abort download if a fragment is unavailable (Alias: --no-skip-
304 unavailable-fragments)
305 --keep-fragments
307 Keep downloaded fragments on disk after downloading is finished
308 --no-keep-fragments
310 Delete downloaded fragments after downloading is finished (de‐
311 fault)
312 --buffer-size SIZE
314 Size of download buffer, e.g. 1024 or 16K (default is 1024)
315 --resize-buffer
317 The buffer size is automatically resized from an initial value
318 of --buffer-size (default)
319 --no-resize-buffer
321 Do not automatically adjust the buffer size
322 --http-chunk-size SIZE
324 Size of a chunk for chunk-based HTTP downloading, e.g. 10485760
325 or 10M (default is disabled). May be useful for bypassing band‐
326 width throttling imposed by a webserver (experimental)
327 --playlist-random
329 Download playlist videos in random order
330 --lazy-playlist
332 Process entries in the playlist as they are received. This dis‐
333 ables n_entries, --playlist-random and --playlist-reverse
334 --no-lazy-playlist
336 Process videos in the playlist only after the entire playlist is
337 parsed (default)
338 --xattr-set-filesize
340 Set file xattribute ytdl.filesize with expected file size
341 --hls-use-mpegts
343 Use the mpegts container for HLS videos; allowing some players
344 to play the video while downloading, and reducing the chance of
345 file corruption if download is interrupted. This is enabled by
346 default for live streams
347 --no-hls-use-mpegts
349 Do not use the mpegts container for HLS videos. This is default
350 when not downloading live streams
351 --download-sections REGEX
353 Download only chapters whose title matches the given regular ex‐
354 pression. Time ranges prefixed by a "" can also be used in
355 place of chapters to download the specified range. Needs ffmpeg.
356 This option can be used multiple times to download multiple sec‐
357 tions, e.g. --download-sections "10:15-inf" --download-sections
358 "intro"
359 --downloader [PROTO:]NAME
361 Name or path of the external downloader to use (optionally) pre‐
362 fixed by the protocols (http, ftp, m3u8, dash, rstp, rtmp, mms)
363 to use it for. Currently supports native, aria2c, avconv, axel,
364 curl, ffmpeg, httpie, wget. You can use this option multiple
365 times to set different downloaders for different protocols.
366 E.g. --downloader aria2c --downloader "dash,m3u8:native" will
367 use aria2c for http/ftp downloads, and the native downloader for
368 dash/m3u8 downloads (Alias: --external-downloader)
369 --downloader-args NAME:ARGS
371 Give these arguments to the external downloader. Specify the
372 downloader name and the arguments separated by a colon ":". For
373 ffmpeg, arguments can be passed to different positions using the
374 same syntax as --postprocessor-args. You can use this option
375 multiple times to give different arguments to different down‐
376 loaders (Alias: --external-downloader-args)
377 Filesystem Options:
379 -a, --batch-file FILE
380 File containing URLs to download ("-" for stdin), one URL per
381 line. Lines starting with "#", ";" or "]" are considered as
382 comments and ignored
383 --no-batch-file
385 Do not read URLs from batch file (default)
386 -P, --paths [TYPES:]PATH
388 The paths where the files should be downloaded. Specify the
389 type of file and the path separated by a colon ":". All the
390 same TYPES as --output are supported. Additionally, you can al‐
391 so provide "home" (default) and "temp" paths. All intermediary
392 files are first downloaded to the temp path and then the final
393 files are moved over to the home path after download is fin‐
394 ished. This option is ignored if --output is an absolute path
395 -o, --output [TYPES:]TEMPLATE
397 Output filename template; see "OUTPUT TEMPLATE" for details
398 --output-na-placeholder TEXT
400 Placeholder for unavailable fields in "OUTPUT TEMPLATE" (de‐
401 fault: "NA")
402 --restrict-filenames
404 Restrict filenames to only ASCII characters, and avoid "&" and
405 spaces in filenames
406 --no-restrict-filenames
408 Allow Unicode characters, "&" and spaces in filenames (default)
409 --windows-filenames
411 Force filenames to be Windows-compatible
412 --no-windows-filenames
414 Make filenames Windows-compatible only if using Windows (de‐
415 fault)
416 --trim-filenames LENGTH
418 Limit the filename length (excluding extension) to the specified
419 number of characters
420 -w, --no-overwrites
422 Do not overwrite any files
423 --force-overwrites
425 Overwrite all video and metadata files. This option includes
426 --no-continue
427 --no-force-overwrites
429 Do not overwrite the video, but overwrite related files (de‐
430 fault)
431 -c, --continue
433 Resume partially downloaded files/fragments (default)
434 --no-continue
436 Do not resume partially downloaded fragments. If the file is
437 not fragmented, restart download of the entire file
438 --part Use .part files instead of writing directly into output file
440 (default)
441 --no-part
443 Do not use .part files - write directly into output file
444 --mtime
446 Use the Last-modified header to set the file modification time
447 (default)
448 --no-mtime
450 Do not use the Last-modified header to set the file modification
451 time
452 --write-description
454 Write video description to a .description file
455 --no-write-description
457 Do not write video description (default)
458 --write-info-json
460 Write video metadata to a .info.json file (this may contain per‐
461 sonal information)
462 --no-write-info-json
464 Do not write video metadata (default)
465 --write-playlist-metafiles
467 Write playlist metadata in addition to the video metadata when
468 using --write-info-json, --write-description etc. (default)
469 --no-write-playlist-metafiles
471 Do not write playlist metadata when using --write-info-json,
472 --write-description etc.
473 --clean-info-json
475 Remove some private fields such as filenames from the infojson.
476 Note that it could still contain some personal information (de‐
477 fault)
478 --no-clean-info-json
480 Write all fields to the infojson
481 --write-comments
483 Retrieve video comments to be placed in the infojson. The com‐
484 ments are fetched even without this option if the extraction is
485 known to be quick (Alias: --get-comments)
486 --no-write-comments
488 Do not retrieve video comments unless the extraction is known to
489 be quick (Alias: --no-get-comments)
490 --load-info-json FILE
492 JSON file containing the video information (created with the
493 "--write-info-json" option)
494 --cookies FILE
496 Netscape formatted file to read cookies from and dump cookie jar
497 in
498 --no-cookies
500 Do not read/dump cookies from/to file (default)
501 --cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]
503 The name of the browser to load cookies from. Currently sup‐
504 ported browsers are: brave, chrome, chromium, edge, firefox,
505 opera, safari, vivaldi. Optionally, the KEYRING used for de‐
506 crypting Chromium cookies on Linux, the name/path of the PROFILE
507 to load cookies from, and the CONTAINER name (if Firefox)
508 ("none" for no container) can be given with their respective
509 seperators. By default, all containers of the most recently ac‐
510 cessed profile are used. Currently supported keyrings are: ba‐
511 sictext, gnomekeyring, kwallet
512 --no-cookies-from-browser
514 Do not load cookies from browser (default)
515 --cache-dir DIR
517 Location in the filesystem where yt-dlp can store some download‐
518 ed information (such as client ids and signatures) permanently.
519 By default ${XDG_CACHE_HOME}/yt-dlp
520 --no-cache-dir
522 Disable filesystem caching
523 --rm-cache-dir
525 Delete all filesystem cache files
526 Thumbnail Options:
528 --write-thumbnail
529 Write thumbnail image to disk
530 --no-write-thumbnail
532 Do not write thumbnail image to disk (default)
533 --write-all-thumbnails
535 Write all thumbnail image formats to disk
536 --list-thumbnails
538 List available thumbnails of each video. Simulate unless --no-
539 simulate is used
540 Internet Shortcut Options:
542 --write-link
543 Write an internet shortcut file, depending on the current plat‐
544 form (.url, .webloc or .desktop). The URL may be cached by the
545 OS
546 --write-url-link
548 Write a .url Windows internet shortcut. The OS caches the URL
549 based on the file path
550 --write-webloc-link
552 Write a .webloc macOS internet shortcut
553 --write-desktop-link
555 Write a .desktop Linux internet shortcut
556 Verbosity and Simulation Options:
558 -q, --quiet
559 Activate quiet mode. If used with --verbose, print the log to
560 stderr
561 --no-warnings
563 Ignore warnings
564 -s, --simulate
566 Do not download the video and do not write anything to disk
567 --no-simulate
569 Download the video even if printing/listing options are used
570 --ignore-no-formats-error
572 Ignore "No video formats" error. Useful for extracting metadata
573 even if the videos are not actually available for download (ex‐
574 perimental)
575 --no-ignore-no-formats-error
577 Throw error when no downloadable video formats are found (de‐
578 fault)
579 --skip-download
581 Do not download the video but write all related files (Alias:
582 --no-download)
583 -O, --print [WHEN:]TEMPLATE
585 Field name or output template to print to screen, optionally
586 prefixed with when to print it, separated by a ":". Supported
587 values of "WHEN" are the same as that of --use-postprocessor
588 (default: video). Implies --quiet. Implies --simulate unless
589 --no-simulate or later stages of WHEN are used. This option can
590 be used multiple times
591 --print-to-file [WHEN:]TEMPLATE FILE
593 Append given template to the file. The values of WHEN and TEM‐
594 PLATE are same as that of --print. FILE uses the same syntax as
595 the output template. This option can be used multiple times
596 -j, --dump-json
598 Quiet, but print JSON information for each video. Simulate un‐
599 less --no-simulate is used. See "OUTPUT TEMPLATE" for a de‐
600 scription of available keys
601 -J, --dump-single-json
603 Quiet, but print JSON information for each url or infojson
604 passed. Simulate unless --no-simulate is used. If the URL
605 refers to a playlist, the whole playlist information is dumped
606 in a single line
607 --force-write-archive
609 Force download archive entries to be written as far as no errors
610 occur, even if -s or another simulation option is used (Alias:
611 --force-download-archive)
612 --newline
614 Output progress bar as new lines
615 --no-progress
617 Do not print progress bar
618 --progress
620 Show progress bar, even if in quiet mode
621 --console-title
623 Display progress in console titlebar
624 --progress-template [TYPES:]TEMPLATE
626 Template for progress outputs, optionally prefixed with one of
627 "download:" (default), "download-title:" (the console title),
628 "postprocess:", or "postprocess-title:". The video's fields are
629 accessible under the "info" key and the progress attributes are
630 accessible under "progress" key. E.g. --console-title
631 --progress-template "download-title:%(in‐
632 fo.id)s-%(progress.eta)s"
633 -v, --verbose
635 Print various debugging information
636 --dump-pages
638 Print downloaded pages encoded using base64 to debug problems
639 (very verbose)
640 --write-pages
642 Write downloaded intermediary pages to files in the current di‐
643 rectory to debug problems
644 --print-traffic
646 Display sent and read HTTP traffic
647 Workarounds:
649 --encoding ENCODING
650 Force the specified encoding (experimental)
651 --legacy-server-connect
653 Explicitly allow HTTPS connection to servers that do not support
654 RFC 5746 secure renegotiation
655 --no-check-certificates
657 Suppress HTTPS certificate validation
658 --prefer-insecure
660 Use an unencrypted connection to retrieve information about the
661 video (Currently supported only for YouTube)
662 --add-header FIELD:VALUE
664 Specify a custom HTTP header and its value, separated by a colon
665 ":". You can use this option multiple times
666 --bidi-workaround
668 Work around terminals that lack bidirectional text support. Re‐
669 quires bidiv or fribidi executable in PATH
670 --sleep-requests SECONDS
672 Number of seconds to sleep between requests during data extrac‐
673 tion
674 --sleep-interval SECONDS
676 Number of seconds to sleep before each download. This is the
677 minimum time to sleep when used along with --max-sleep-interval
678 (Alias: --min-sleep-interval)
679 --max-sleep-interval SECONDS
681 Maximum number of seconds to sleep. Can only be used along with
682 --min-sleep-interval
683 --sleep-subtitles SECONDS
685 Number of seconds to sleep before each subtitle download
686 Video Format Options:
688 -f, --format FORMAT
689 Video format code, see "FORMAT SELECTION" for more details
690 -S, --format-sort SORTORDER
692 Sort the formats by the fields given, see "Sorting Formats" for
693 more details
694 --format-sort-force
696 Force user specified sort order to have precedence over all
697 fields, see "Sorting Formats" for more details (Alias: --S-
698 force)
699 --no-format-sort-force
701 Some fields have precedence over the user specified sort order
702 (default)
703 --video-multistreams
705 Allow multiple video streams to be merged into a single file
706 --no-video-multistreams
708 Only one video stream is downloaded for each output file (de‐
709 fault)
710 --audio-multistreams
712 Allow multiple audio streams to be merged into a single file
713 --no-audio-multistreams
715 Only one audio stream is downloaded for each output file (de‐
716 fault)
717 --prefer-free-formats
719 Prefer video formats with free containers over non-free ones of
720 same quality. Use with "-S ext" to strictly prefer free con‐
721 tainers irrespective of quality
722 --no-prefer-free-formats
724 Don't give any special preference to free containers (default)
725 --check-formats
727 Make sure formats are selected only from those that are actually
728 downloadable
729 --check-all-formats
731 Check all formats for whether they are actually downloadable
732 --no-check-formats
734 Do not check that the formats are actually downloadable
735 -F, --list-formats
737 List available formats of each video. Simulate unless --no-sim‐
738 ulate is used
739 --merge-output-format FORMAT
741 Containers that may be used when merging formats, separated by
742 "/", e.g. "mp4/mkv". Ignored if no merge is required. (cur‐
743 rently supported: avi, flv, mkv, mov, mp4, webm)
744 Subtitle Options:
746 --write-subs
747 Write subtitle file
748 --no-write-subs
750 Do not write subtitle file (default)
751 --write-auto-subs
753 Write automatically generated subtitle file (Alias: --write-au‐
754 tomatic-subs)
755 --no-write-auto-subs
757 Do not write auto-generated subtitles (default) (Alias: --no-
758 write-automatic-subs)
759 --list-subs
761 List available subtitles of each video. Simulate unless --no-
762 simulate is used
763 --sub-format FORMAT
765 Subtitle format; accepts formats preference, e.g. "srt" or
766 "ass/srt/best"
767 --sub-langs LANGS
769 Languages of the subtitles to download (can be regex) or "all"
770 separated by commas, e.g. --sub-langs "en.*,ja". You can pre‐
771 fix the language code with a "-" to exclude it from the request‐
772 ed languages, e.g. --sub-langs all,-live_chat. Use --list-subs
773 for a list of available language tags
774 Authentication Options:
776 -u, --username USERNAME
777 Login with this account ID
778 -p, --password PASSWORD
780 Account password. If this option is left out, yt-dlp will ask
781 interactively
782 -2, --twofactor TWOFACTOR
784 Two-factor authentication code
785 -n, --netrc
787 Use .netrc authentication data
788 --netrc-location PATH
790 Location of .netrc authentication data; either the path or its
791 containing directory. Defaults to ~/.netrc
792 --video-password PASSWORD
794 Video password (vimeo, youku)
795 --ap-mso MSO
797 Adobe Pass multiple-system operator (TV provider) identifier,
798 use --ap-list-mso for a list of available MSOs
799 --ap-username USERNAME
801 Multiple-system operator account login
802 --ap-password PASSWORD
804 Multiple-system operator account password. If this option is
805 left out, yt-dlp will ask interactively
806 --ap-list-mso
808 List all supported multiple-system operators
809 --client-certificate CERTFILE
811 Path to client certificate file in PEM format. May include the
812 private key
813 --client-certificate-key KEYFILE
815 Path to private key file for client certificate
816 --client-certificate-password PASSWORD
818 Password for client certificate private key, if encrypted. If
819 not provided, and the key is encrypted, yt-dlp will ask interac‐
820 tively
821 Post-Processing Options:
823 -x, --extract-audio
824 Convert video files to audio-only files (requires ffmpeg and ff‐
825 probe)
826 --audio-format FORMAT
828 Format to convert the audio to when -x is used. (currently sup‐
829 ported: best (default), aac, alac, flac, m4a, mp3, opus, vorbis,
830 wav). You can specify multiple rules using similar syntax as
831 --remux-video
832 --audio-quality QUALITY
834 Specify ffmpeg audio quality to use when converting the audio
835 with -x. Insert a value between 0 (best) and 10 (worst) for VBR
836 or a specific bitrate like 128K (default 5)
837 --remux-video FORMAT
839 Remux the video into another container if necessary (currently
840 supported: avi, flv, gif, mkv, mov, mp4, webm, aac, aiff, alac,
841 flac, m4a, mka, mp3, ogg, opus, vorbis, wav). If target con‐
842 tainer does not support the video/audio codec, remuxing will
843 fail. You can specify multiple rules; e.g.
844 "aac>m4a/mov>mp4/mkv" will remux aac to m4a, mov to mp4 and any‐
845 thing else to mkv
846 --recode-video FORMAT
848 Re-encode the video into another format if necessary. The syn‐
849 tax and supported formats are the same as --remux-video
850 --postprocessor-args NAME:ARGS
852 Give these arguments to the postprocessors. Specify the post‐
853 processor/executable name and the arguments separated by a colon
854 ":" to give the argument to the specified postprocessor/exe‐
855 cutable. Supported PP are: Merger, ModifyChapters, SplitChap‐
856 ters, ExtractAudio, VideoRemuxer, VideoConvertor, Metadata, Em‐
857 bedSubtitle, EmbedThumbnail, SubtitlesConvertor, ThumbnailsCon‐
858 vertor, FixupStretched, FixupM4a, FixupM3u8, FixupTimestamp and
859 FixupDuration. The supported executables are: AtomicParsley,
860 FFmpeg and FFprobe. You can also specify "PP+EXE:ARGS" to give
861 the arguments to the specified executable only when being used
862 by the specified postprocessor. Additionally, for ffmpeg/ff‐
863 probe, "_i"/"_o" can be appended to the prefix optionally fol‐
864 lowed by a number to pass the argument before the specified in‐
865 put/output file, e.g. --ppa "Merger+ffmpeg_i1:-v quiet". You
866 can use this option multiple times to give different arguments
867 to different postprocessors. (Alias: --ppa)
868 -k, --keep-video
870 Keep the intermediate video file on disk after post-processing
871 --no-keep-video
873 Delete the intermediate video file after post-processing (de‐
874 fault)
875 --post-overwrites
877 Overwrite post-processed files (default)
878 --no-post-overwrites
880 Do not overwrite post-processed files
881 --embed-subs
883 Embed subtitles in the video (only for mp4, webm and mkv videos)
884 --no-embed-subs
886 Do not embed subtitles (default)
887 --embed-thumbnail
889 Embed thumbnail in the video as cover art
890 --no-embed-thumbnail
892 Do not embed thumbnail (default)
893 --embed-metadata
895 Embed metadata to the video file. Also embeds chapters/infojson
896 if present unless --no-embed-chapters/--no-embed-info-json are
897 used (Alias: --add-metadata)
898 --no-embed-metadata
900 Do not add metadata to file (default) (Alias: --no-add-metadata)
901 --embed-chapters
903 Add chapter markers to the video file (Alias: --add-chapters)
904 --no-embed-chapters
906 Do not add chapter markers (default) (Alias: --no-add-chapters)
907 --embed-info-json
909 Embed the infojson as an attachment to mkv/mka video files
910 --no-embed-info-json
912 Do not embed the infojson as an attachment to the video file
913 --parse-metadata [WHEN:]FROM:TO
915 Parse additional metadata like title/artist from other fields;
916 see "MODIFYING METADATA" for details. Supported values of
917 "WHEN" are the same as that of --use-postprocessor (default:
918 pre_process)
919 --replace-in-metadata [WHEN:]FIELDS REGEX REPLACE
921 Replace text in a metadata field using the given regex. This
922 option can be used multiple times. Supported values of "WHEN"
923 are the same as that of --use-postprocessor (default:
924 pre_process)
925 --xattrs
927 Write metadata to the video file's xattrs (using dublin core and
928 xdg standards)
929 --concat-playlist POLICY
931 Concatenate videos in a playlist. One of "never", "always", or
932 "multi_video" (default; only when the videos form a single
933 show). All the video files must have same codecs and number of
934 streams to be concatable. The "pl_video:" prefix can be used
935 with "--paths" and "--output" to set the output filename for the
936 concatenated files. See "OUTPUT TEMPLATE" for details
937 --fixup POLICY
939 Automatically correct known faults of the file. One of never
940 (do nothing), warn (only emit a warning), detect_or_warn (the
941 default; fix file if we can, warn otherwise), force (try fixing
942 even if file already exists)
943 --ffmpeg-location PATH
945 Location of the ffmpeg binary; either the path to the binary or
946 its containing directory
947 --exec [WHEN:]CMD
949 Execute a command, optionally prefixed with when to execute it,
950 separated by a ":". Supported values of "WHEN" are the same as
951 that of --use-postprocessor (default: after_move). Same syntax
952 as the output template can be used to pass any field as argu‐
953 ments to the command. After download, an additional field
954 "filepath" that contains the final path of the downloaded file
955 is also available, and if no fields are passed,
956 %(filepath,_filename|)q is appended to the end of the command.
957 This option can be used multiple times
958 --no-exec
960 Remove any previously defined --exec
961 --convert-subs FORMAT
963 Convert the subtitles to another format (currently supported:
964 ass, lrc, srt, vtt) (Alias: --convert-subtitles)
965 --convert-thumbnails FORMAT
967 Convert the thumbnails to another format (currently supported:
968 jpg, png, webp). You can specify multiple rules using similar
969 syntax as --remux-video
970 --split-chapters
972 Split video into multiple files based on internal chapters. The
973 "chapter:" prefix can be used with "--paths" and "--output" to
974 set the output filename for the split files. See "OUTPUT TEM‐
975 PLATE" for details
976 --no-split-chapters
978 Do not split video based on chapters (default)
979 --remove-chapters REGEX
981 Remove chapters whose title matches the given regular expres‐
982 sion. The syntax is the same as --download-sections. This op‐
983 tion can be used multiple times
984 --no-remove-chapters
986 Do not remove any chapters from the file (default)
987 --force-keyframes-at-cuts
989 Force keyframes at cuts when downloading/splitting/removing sec‐
990 tions. This is slow due to needing a re-encode, but the result‐
991 ing video may have fewer artifacts around the cuts
992 --no-force-keyframes-at-cuts
994 Do not force keyframes around the chapters when cutting/split‐
995 ting (default)
996 --use-postprocessor NAME[:ARGS]
998 The (case sensitive) name of plugin postprocessors to be en‐
999 abled, and (optionally) arguments to be passed to it, separated
1000 by a colon ":". ARGS are a semicolon ";" delimited list of
1001 NAME=VALUE. The "when" argument determines when the postproces‐
1002 sor is invoked. It can be one of "pre_process" (after video ex‐
1003 traction), "after_filter" (after video passes filter), "video"
1004 (after --format; before --print/--output), "before_dl" (before
1005 each video download), "post_process" (after each video download;
1006 default), "after_move" (after moving video file to it's final
1007 locations), "after_video" (after downloading and processing all
1008 formats of a video), or "playlist" (at end of playlist). This
1009 option can be used multiple times to add different postproces‐
1010 sors
1011 SponsorBlock Options:
1013 Make chapter entries for, or remove various segments (sponsor, intro‐
1014 ductions, etc.) from downloaded YouTube videos using the SponsorBlock
1015 API (https://sponsor.ajay.app)
1016 --sponsorblock-mark CATS
1018 SponsorBlock categories to create chapters for, separated by
1019 commas. Available categories are sponsor, intro, outro, self‐
1020 promo, preview, filler, interaction, music_offtopic, poi_high‐
1021 light, chapter, all and default (=all). You can prefix the cat‐
1022 egory with a "-" to exclude it. See [1] for description of the
1023 categories. E.g. --sponsorblock-mark all,-preview [1]
1024 https://wiki.sponsor.ajay.app/w/Segment_Categories
1025 --sponsorblock-remove CATS
1027 SponsorBlock categories to be removed from the video file, sepa‐
1028 rated by commas. If a category is present in both mark and re‐
1029 move, remove takes precedence. The syntax and available cate‐
1030 gories are the same as for --sponsorblock-mark except that "de‐
1031 fault" refers to "all,-filler" and poi_highlight, chapter are
1032 not available
1033 --sponsorblock-chapter-title TEMPLATE
1035 An output template for the title of the SponsorBlock chapters
1036 created by --sponsorblock-mark. The only available fields are
1037 start_time, end_time, category, categories, name, catego‐
1038 ry_names. Defaults to "[SponsorBlock]: %(category_names)l"
1039 --no-sponsorblock
1041 Disable both --sponsorblock-mark and --sponsorblock-remove
1042 --sponsorblock-api URL
1044 SponsorBlock API location, defaults to https://sponsor.ajay.app
1045 Extractor Options:
1047 --extractor-retries RETRIES
1048 Number of retries for known extractor errors (default is 3), or
1049 "infinite"
1050 --allow-dynamic-mpd
1052 Process dynamic DASH manifests (default) (Alias: --no-ignore-dy‐
1053 namic-mpd)
1054 --ignore-dynamic-mpd
1056 Do not process dynamic DASH manifests (Alias: --no-allow-dynam‐
1057 ic-mpd)
1058 --hls-split-discontinuity
1060 Split HLS playlists to different formats at discontinuities such
1061 as ad breaks
1062 --no-hls-split-discontinuity
1064 Do not split HLS playlists to different formats at discontinu‐
1065 ities such as ad breaks (default)
1066 --extractor-args IE_KEY:ARGS
1068 Pass ARGS arguments to the IE_KEY extractor. See "EXTRACTOR AR‐
1069 GUMENTS" for details. You can use this option multiple times to
1070 give arguments for different extractors
1071
1073 You can configure yt-dlp by placing any supported command line option
1074 to a configuration file. The configuration is loaded from the follow‐
1075 ing locations:
1076 1. Main Configuration:
1078 • The file given by --config-location
1080 2. Portable Configuration: (Recommended for portable installations)
1082 • If using a binary, yt-dlp.conf in the same directory as the bina‐
1084 ry
1085 • If running from source-code, yt-dlp.conf in the parent directory
1087 of yt_dlp
1088 3. Home Configuration:
1090 • yt-dlp.conf in the home path given by -P
1092 • If -P is not given, the current directory is searched
1094 4. User Configuration:
1096 • ${XDG_CONFIG_HOME}/yt-dlp.conf
1098 • ${XDG_CONFIG_HOME}/yt-dlp/config (recommended on Linux/macOS)
1100 • ${XDG_CONFIG_HOME}/yt-dlp/config.txt
1102 • ${APPDATA}/yt-dlp.conf
1104 • ${APPDATA}/yt-dlp/config (recommended on Windows)
1106 • ${APPDATA}/yt-dlp/config.txt
1108 • ~/yt-dlp.conf
1110 • ~/yt-dlp.conf.txt
1112 • ~/.yt-dlp/config
1114 • ~/.yt-dlp/config.txt See also: Notes about environment variables
1116 5. System Configuration:
1118 • /etc/yt-dlp.conf
1120 • /etc/yt-dlp/config
1122 • /etc/yt-dlp/config.txt
1124 E.g. with the following configuration file yt-dlp will always extract
1126 the audio, not copy the mtime, use a proxy and save all videos under
1127 YouTube directory in your home directory:
1128 # Lines starting with # are comments
1130 # Always extract audio
1132 -x
1133 # Do not copy the mtime
1135 --no-mtime
1136 # Use this proxy
1138 --proxy 127.0.0.1:3128
1139 # Save all videos under YouTube directory in your home directory
1141 -o ~/YouTube/%(title)s.%(ext)s
1142 Note: Options in configuration file are just the same options aka
1144 switches used in regular command line calls; thus there must be no
1145 whitespace after - or --, e.g. -o or --proxy but not - o or -- proxy.
1146 They must also be quoted when necessary as-if it were a UNIX shell.
1147 You can use --ignore-config if you want to disable all configuration
1149 files for a particular yt-dlp run. If --ignore-config is found inside
1150 any configuration file, no further configuration will be loaded. For
1151 example, having the option in the portable configuration file prevents
1152 loading of home, user, and system configurations. Additionally, (for
1153 backward compatibility) if --ignore-config is found inside the system
1154 configuration file, the user configuration is not loaded.
1155 Configuration file encoding
1157 The configuration files are decoded according to the UTF BOM if
1158 present, and in the encoding from system locale otherwise.
1159 If you want your file to be decoded differently, add # coding: ENCODING
1161 to the beginning of the file (e.g. # coding: shift-jis). There must
1162 be no characters before that, even spaces or BOM.
1163 Authentication with .netrc file
1165 You may also want to configure automatic credentials storage for ex‐
1166 tractors that support authentication (by providing login and password
1167 with --username and --password) in order not to pass credentials as
1168 command line arguments on every yt-dlp execution and prevent tracking
1169 plain text passwords in the shell command history. You can achieve
1170 this using a .netrc file (https://stackoverflow.com/tags/.netrc/info)
1171 on a per-extractor basis. For that you will need to create a .netrc
1172 file in --netrc-location and restrict permissions to read/write by only
1173 you:
1174 touch ${HOME}/.netrc
1176 chmod a-rwx,u+rw ${HOME}/.netrc
1177 After that you can add credentials for an extractor in the following
1179 format, where extractor is the name of the extractor in lowercase:
1180 machine <extractor> login <username> password <password>
1182 E.g.
1184 machine youtube login myaccount@gmail.com password my_youtube_password
1186 machine twitch login my_twitch_account_name password my_twitch_password
1187 To activate authentication with the .netrc file you should pass --netrc
1189 to yt-dlp or place it in the configuration file.
1190 The default location of the .netrc file is ~ (see below).
1192 Notes about environment variables
1194 • Environment variables are normally specified as ${VARIABLE}/$VARIABLE
1195 on UNIX and %VARIABLE% on Windows; but is always shown as ${VARIABLE}
1196 in this documentation
1197 • yt-dlp also allow using UNIX-style variables on Windows for path-like
1199 options; e.g. --output, --config-location
1200 • If unset, ${XDG_CONFIG_HOME} defaults to ~/.config and
1202 ${XDG_CACHE_HOME} to ~/.cache
1203 • On Windows, ~ points to ${HOME} if present; or, ${USERPROFILE} or
1205 ${HOMEDRIVE}${HOMEPATH} otherwise
1206 • On Windows, ${USERPROFILE} generally points to C:\Users\<user name>
1208 and ${APPDATA} to ${USERPROFILE}\AppData\Roaming
1209
1211 The -o option is used to indicate a template for the output file names
1212 while -P option is used to specify the path each type of file should be
1213 saved to.
1214 The simplest usage of -o is not to set any template arguments when
1216 downloading a single file, like in yt-dlp -o funny_video.flv
1217 "https://some/video" (hard-coding file extension like this is not rec‐
1218 ommended and could break some post-processing).
1219 It may however also contain special sequences that will be replaced
1221 when downloading each video. The special sequences may be formatted
1222 according to Python string formatting operations
1223 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1224 formatting), e.g. %(NAME)s or %(NAME)05d. To clarify, that is a per‐
1225 cent symbol followed by a name in parentheses, followed by formatting
1226 operations.
1227 The field names themselves (the part inside the parenthesis) can also
1229 have some special formatting:
1230 1. Object traversal: The dictionaries and lists available in metadata
1232 can be traversed by using a dot . separator; e.g. %(tags.0)s,
1233 %(subtitles.en.-1.ext)s. You can do Python slicing with colon :;
1234 E.g. %(id.3:7:-1)s, %(formats.:.format_id)s. Curly braces {} can
1235 be used to build dictionaries with only specific keys; e.g. %(for‐
1236 mats.:.{format_id,height})#j. An empty field name %()s refers to
1237 the entire infodict; e.g. %(.{id,title})s. Note that all the
1238 fields that become available using this method are not listed below.
1239 Use -j to see such fields
1240 2. Addition: Addition and subtraction of numeric fields can be done us‐
1242 ing + and - respectively. E.g. %(playlist_index+10)03d, %(n_en‐
1243 tries+1-playlist_index)d
1244 3. Date/time Formatting: Date/time fields can be formatted according to
1246 strftime formatting (https://docs.python.org/3/library/date‐
1247 time.html#strftime-and-strptime-format-codes) by specifying it sepa‐
1248 rated from the field name using a >. E.g. %(duration>%H-%M-%S)s,
1249 %(upload_date>%Y-%m-%d)s, %(epoch-3600>%H-%M-%S)s
1250 4. Alternatives: Alternate fields can be specified separated with a ,.
1252 E.g. %(release_date>%Y,upload_date>%Y|Unknown)s
1253 5. Replacement: A replacement value can be specified using a & separa‐
1255 tor. If the field is not empty, this replacement value will be used
1256 instead of the actual field content. This is done after alternate
1257 fields are considered; thus the replacement is used if any of the
1258 alternative fields is not empty.
1259 6. Default: A literal default value can be specified for when the field
1261 is empty using a | separator. This overrides --output-na-placehold‐
1262 er. E.g. %(uploader|Unknown)s
1263 7. More Conversions: In addition to the normal format types diouxXeEf‐
1265 FgGcrs, yt-dlp additionally supports converting to B = Bytes, j =
1266 json (flag # for pretty-printing, + for Unicode), h = HTML escaping,
1267 l = a comma separated list (flag # for \n newline-separated), q = a
1268 string quoted for the terminal (flag # to split a list into differ‐
1269 ent arguments), D = add Decimal suffixes (e.g. 10M) (flag # to use
1270 1024 as factor), and S = Sanitize as filename (flag # for restrict‐
1271 ed)
1272 8. Unicode normalization: The format type U can be used for NFC Unicode
1274 normalization (https://docs.python.org/3/library/unicodeda‐
1275 ta.html#unicodedata.normalize). The alternate form flag (#) changes
1276 the normalization to NFD and the conversion flag + can be used for
1277 NFKC/NFKD compatibility equivalence normalization. E.g. %(ti‐
1278 tle)+.100U is NFKC
1279 To summarize, the general syntax for a field is:
1281 %(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type
1283 Additionally, you can set different output templates for the various
1285 metadata files separately from the general output template by specify‐
1286 ing the type of file followed by the template separated by a colon :.
1287 The different file types supported are subtitle, thumbnail, descrip‐
1288 tion, annotation (deprecated), infojson, link, pl_thumbnail, pl_de‐
1289 scription, pl_infojson, chapter, pl_video. E.g. -o "%(ti‐
1290 tle)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s" will put the
1291 thumbnails in a folder with the same name as the video. If any of the
1292 templates is empty, that type of file will not be written. E.g.
1293 --write-thumbnail -o "thumbnail:" will write thumbnails only for
1294 playlists and not for video.
1295 Note: Due to post-processing (i.e. merging etc.), the actual output
1297 filename might differ. Use --print after_move:filepath to get the name
1298 after all post-processing is complete.
1299 The available fields are:
1301 • id (string): Video identifier
1303 • title (string): Video title
1305 • fulltitle (string): Video title ignoring live timestamp and generic
1307 title
1308 • ext (string): Video filename extension
1310 • alt_title (string): A secondary title of the video
1312 • description (string): The description of the video
1314 • display_id (string): An alternative identifier for the video
1316 • uploader (string): Full name of the video uploader
1318 • license (string): License name the video is licensed under
1320 • creator (string): The creator of the video
1322 • timestamp (numeric): UNIX timestamp of the moment the video became
1324 available
1325 • upload_date (string): Video upload date in UTC (YYYYMMDD)
1327 • release_timestamp (numeric): UNIX timestamp of the moment the video
1329 was released
1330 • release_date (string): The date (YYYYMMDD) when the video was re‐
1332 leased in UTC
1333 • modified_timestamp (numeric): UNIX timestamp of the moment the video
1335 was last modified
1336 • modified_date (string): The date (YYYYMMDD) when the video was last
1338 modified in UTC
1339 • uploader_id (string): Nickname or id of the video uploader
1341 • channel (string): Full name of the channel the video is uploaded on
1343 • channel_id (string): Id of the channel
1345 • channel_follower_count (numeric): Number of followers of the channel
1347 • location (string): Physical location where the video was filmed
1349 • duration (numeric): Length of the video in seconds
1351 • duration_string (string): Length of the video (HH:mm:ss)
1353 • view_count (numeric): How many users have watched the video on the
1355 platform
1356 • concurrent_view_count (numeric): How many users are currently watch‐
1358 ing the video on the platform.
1359 • like_count (numeric): Number of positive ratings of the video
1361 • dislike_count (numeric): Number of negative ratings of the video
1363 • repost_count (numeric): Number of reposts of the video
1365 • average_rating (numeric): Average rating give by users, the scale
1367 used depends on the webpage
1368 • comment_count (numeric): Number of comments on the video (For some
1370 extractors, comments are only downloaded at the end, and so this
1371 field cannot be used)
1372 • age_limit (numeric): Age restriction for the video (years)
1374 • live_status (string): One of "not_live", "is_live", "is_upcoming",
1376 "was_live", "post_live" (was live, but VOD is not yet processed)
1377 • is_live (boolean): Whether this video is a live stream or a fixed-
1379 length video
1380 • was_live (boolean): Whether this video was originally a live stream
1382 • playable_in_embed (string): Whether this video is allowed to play in
1384 embedded players on other sites
1385 • availability (string): Whether the video is "private", "premium_on‐
1387 ly", "subscriber_only", "needs_auth", "unlisted" or "public"
1388 • start_time (numeric): Time in seconds where the reproduction should
1390 start, as specified in the URL
1391 • end_time (numeric): Time in seconds where the reproduction should
1393 end, as specified in the URL
1394 • extractor (string): Name of the extractor
1396 • extractor_key (string): Key name of the extractor
1398 • epoch (numeric): Unix epoch of when the information extraction was
1400 completed
1401 • autonumber (numeric): Number that will be increased with each down‐
1403 load, starting at --autonumber-start
1404 • video_autonumber (numeric): Number that will be increased with each
1406 video
1407 • n_entries (numeric): Total number of extracted items in the playlist
1409 • playlist_id (string): Identifier of the playlist that contains the
1411 video
1412 • playlist_title (string): Name of the playlist that contains the video
1414 • playlist (string): playlist_id or playlist_title
1416 • playlist_count (numeric): Total number of items in the playlist. May
1418 not be known if entire playlist is not extracted
1419 • playlist_index (numeric): Index of the video in the playlist padded
1421 with leading zeros according the final index
1422 • playlist_autonumber (numeric): Position of the video in the playlist
1424 download queue padded with leading zeros according to the total
1425 length of the playlist
1426 • playlist_uploader (string): Full name of the playlist uploader
1428 • playlist_uploader_id (string): Nickname or id of the playlist upload‐
1430 er
1431 • webpage_url (string): A URL to the video webpage which if given to
1433 yt-dlp should allow to get the same result again
1434 • webpage_url_basename (string): The basename of the webpage URL
1436 • webpage_url_domain (string): The domain of the webpage URL
1438 • original_url (string): The URL given by the user (or same as web‐
1440 page_url for playlist entries)
1441 All the fields in Filtering Formats can also be used
1443 Available for the video that belongs to some logical chapter or sec‐
1445 tion:
1446 • chapter (string): Name or title of the chapter the video belongs to
1448 • chapter_number (numeric): Number of the chapter the video belongs to
1450 • chapter_id (string): Id of the chapter the video belongs to
1452 Available for the video that is an episode of some series or programme:
1454 • series (string): Title of the series or programme the video episode
1456 belongs to
1457 • season (string): Title of the season the video episode belongs to
1459 • season_number (numeric): Number of the season the video episode be‐
1461 longs to
1462 • season_id (string): Id of the season the video episode belongs to
1464 • episode (string): Title of the video episode
1466 • episode_number (numeric): Number of the video episode within a season
1468 • episode_id (string): Id of the video episode
1470 Available for the media that is a track or a part of a music album:
1472 • track (string): Title of the track
1474 • track_number (numeric): Number of the track within an album or a disc
1476 • track_id (string): Id of the track
1478 • artist (string): Artist(s) of the track
1480 • genre (string): Genre(s) of the track
1482 • album (string): Title of the album the track belongs to
1484 • album_type (string): Type of the album
1486 • album_artist (string): List of all artists appeared on the album
1488 • disc_number (numeric): Number of the disc or other physical medium
1490 the track belongs to
1491 • release_year (numeric): Year (YYYY) when the album was released
1493 Available only when using --download-sections and for chapter: prefix
1495 when using --split-chapters for videos with internal chapters:
1496 • section_title (string): Title of the chapter
1498 • section_number (numeric): Number of the chapter within the file
1500 • section_start (numeric): Start time of the chapter in seconds
1502 • section_end (numeric): End time of the chapter in seconds
1504 Available only when used in --print:
1506 • urls (string): The URLs of all requested formats, one in each line
1508 • filename (string): Name of the video file. Note that the actual
1510 filename may differ
1511 • formats_table (table): The video format table as printed by --list-
1513 formats
1514 • thumbnails_table (table): The thumbnail format table as printed by
1516 --list-thumbnails
1517 • subtitles_table (table): The subtitle format table as printed by
1519 --list-subs
1520 • automatic_captions_table (table): The automatic subtitle format table
1522 as printed by --list-subs
1523 Available only in --sponsorblock-chapter-title:
1525 • start_time (numeric): Start time of the chapter in seconds
1527 • end_time (numeric): End time of the chapter in seconds
1529 • categories (list): The SponsorBlock categories (https://wiki.spon‐
1531 sor.ajay.app/w/Types#Category) the chapter belongs to
1532 • category (string): The smallest SponsorBlock category the chapter be‐
1534 longs to
1535 • category_names (list): Friendly names of the categories
1537 • name (string): Friendly name of the smallest category
1539 • type (string): The SponsorBlock action type (https://wiki.spon‐
1541 sor.ajay.app/w/Types#Action_Type) of the chapter
1542 Each aforementioned sequence when referenced in an output template will
1544 be replaced by the actual value corresponding to the sequence name.
1545 E.g. for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title yt-
1546 dlp test video and id BaW_jenozKc, this will result in a yt-dlp test
1547 video-BaW_jenozKc.mp4 file created in the current directory.
1548 Note: Some of the sequences are not guaranteed to be present since they
1550 depend on the metadata obtained by a particular extractor. Such se‐
1551 quences will be replaced with placeholder value provided with --output-
1552 na-placeholder (NA by default).
1553 Tip: Look at the -j output to identify which fields are available for
1555 the particular URL
1556 For numeric sequences you can use numeric related formatting
1558 (https://docs.python.org/3/library/stdtypes.html#printf-style-string-
1559 formatting); e.g. %(view_count)05d will result in a string with view
1560 count padded with zeros up to 5 characters, like in 00042.
1561 Output templates can also contain arbitrary hierarchical path, e.g. -o
1563 "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" which will result
1564 in downloading each video in a directory corresponding to this path
1565 template. Any missing directory will be automatically created for you.
1566 To use percent literals in an output template use %%. To output to
1568 stdout use -o -.
1569 The current default template is %(title)s [%(id)s].%(ext)s.
1571 In some cases, you don't want special characters such as 中, spaces, or
1573 &, such as when transferring the downloaded filename to a Windows sys‐
1574 tem or the filename through an 8bit-unsafe channel. In these cases,
1575 add the --restrict-filenames flag to get a shorter title.
1576 Output template examples
1578 $ yt-dlp --print filename -o "test video.%(ext)s" BaW_jenozKc
1579 test video.webm # Literal name with correct extension
1580 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc
1582 youtube-dl test video ''_ä↭𝕐.webm # All kinds of weird characters
1583 $ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
1585 youtube-dl_test_video_.webm # Restricted file name
1586 # Download YouTube playlist videos in separate directory indexed by video order in a playlist
1588 $ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1589 # Download YouTube playlist videos in separate directories according to their uploaded year
1591 $ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1592 # Prefix playlist index with " - " separator, but only if it is available
1594 $ yt-dlp -o '%(playlist_index|)s%(playlist_index& - |)s%(title)s.%(ext)s' BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1595 # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
1597 $ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"
1598 # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
1600 $ 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"
1601 # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
1603 $ 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"
1604 # Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
1606 # and put all temporary files in "C:\MyVideos\tmp"
1607 $ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs
1608 # Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
1610 $ 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
1611 # Stream the video being downloaded to stdout
1613 $ yt-dlp -o - BaW_jenozKc
1614
1616 By default, yt-dlp tries to download the best available quality if you
1617 don't pass any options. This is generally equivalent to using -f
1618 bestvideo*+bestaudio/best. However, if multiple audiostreams is en‐
1619 abled (--audio-multistreams), the default format changes to -f
1620 bestvideo+bestaudio/best. Similarly, if ffmpeg is unavailable, or if
1621 you use yt-dlp to stream to stdout (-o -), the default becomes -f
1622 best/bestvideo+bestaudio.
1623 Deprecation warning: Latest versions of yt-dlp can stream multiple for‐
1625 mats to the stdout simultaneously using ffmpeg. So, in future ver‐
1626 sions, the default for this will be set to -f bv*+ba/b similar to nor‐
1627 mal downloads. If you want to preserve the -f b/bv+ba setting, it is
1628 recommended to explicitly specify it in the configuration options.
1629 The general syntax for format selection is -f FORMAT (or --format FOR‐
1631 MAT) where FORMAT is a selector expression, i.e. an expression that
1632 describes format or formats you would like to download.
1633 The simplest case is requesting a specific format; e.g. with -f 22 you
1635 can download the format with format code equal to 22. You can get the
1636 list of available format codes for particular video using --list-for‐
1637 mats or -F. Note that these format codes are extractor specific.
1638 You can also use a file extension (currently 3gp, aac, flv, m4a, mp3,
1640 mp4, ogg, wav, webm are supported) to download the best quality format
1641 of a particular file extension served as a single file, e.g. -f webm
1642 will download the best quality format with the webm extension served as
1643 a single file.
1644 You can use -f - to interactively provide the format selector for each
1646 video
1647 You can also use special names to select particular edge case formats:
1649 • all: Select all formats separately
1651 • mergeall: Select and merge all formats (Must be used with --audio-
1653 multistreams, --video-multistreams or both)
1654 • b*, best*: Select the best quality format that contains either a
1656 video or an audio or both (ie; vcodec!=none or acodec!=none)
1657 • b, best: Select the best quality format that contains both video and
1659 audio. Equivalent to best*[vcodec!=none][acodec!=none]
1660 • bv, bestvideo: Select the best quality video-only format. Equivalent
1662 to best*[acodec=none]
1663 • bv*, bestvideo*: Select the best quality format that contains video.
1665 It may also contain audio. Equivalent to best*[vcodec!=none]
1666 • ba, bestaudio: Select the best quality audio-only format. Equivalent
1668 to best*[vcodec=none]
1669 • ba*, bestaudio*: Select the best quality format that contains audio.
1671 It may also contain video. Equivalent to best*[acodec!=none] (Do not
1672 use! (https://github.com/yt-dlp/yt-dlp/issues/979#issuecom‐
1673 ment-919629354))
1674 • w*, worst*: Select the worst quality format that contains either a
1676 video or an audio
1677 • w, worst: Select the worst quality format that contains both video
1679 and audio. Equivalent to worst*[vcodec!=none][acodec!=none]
1680 • wv, worstvideo: Select the worst quality video-only format. Equiva‐
1682 lent to worst*[acodec=none]
1683 • wv*, worstvideo*: Select the worst quality format that contains
1685 video. It may also contain audio. Equivalent to
1686 worst*[vcodec!=none]
1687 • wa, worstaudio: Select the worst quality audio-only format. Equiva‐
1689 lent to worst*[vcodec=none]
1690 • wa*, worstaudio*: Select the worst quality format that contains au‐
1692 dio. It may also contain video. Equivalent to worst*[acodec!=none]
1693 For example, to download the worst quality video-only format you can
1695 use -f worstvideo. It is however recommended not to use worst and re‐
1696 lated options. When your format selector is worst, the format which is
1697 worst in all respects is selected. Most of the time, what you actually
1698 want is the video with the smallest filesize instead. So it is gener‐
1699 ally better to use -S +size or more rigorously, -S +size,+br,+res,+fps
1700 instead of -f worst. See Sorting Formats for more details.
1701 You can select the n'th best format of a type by using best<type>.<n>.
1703 For example, best.2 will select the 2nd best combined format. Similar‐
1704 ly, bv*.3 will select the 3rd best format that contains a video stream.
1705 If you want to download multiple videos, and they don't have the same
1707 formats available, you can specify the order of preference using slash‐
1708 es. Note that formats on the left hand side are preferred; e.g. -f
1709 22/17/18 will download format 22 if it's available, otherwise it will
1710 download format 17 if it's available, otherwise it will download format
1711 18 if it's available, otherwise it will complain that no suitable for‐
1712 mats are available for download.
1713 If you want to download several formats of the same video use a comma
1715 as a separator, e.g. -f 22,17,18 will download all these three for‐
1716 mats, of course if they are available. Or a more sophisticated example
1717 combined with the precedence feature: -f
1718 136/137/mp4/bestvideo,140/m4a/bestaudio.
1719 You can merge the video and audio of multiple formats into a single
1721 file using -f <format1>+<format2>+... (requires ffmpeg installed); e.g.
1722 -f bestvideo+bestaudio will download the best video-only format, the
1723 best audio-only format and mux them together with ffmpeg.
1724 Deprecation warning: Since the below described behavior is complex and
1726 counter-intuitive, this will be removed and multistreams will be en‐
1727 abled by default in the future. A new operator will be instead added
1728 to limit formats to single audio/video
1729 Unless --video-multistreams is used, all formats with a video stream
1731 except the first one are ignored. Similarly, unless --audio-multi‐
1732 streams is used, all formats with an audio stream except the first one
1733 are ignored. E.g. -f bestvideo+best+bestaudio --video-multistreams
1734 --audio-multistreams will download and merge all 3 given formats. The
1735 resulting file will have 2 video streams and 2 audio streams. But -f
1736 bestvideo+best+bestaudio --no-video-multistreams will download and
1737 merge only bestvideo and bestaudio. best is ignored since another for‐
1738 mat containing a video stream (bestvideo) has already been selected.
1739 The order of the formats is therefore important. -f best+bestaudio
1740 --no-audio-multistreams will download only best while -f bestaudio+best
1741 --no-audio-multistreams will ignore best and download only bestaudio.
1742 Filtering Formats
1744 You can also filter the video formats by putting a condition in brack‐
1745 ets, as in -f "best[height=720]" (or -f "[filesize>10M]").
1746 The following numeric meta fields can be used with comparisons <, <=,
1748 >, >=, = (equals), != (not equals):
1749 • filesize: The number of bytes, if known in advance
1751 • filesize_approx: An estimate for the number of bytes
1753 • width: Width of the video, if known
1755 • height: Height of the video, if known
1757 • aspect_ratio: Aspect ratio of the video, if known
1759 • tbr: Average bitrate of audio and video in KBit/s
1761 • abr: Average audio bitrate in KBit/s
1763 • vbr: Average video bitrate in KBit/s
1765 • asr: Audio sampling rate in Hertz
1767 • fps: Frame rate
1769 • audio_channels: The number of audio channels
1771 • stretched_ratio: width:height of the video's pixels, if not square
1773 Also filtering work for comparisons = (equals), ^= (starts with), $=
1775 (ends with), *= (contains), ~= (matches regex) and following string
1776 meta fields:
1777 • url: Video URL
1779 • ext: File extension
1781 • acodec: Name of the audio codec in use
1783 • vcodec: Name of the video codec in use
1785 • container: Name of the container format
1787 • protocol: The protocol that will be used for the actual download,
1789 lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m, ism,
1790 http_dash_segments, m3u8, or m3u8_native)
1791 • language: Language code
1793 • dynamic_range: The dynamic range of the video
1795 • format_id: A short description of the format
1797 • format: A human-readable description of the format
1799 • format_note: Additional info about the format
1801 • resolution: Textual description of width and height
1803 Any string comparison may be prefixed with negation ! in order to pro‐
1805 duce an opposite comparison, e.g. !*= (does not contain). The compar‐
1806 and of a string comparison needs to be quoted with either double or
1807 single quotes if it contains spaces or special characters other than
1808 ._-.
1809 Note: None of the aforementioned meta fields are guaranteed to be
1811 present since this solely depends on the metadata obtained by particu‐
1812 lar extractor, i.e. the metadata offered by the website. Any other
1813 field made available by the extractor can also be used for filtering.
1814 Formats for which the value is not known are excluded unless you put a
1816 question mark (?) after the operator. You can combine format filters,
1817 so -f "[height<=?720][tbr>500]" selects up to 720p videos (or videos
1818 where the height is not known) with a bitrate of at least 500 KBit/s.
1819 You can also use the filters with all to download all formats that sat‐
1820 isfy the filter, e.g. -f "all[vcodec=none]" selects all audio-only
1821 formats.
1822 Format selectors can also be grouped using parentheses; e.g. -f
1824 "(mp4,webm)[height<480]" will download the best pre-merged mp4 and webm
1825 formats with a height lower than 480.
1826 Sorting Formats
1828 You can change the criteria for being considered the best by using -S
1829 (--format-sort). The general format for this is --format-sort
1830 field1,field2....
1831 The available fields are:
1833 • hasvid: Gives priority to formats that have a video stream
1835 • hasaud: Gives priority to formats that have an audio stream
1837 • ie_pref: The format preference
1839 • lang: The language preference
1841 • quality: The quality of the format
1843 • source: The preference of the source
1845 • proto: Protocol used for download (https/ftps > http/ftp > m3u8_na‐
1847 tive/m3u8 > http_dash_segments> websocket_frag > mms/rtsp > f4f/f4m)
1848 • vcodec: Video Codec (av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 >
1850 theora > other)
1851 • acodec: Audio Codec (flac/alac > wav/aiff > opus > vorbis > aac >
1853 mp4a > mp3 ac4 > > eac3 > ac3 > dts > other)
1854 • codec: Equivalent to vcodec,acodec
1856 • vext: Video Extension (mp4 > mov > webm > flv > other). If --prefer-
1858 free-formats is used, webm is preferred.
1859 • aext: Audio Extension (m4a > aac > mp3 > ogg > opus > webm > other).
1861 If --prefer-free-formats is used, the order changes to ogg > opus >
1862 webm > mp3 > m4a > aac
1863 • ext: Equivalent to vext,aext
1865 • filesize: Exact filesize, if known in advance
1867 • fs_approx: Approximate filesize calculated from the manifests
1869 • size: Exact filesize if available, otherwise approximate filesize
1871 • height: Height of video
1873 • width: Width of video
1875 • res: Video resolution, calculated as the smallest dimension.
1877 • fps: Framerate of video
1879 • hdr: The dynamic range of the video (DV > HDR12 > HDR10+ > HDR10 >
1881 HLG > SDR)
1882 • channels: The number of audio channels
1884 • tbr: Total average bitrate in KBit/s
1886 • vbr: Average video bitrate in KBit/s
1888 • abr: Average audio bitrate in KBit/s
1890 • br: Equivalent to using tbr,vbr,abr
1892 • asr: Audio sample rate in Hz
1894 Deprecation warning: Many of these fields have (currently undocumented)
1896 aliases, that may be removed in a future version. It is recommended to
1897 use only the documented field names.
1898 All fields, unless specified otherwise, are sorted in descending order.
1900 To reverse this, prefix the field with a +. E.g. +res prefers format
1901 with the smallest resolution. Additionally, you can suffix a preferred
1902 value for the fields, separated by a :. E.g. res:720 prefers larger
1903 videos, but no larger than 720p and the smallest video if there are no
1904 videos less than 720p. For codec and ext, you can provide two pre‐
1905 ferred values, the first for video and the second for audio. E.g.
1906 +codec:avc:m4a (equivalent to +vcodec:avc,+acodec:m4a) sets the video
1907 codec preference to h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 >
1908 theora and audio codec preference to mp4a > aac > vorbis > opus > mp3 >
1909 ac3 > dts. You can also make the sorting prefer the nearest values to
1910 the provided by using ~ as the delimiter. E.g. filesize~1G prefers
1911 the format with filesize closest to 1 GiB.
1912 The fields hasvid and ie_pref are always given highest priority in
1914 sorting, irrespective of the user-defined order. This behaviour can be
1915 changed by using --format-sort-force. Apart from these, the default
1916 order used is: lang,quality,res,fps,hdr:12,vcodec:vp9.2,chan‐
1917 nels,acodec,size,br,asr,proto,ext,hasaud,source,id. The extractors may
1918 override this default order, but they cannot override the user-provided
1919 order.
1920 Note that the default has vcodec:vp9.2; i.e. av1 is not preferred.
1922 Similarly, the default for hdr is hdr:12; i.e. dolby vision is not
1923 preferred. These choices are made since DV and AV1 formats are not yet
1924 fully compatible with most devices. This may be changed in the future
1925 as more devices become capable of smoothly playing back these formats.
1926 If your format selector is worst, the last item is selected after sort‐
1928 ing. This means it will select the format that is worst in all re‐
1929 spects. Most of the time, what you actually want is the video with the
1930 smallest filesize instead. So it is generally better to use -f best -S
1931 +size,+br,+res,+fps.
1932 Tip: You can use the -v -F to see how the formats have been sorted
1934 (worst to best).
1935 Format Selection examples
1937 # Download and merge the best video-only format and the best audio-only format,
1938 # or download the best combined format if video-only format is not available
1939 $ yt-dlp -f "bv+ba/b"
1940 # Download best format that contains video,
1942 # and if it doesn't already have an audio stream, merge it with best audio-only format
1943 $ yt-dlp -f "bv*+ba/b"
1944 # Same as above
1946 $ yt-dlp
1947 # Download the best video-only format and the best audio-only format without merging them
1949 # For this case, an output template should be used since
1950 # by default, bestvideo and bestaudio will have the same file name.
1951 $ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"
1952 # Download and merge the best format that has a video stream,
1954 # and all audio-only formats into one file
1955 $ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams
1956 # Download and merge the best format that has a video stream,
1958 # and the best 2 audio-only formats into one file
1959 $ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams
1960 # The following examples show the old method (without -S) of format selection
1963 # and how to use -S to achieve a similar but (generally) better result
1964 # Download the worst video available (old method)
1966 $ yt-dlp -f "wv*+wa/w"
1967 # Download the best video available but with the smallest resolution
1969 $ yt-dlp -S "+res"
1970 # Download the smallest video available
1972 $ yt-dlp -S "+size,+br"
1973 # Download the best mp4 video available, or the best video if no mp4 available
1977 $ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"
1978 # Download the best video with the best extension
1980 # (For video, mp4 > mov > webm > flv. For audio, m4a > aac > mp3 ...)
1981 $ yt-dlp -S "ext"
1982 # Download the best video available but no better than 480p,
1986 # or the worst video if there is no video under 480p
1987 $ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"
1988 # Download the best video available with the largest height but no better than 480p,
1990 # or the best video with the smallest resolution if there is no video under 480p
1991 $ yt-dlp -S "height:480"
1992 # Download the best video available with the largest resolution but no better than 480p,
1994 # or the best video with the smallest resolution if there is no video under 480p
1995 # Resolution is determined by using the smallest dimension.
1996 # So this works correctly for vertical videos as well
1997 $ yt-dlp -S "res:480"
1998 # Download the best video (that also has audio) but no bigger than 50 MB,
2002 # or the worst video (that also has audio) if there is no video under 50 MB
2003 $ yt-dlp -f "b[filesize<50M] / w"
2004 # Download largest video (that also has audio) but no bigger than 50 MB,
2006 # or the smallest video (that also has audio) if there is no video under 50 MB
2007 $ yt-dlp -f "b" -S "filesize:50M"
2008 # Download best video (that also has audio) that is closest in size to 50 MB
2010 $ yt-dlp -f "b" -S "filesize~50M"
2011 # Download best video available via direct link over HTTP/HTTPS protocol,
2015 # or the best video available via any protocol if there is no such video
2016 $ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"
2017 # Download best video available via the best protocol
2019 # (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
2020 $ yt-dlp -S "proto"
2021 # Download the best video with either h264 or h265 codec,
2025 # or the best video if there is no such video
2026 $ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"
2027 # Download the best video with best codec no better than h264,
2029 # or the best video with worst codec if there is no such video
2030 $ yt-dlp -S "codec:h264"
2031 # Download the best video with worst codec no worse than h264,
2033 # or the best video with best codec if there is no such video
2034 $ yt-dlp -S "+codec:h264"
2035 # More complex examples
2039 # Download the best video no better than 720p preferring framerate greater than 30,
2041 # or the worst video (still preferring framerate greater than 30) if there is no such video
2042 $ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"
2043 # Download the video with the largest resolution no better than 720p,
2045 # or the video with the smallest resolution available if there is no such video,
2046 # preferring larger framerate for formats with the same resolution
2047 $ yt-dlp -S "res:720,fps"
2048 # Download the video with smallest resolution no worse than 480p,
2052 # or the video with the largest resolution available if there is no such video,
2053 # preferring better codec and then larger total bitrate for the same resolution
2054 $ yt-dlp -S "+res:480,codec,br"
2055
2057 The metadata obtained by the extractors can be modified by using
2058 --parse-metadata and --replace-in-metadata
2059 --replace-in-metadata FIELDS REGEX REPLACE is used to replace text in
2061 any metadata field using python regular expression
2062 (https://docs.python.org/3/library/re.html#regular-expression-syntax).
2063 Backreferences (https://docs.python.org/3/library/re.html?high‐
2064 light=backreferences#re.sub) can be used in the replace string for ad‐
2065 vanced use.
2066 The general syntax of --parse-metadata FROM:TO is to give the name of a
2068 field or an output template to extract data from, and the format to in‐
2069 terpret it as, separated by a colon :. Either a python regular expres‐
2070 sion (https://docs.python.org/3/library/re.html#regular-expression-syn‐
2071 tax) with named capture groups, a single field name, or a similar syn‐
2072 tax to the output template (only %(field)s formatting is supported) can
2073 be used for TO. The option can be used multiple times to parse and
2074 modify various fields.
2075 Note that these options preserve their relative order, allowing re‐
2077 placements to be made in parsed fields and viceversa. Also, any field
2078 thus created can be used in the output template and will also affect
2079 the media file's metadata added when using --embed-metadata.
2080 This option also has a few special uses:
2082 • You can download an additional URL based on the metadata of the cur‐
2084 rently downloaded video. To do this, set the field additional_urls
2085 to the URL that you want to download. E.g. --parse-metadata "de‐
2086 scription:(?P<additional_urls>https?://www\.vimeo\.com/\d+) will
2087 download the first vimeo video found in the description
2088 • You can use this to change the metadata that is embedded in the media
2090 file. To do this, set the value of the corresponding field with a
2091 meta_ prefix. For example, any value you set to meta_description
2092 field will be added to the description field in the file - you can
2093 use this to set a different "description" and "synopsis". To modify
2094 the metadata of individual streams, use the meta<n>_ prefix (e.g.
2095 meta1_language). Any value set to the meta_ field will overwrite all
2096 default values.
2097 Note: Metadata modification happens before format selection, post-ex‐
2099 traction and other post-processing operations. Some fields may be
2100 added or changed during these steps, overriding your changes.
2101 For reference, these are the fields yt-dlp adds by default to the file
2103 metadata:
2104 Metadata fields From
2106 ─────────────────────────────────────────────────────
2107 title track or title
2108 date upload_date
2109 description, synopsis description
2110 purl, comment webpage_url
2111 track track_number
2112 artist artist, creator, uploader
2113 or uploader_id
2114 genre genre
2115 album album
2116 album_artist album_artist
2117 disc disc_number
2118 show series
2119 season_number season_number
2120 episode_id episode or episode_id
2121 episode_sort episode_number
2122 language of each stream the format's language
2123 Note: The file format may not support some of these fields
2125 Modifying metadata examples
2127 # Interpret the title as "Artist - Title"
2128 $ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"
2129 # Regex example
2131 $ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"
2132 # Set title as "Series name S01E05"
2134 $ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"
2135 # Prioritize uploader as the "artist" field in video metadata
2137 $ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --embed-metadata
2138 # Set "comment" field in video metadata using description instead of webpage_url,
2140 # handling multiple lines correctly
2141 $ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --embed-metadata
2142 # Do not set any "synopsis" in the video metadata
2144 $ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"
2145 # Remove "formats" field from the infojson by setting it to an empty string
2147 $ yt-dlp --parse-metadata ":(?P<formats>)" -j
2148 # Replace all spaces and "_" in title and uploader with a `-`
2150 $ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"
2151
2153 Some extractors accept additional arguments which can be passed using
2154 --extractor-args KEY:ARGS. ARGS is a ; (semicolon) separated string of
2155 ARG=VAL1,VAL2. E.g. --extractor-args "youtube:player-client=an‐
2156 droid_embedded,web;include_live_dash" --extractor-args "funimation:ver‐
2157 sion=uncut"
2158 The following extractors use this feature:
2160 youtube
2162 • lang: Prefer translated metadata (title, description etc) of this
2163 language code (case-sensitive). By default, the video primary lan‐
2164 guage metadata is preferred, with a fallback to en translated. See
2165 youtube.py (https://github.com/yt-dlp/yt-
2166 dlp/blob/c26f9b991a0681fd3ea548d535919cec1fbbd430/yt_dlp/extrac‐
2167 tor/youtube.py#L381-L390) for list of supported content language
2168 codes
2169 • skip: One or more of hls, dash or translated_subs to skip extraction
2171 of the m3u8 manifests, dash manifests and auto-translated subtitles
2172 (https://github.com/yt-dlp/yt-dlp/issues/4090#issuecom‐
2173 ment-1158102032) respectively
2174 • player_client: Clients to extract video data from. The main clients
2176 are web, android and ios with variants _music, _embedded, _embed‐
2177 screen, _creator (e.g. web_embedded); and mweb and tv_embedded (age‐
2178 gate bypass) with no variants. By default, android,web is used, but
2179 tv_embedded and creator variants are added as required for age-gated
2180 videos. Similarly, the music variants are added for mu‐
2181 sic.youtube.com urls. You can use all to use all the clients, and
2182 default for the default clients.
2183 • player_skip: Skip some network requests that are generally needed for
2185 robust extraction. One or more of configs (skip client configs),
2186 webpage (skip initial webpage), js (skip js player). While these op‐
2187 tions can help reduce the number of requests needed or avoid some
2188 rate-limiting, they could cause some issues. See #860
2189 (https://github.com/yt-dlp/yt-dlp/pull/860) for more details
2190 • comment_sort: top or new (default) - choose comment sorting mode (on
2192 YouTube's side)
2193 • max_comments: Limit the amount of comments to gather. Comma-separat‐
2195 ed list of integers representing max-comments,max-parents,max-
2196 replies,max-replies-per-thread. Default is all,all,all,all
2197 • E.g. all,all,1000,10 will get a maximum of 1000 replies total,
2199 with up to 10 replies per thread. 1000,all,100 will get a maximum
2200 of 1000 comments, with a maximum of 100 replies total
2201 • include_incomplete_formats: Extract formats that cannot be downloaded
2203 completely (live dash and post-live m3u8)
2204 • innertube_host: Innertube API host to use for all API requests; e.g.
2206 studio.youtube.com, youtubei.googleapis.com. Note that cookies ex‐
2207 ported from one subdomain will not work on others
2208 • innertube_key: Innertube API key to use for all API requests
2210 youtubetab (YouTube playlists, channels, feeds, etc.)
2212 • skip: One or more of webpage (skip initial webpage download), au‐
2213 thcheck (allow the download of playlists requiring authentication
2214 when no initial webpage is downloaded. This may cause unwanted be‐
2215 havior, see #1122 (https://github.com/yt-dlp/yt-dlp/pull/1122) for
2216 more details)
2217 • approximate_date: Extract approximate upload_date and timestamp in
2219 flat-playlist. This may cause date-based filters to be slightly off
2220 generic
2222 • fragment_query: Passthrough any query in mpd/m3u8 manifest URLs to
2223 their fragments. Does not apply to ffmpeg
2224 funimation
2226 • language: Audio languages to extract, e.g. funimation:language=eng‐
2227 lish,japanese
2228 • version: The video version to extract - uncut or simulcast
2230 crunchyrollbeta (Crunchyroll)
2232 • format: Which stream type(s) to extract (default: adaptive_hls). Po‐
2233 tentially useful values include adaptive_hls, adaptive_dash, vo_adap‐
2234 tive_hls, vo_adaptive_dash, download_hls, download_dash, multi‐
2235 track_adaptive_hls_v2
2236 • hardsub: Preference order for which hardsub versions to extract, or
2238 all (default: None = no hardsubs), e.g. crunchyrollbeta:hardsub=en-
2239 US,None
2240 vikichannel
2242 • video_types: Types of videos to download - one or more of episodes,
2243 movies, clips, trailers
2244 niconico
2246 • segment_duration: Segment duration in milliseconds for HLS-DMC for‐
2247 mats. Use it at your own risk since this feature may result in your
2248 account termination.
2249 youtubewebarchive
2251 • check_all: Try to check more at the cost of more requests. One or
2252 more of thumbnails, captures
2253 gamejolt
2255 • comment_sort: hot (default), you (cookies needed), top, new - choose
2256 comment sorting mode (on GameJolt's side)
2257 hotstar
2259 • res: resolution to ignore - one or more of sd, hd, fhd
2260 • vcodec: vcodec to ignore - one or more of h264, h265, dvh265
2262 • dr: dynamic range to ignore - one or more of sdr, hdr10, dv
2264 tiktok
2266 • api_hostname: Hostname to use for mobile API requests, e.g. api-
2267 h2.tiktokv.com
2268 • app_version: App version to call mobile APIs with - should be set
2270 along with manifest_app_version, e.g. 20.2.1
2271 • manifest_app_version: Numeric app version to call mobile APIs with,
2273 e.g. 221
2274 rokfinchannel
2276 • tab: Which tab to download - one of new, top, videos, podcasts,
2277 streams, stacks
2278 twitter
2280 • force_graphql: Force usage of the GraphQL API. By default it will
2281 only be used if login cookies are provided
2282 Note: These options may be changed/removed in the future without con‐
2284 cern for backward compatibility
2285
2287 You can install yt-dlp using the binaries, PIP
2288 (https://pypi.org/project/yt-dlp) or one using a third-party package
2289 manager. See the wiki (https://github.com/yt-dlp/yt-dlp/wiki/Installa‐
2290 tion) for detailed instructions
2291 UPDATE
2293 You can use yt-dlp -U to update if you are using the release binaries
2294 If you installed with PIP (https://github.com/yt-dlp/yt-dlp/wiki/In‐
2296 stallation#with-pip), simply re-run the same command that was used to
2297 install the program
2298 For other third-party package managers, see the wiki
2300 (https://github.com/yt-dlp/yt-dlp/wiki/Installation#third-party-pack‐
2301 age-managers) or refer their documentation
2302 Note: The manpages, shell completion files etc. are available in the
2304 source tarball (https://github.com/yt-dlp/yt-dlp/releases/latest/down‐
2305 load/yt-dlp.tar.gz)
2306 DEPENDENCIES
2308 Python versions 3.7+ (CPython and PyPy) are supported. Other versions
2309 and implementations may or may not work correctly.
2310 While all the other dependencies are optional, ffmpeg and ffprobe are
2312 highly recommended
2313 Strongly recommended
2315 • ffmpeg and ffprobe (https://www.ffmpeg.org) - Required for merging
2316 separate video and audio files as well as for various post-processing
2317 tasks. License depends on the build (https://www.ffmpeg.org/le‐
2318 gal.html)
2319 There are bugs in ffmpeg that causes various issues when used along‐
2321 side yt-dlp. Since ffmpeg is such an important dependency, we pro‐
2322 vide custom builds (https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-
2323 static-auto-builds) with patches for some of these issues at yt-
2324 dlp/FFmpeg-Builds (https://github.com/yt-dlp/FFmpeg-Builds). See the
2325 readme (https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for
2326 details on the specific issues solved by these builds
2327 Important: What you need is ffmpeg binary, NOT the python package of
2329 the same name (https://pypi.org/project/ffmpeg)
2330 Networking
2332 • certifi (https://github.com/certifi/python-certifi)* - Provides
2333 Mozilla's root certificate bundle. Licensed under MPLv2
2334 (https://github.com/certifi/python-certifi/blob/master/LICENSE)
2335 • brotli (https://github.com/google/brotli)* or brotlicffi
2337 (https://github.com/python-hyper/brotlicffi) - Brotli
2338 (https://en.wikipedia.org/wiki/Brotli) content encoding support.
2339 Both licensed under MIT 1 (https://github.com/google/brotli/blob/mas‐
2340 ter/LICENSE) 2 (https://github.com/python-hyper/brotlicffi/blob/mas‐
2341 ter/LICENSE)
2342 • websockets (https://github.com/aaugustin/websockets)* - For download‐
2344 ing over websocket. Licensed under BSD-3-Clause
2345 (https://github.com/aaugustin/websockets/blob/main/LICENSE)
2346 Metadata
2348 • mutagen (https://github.com/quodlibet/mutagen)* - For --embed-thumb‐
2349 nail in certain formats. Licensed under GPLv2+
2350 (https://github.com/quodlibet/mutagen/blob/master/COPYING)
2351 • AtomicParsley (https://github.com/wez/atomicparsley) - For --embed-
2353 thumbnail in mp4/m4a files when mutagen/ffmpeg cannot. Licensed un‐
2354 der GPLv2+ (https://github.com/wez/atomicparsley/blob/master/COPYING)
2355 • xattr (https://github.com/xattr/xattr), pyxattr
2357 (https://github.com/iustin/pyxattr) or setfattr (http://savan‐
2358 nah.nongnu.org/projects/attr) - For writing xattr metadata (--xattr)
2359 on Linux. Licensed under MIT (https://github.com/xattr/xat‐
2360 tr/blob/master/LICENSE.txt), LGPL2.1 (https://github.com/iustin/pyx‐
2361 attr/blob/master/COPYING) and GPLv2+ (http://git.savan‐
2362 nah.nongnu.org/cgit/attr.git/tree/doc/COPYING) respectively
2363 Misc
2365 • pycryptodomex (https://github.com/Legrandin/pycryptodome)* - For de‐
2366 crypting AES-128 HLS streams and various other data. Licensed under
2367 BSD-2-Clause (https://github.com/Legrandin/pycryptodome/blob/mas‐
2368 ter/LICENSE.rst)
2369 • phantomjs (https://github.com/ariya/phantomjs) - Used in extractors
2371 where javascript needs to be run. Licensed under BSD-3-Clause
2372 (https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
2373 • secretstorage (https://github.com/mitya57/secretstorage) - For
2375 --cookies-from-browser to access the Gnome keyring while decrypting
2376 cookies of Chromium-based browsers on Linux. Licensed under
2377 BSD-3-Clause (https://github.com/mitya57/secretstorage/blob/mas‐
2378 ter/LICENSE)
2379 • Any external downloader that you want to use with --downloader
2381 Deprecated
2383 • avconv and avprobe (https://www.libav.org) - Now deprecated alterna‐
2384 tive to ffmpeg. License depends on the build (https://libav.org/le‐
2385 gal)
2386 • sponskrub (https://github.com/faissaloo/SponSkrub) - For using the
2388 now deprecated sponskrub options. Licensed under GPLv3+
2389 (https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
2390 • rtmpdump (http://rtmpdump.mplayerhq.hu) - For downloading rtmp
2392 streams. ffmpeg can be used instead with --downloader ffmpeg. Li‐
2393 censed under GPLv2+ (http://rtmpdump.mplayerhq.hu)
2394 • mplayer (http://mplayerhq.hu/design7/info.html) or mpv
2396 (https://mpv.io) - For downloading rstp/mms streams. ffmpeg can be
2397 used instead with --downloader ffmpeg. Licensed under GPLv2+
2398 (https://github.com/mpv-player/mpv/blob/master/Copyright)
2399 To use or redistribute the dependencies, you must agree to their re‐
2401 spective licensing terms.
2402 The standalone release binaries are built with the Python interpreter
2404 and the packages marked with * included.
2405 If you do not have the necessary dependencies for a task you are at‐
2407 tempting, yt-dlp will warn you. All the currently available dependen‐
2408 cies are visible at the top of the --verbose output
2409 COMPILE
2411 Standalone PyInstaller Builds
2412 To build the standalone executable, you must have Python and pyin‐
2413 staller (plus any of yt-dlp's optional dependencies if needed). Once
2414 you have all the necessary dependencies installed, simply run
2415 pyinst.py. The executable will be built for the same architecture
2416 (x86/ARM, 32/64 bit) as the Python used.
2417 python3 -m pip install -U pyinstaller -r requirements.txt
2419 python3 devscripts/make_lazy_extractors.py
2420 python3 pyinst.py
2421 On some systems, you may need to use py or python instead of python3.
2423 pyinst.py accepts any arguments that can be passed to pyinstaller, such
2425 as --onefile/-F or --onedir/-D, which is further documented here
2426 (https://pyinstaller.org/en/stable/usage.html#what-to-generate).
2427 Note: Pyinstaller versions below 4.4 do not support
2429 (https://github.com/pyinstaller/pyinstaller#requirements-and-tested-
2430 platforms) Python installed from the Windows store without using a vir‐
2431 tual environment.
2432 Important: Running pyinstaller directly without using pyinst.py is not
2434 officially supported. This may or may not work correctly.
2435 Platform-independent Binary (UNIX)
2437 You will need the build tools python (3.7+), zip, make (GNU), pandoc*
2438 and pytest*.
2439 After installing these, simply run make.
2441 You can also run make yt-dlp instead to compile only the binary without
2443 updating any of the additional files. (The build tools marked with *
2444 are not needed for this)
2445 Standalone Py2Exe Builds (Windows)
2447 While we provide the option to build with py2exe
2448 (https://www.py2exe.org), it is recommended to build using PyInstaller
2449 instead since the py2exe builds cannot contain pycryptodomex/certifi
2450 and needs VC++14 on the target computer to run.
2451 If you wish to build it anyway, install Python and py2exe, and then
2453 simply run setup.py py2exe
2454 py -m pip install -U py2exe -r requirements.txt
2456 py devscripts/make_lazy_extractors.py
2457 py setup.py py2exe
2458 Related scripts
2460 • devscripts/update-version.py [revision] - Update the version number
2461 based on current date
2462 • devscripts/set-variant.py variant [-M update_message] - Set the build
2464 variant of the executable
2465 • devscripts/make_lazy_extractors.py - Create lazy extractors. Running
2467 this before building the binaries (any variant) will improve their
2468 startup performance. Set the environment variable YTDLP_NO_LAZY_EX‐
2469 TRACTORS=1 if you wish to forcefully disable lazy extractor loading.
2470 You can also fork the project on GitHub and run your fork's build work‐
2472 flow to automatically build a full release
2473
2475 Note that all plugins are imported even if not invoked, and that there
2476 are no checks performed on plugin code. Use plugins at your own risk
2477 and only if you trust the code!
2478 Plugins can be of <type>s extractor or postprocessor. - Extractor
2480 plugins do not need to be enabled from the CLI and are automatically
2481 invoked when the input URL is suitable for it. - Extractor plugins
2482 take priority over builtin extractors. - Postprocessor plugins can be
2483 invoked using --use-postprocessor NAME.
2484 Plugins are loaded from the namespace packages yt_dlp_plugins.extractor
2486 and yt_dlp_plugins.postprocessor.
2487 In other words, the file structure on the disk looks something like:
2489 yt_dlp_plugins/
2491 extractor/
2492 myplugin.py
2493 postprocessor/
2494 myplugin.py
2495 yt-dlp looks for these yt_dlp_plugins namespace folders in many loca‐
2497 tions (see below) and loads in plugins from all of them.
2498 See the wiki for some known plugins (https://github.com/yt-dlp/yt-
2500 dlp/wiki/Plugins)
2501 Installing Plugins
2503 Plugins can be installed using various methods and locations.
2504 1. Configuration directories: Plugin packages (containing a
2506 yt_dlp_plugins namespace folder) can be dropped into the following
2507 standard configuration locations:
2508 • User Plugins
2510 • ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plug‐
2512 ins/ (recommended on Linux/macOS)
2513 • ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plug‐
2515 ins/
2516 • ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/ (rec‐
2518 ommended on Windows)
2519 • ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2521 • ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
2523 • ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2525 • System Plugins
2527 • /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
2529 • /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/
2531 2. Executable location: Plugin packages can similarly be installed in a
2533 yt-dlp-plugins directory under the executable location:
2534 • Binary: where <root-dir>/yt-dlp.exe, <root-dir>/yt-dlp-plug‐
2536 ins/<package name>/yt_dlp_plugins/
2537 • Source: where <root-dir>/yt_dlp/__main__.py, <root-dir>/yt-dlp-
2539 plugins/<package name>/yt_dlp_plugins/
2540 3. pip and other locations in PYTHONPATH
2542 • Plugin packages can be installed and managed using pip. See yt-
2544 dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-plug‐
2545 ins) for an example.
2546 • Note: plugin files between plugin packages installed with pip
2548 must have unique filenames.
2549 • Any path in PYTHONPATH is searched in for the yt_dlp_plugins
2551 namespace folder.
2552 • Note: This does not apply for Pyinstaller/py2exe builds.
2554 .zip, .egg and .whl archives containing a yt_dlp_plugins namespace
2556 folder in their root are also supported as plugin packages. * e.g.
2557 ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip where mypluginpkg.zip
2558 contains yt_dlp_plugins/<type>/myplugin.py
2559 Run yt-dlp with --verbose to check if the plugin has been loaded.
2561 Developing Plugins
2563 See the yt-dlp-sample-plugins (https://github.com/yt-dlp/yt-dlp-sample-
2564 plugins) repo for a template plugin package and the Plugin Development
2565 (https://github.com/yt-dlp/yt-dlp/wiki/Plugin-Development) section of
2566 the wiki for a plugin development guide.
2567 All public classes with a name ending in IE/PP are imported from each
2569 file for extractors and postprocessors repectively. This respects un‐
2570 derscore prefix (e.g. _MyBasePluginIE is private) and __all__. Mod‐
2571 ules can similarly be excluded by prefixing the module name with an un‐
2572 derscore (e.g. _myplugin.py).
2573 To replace an existing extractor with a subclass of one, set the plug‐
2575 in_name class keyword argument (e.g. class MyPluginIE(ABuiltInIE,
2576 plugin_name='myplugin') will replace ABuiltInIE with MyPluginIE).
2577 Since the extractor replaces the parent, you should exclude the sub‐
2578 class extractor from being imported separately by making it private us‐
2579 ing one of the methods described above.
2580 If you are a plugin author, add yt-dlp-plugins (https://github.com/top‐
2582 ics/yt-dlp-plugins) as a topic to your repository for discoverability.
2583 See the Developer Instructions (https://github.com/yt-dlp/yt-
2585 dlp/blob/master/CONTRIBUTING.md#developer-instructions) on how to write
2586 and test an extractor.
2587
2589 yt-dlp makes the best effort to be a good command-line program, and
2590 thus should be callable from any programming language.
2591 Your program should avoid parsing the normal stdout since they may
2593 change in future versions. Instead they should use options such as -J,
2594 --print, --progress-template, --exec etc to create console output that
2595 you can reliably reproduce and parse.
2596 From a Python program, you can embed yt-dlp in a more powerful fashion,
2598 like this:
2599 from yt_dlp import YoutubeDL
2601 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2603 with YoutubeDL() as ydl:
2604 ydl.download(URLS)
2605 Most likely, you'll want to use various options. For a list of options
2607 available, have a look at yt_dlp/YoutubeDL.py.
2608 Tip: If you are porting your code from youtube-dl to yt-dlp, one impor‐
2610 tant point to look out for is that we do not guarantee the return value
2611 of YoutubeDL.extract_info to be json serializable, or even be a dictio‐
2612 nary. It will be dictionary-like, but if you want to ensure it is a
2613 serializable dictionary, pass it through YoutubeDL.sanitize_info as
2614 shown in the example below
2615 Embedding examples
2617 Extracting information
2618 import json
2619 import yt_dlp
2620 URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'
2622 # ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
2624 ydl_opts = {}
2625 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2626 info = ydl.extract_info(URL, download=False)
2627 # ℹ️ ydl.sanitize_info makes the info json-serializable
2629 print(json.dumps(ydl.sanitize_info(info)))
2630 Download using an info-json
2632 import yt_dlp
2633 INFO_FILE = 'path/to/video.info.json'
2635 with yt_dlp.YoutubeDL() as ydl:
2637 error_code = ydl.download_with_info_file(INFO_FILE)
2638 print('Some videos failed to download' if error_code
2640 else 'All videos successfully downloaded')
2641 Extract audio
2643 import yt_dlp
2644 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2646 ydl_opts = {
2648 'format': 'm4a/bestaudio/best',
2649 # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
2650 'postprocessors': [{ # Extract audio using ffmpeg
2651 'key': 'FFmpegExtractAudio',
2652 'preferredcodec': 'm4a',
2653 }]
2654 }
2655 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2657 error_code = ydl.download(URLS)
2658 Filter videos
2660 import yt_dlp
2661 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2663 def longer_than_a_minute(info, *, incomplete):
2665 """Download only videos longer than a minute (or with unknown duration)"""
2666 duration = info.get('duration')
2667 if duration and duration < 60:
2668 return 'The video is too short'
2669 ydl_opts = {
2671 'match_filter': longer_than_a_minute,
2672 }
2673 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2675 error_code = ydl.download(URLS)
2676 Adding logger and progress hook
2678 import yt_dlp
2679 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2681 class MyLogger:
2683 def debug(self, msg):
2684 # For compatibility with youtube-dl, both debug and info are passed into debug
2685 # You can distinguish them by the prefix '[debug] '
2686 if msg.startswith('[debug] '):
2687 pass
2688 else:
2689 self.info(msg)
2690 def info(self, msg):
2692 pass
2693 def warning(self, msg):
2695 pass
2696 def error(self, msg):
2698 print(msg)
2699 # ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
2702 def my_hook(d):
2703 if d['status'] == 'finished':
2704 print('Done downloading, now post-processing ...')
2705 ydl_opts = {
2708 'logger': MyLogger(),
2709 'progress_hooks': [my_hook],
2710 }
2711 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2713 ydl.download(URLS)
2714 Add a custom PostProcessor
2716 import yt_dlp
2717 URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2719 # ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
2721 class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
2722 def run(self, info):
2723 self.to_screen('Doing stuff')
2724 return [], info
2725 with yt_dlp.YoutubeDL() as ydl:
2728 # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
2729 ydl.add_post_processor(MyCustomPP(), when='pre_process')
2730 ydl.download(URLS)
2731 Use a custom format selector
2733 import yt_dlp
2734 URL = ['https://www.youtube.com/watch?v=BaW_jenozKc']
2736 def format_selector(ctx):
2738 """ Select the best video and the best audio that won't result in an mkv.
2739 NOTE: This is just an example and does not handle all cases """
2740 # formats are already sorted worst to best
2742 formats = ctx.get('formats')[::-1]
2743 # acodec='none' means there is no audio
2745 best_video = next(f for f in formats
2746 if f['vcodec'] != 'none' and f['acodec'] == 'none')
2747 # find compatible audio extension
2749 audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
2750 # vcodec='none' means there is no video
2751 best_audio = next(f for f in formats if (
2752 f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))
2753 # These are the minimum required fields for a merged format
2755 yield {
2756 'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
2757 'ext': best_video['ext'],
2758 'requested_formats': [best_video, best_audio],
2759 # Must be + separated list of protocols
2760 'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
2761 }
2762 ydl_opts = {
2765 'format': format_selector,
2766 }
2767 with yt_dlp.YoutubeDL(ydl_opts) as ydl:
2769 ydl.download(URLS)
2770
2772 • Merged with youtube-dl v2021.12.17+ commit/195f22f
2773 (https://github.com/ytdl-org/youtube-dl/commit/195f22f) and youtube-
2774 dlc v2020.11.11-3+ commit/f9401f2 (https://github.com/black‐
2775 jack4494/yt-dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee): You
2776 get all the features and patches of youtube-dlc
2777 (https://github.com/blackjack4494/yt-dlc) in addition to the latest
2778 youtube-dl (https://github.com/ytdl-org/youtube-dl)
2779 • SponsorBlock Integration: You can mark/remove sponsor sections in
2781 YouTube videos by utilizing the SponsorBlock (https://spon‐
2782 sor.ajay.app) API
2783 • Format Sorting: The default format sorting options have been changed
2785 so that higher resolution and better codecs will be now preferred in‐
2786 stead of simply using larger bitrate. Furthermore, you can now spec‐
2787 ify the sort order using -S. This allows for much easier format se‐
2788 lection than what is possible by simply using --format (examples)
2789 • Merged with animelover1984/youtube-dl: You get most of the features
2791 and improvements from animelover1984/youtube-dl
2792 (https://github.com/animelover1984/youtube-dl) including --write-com‐
2793 ments, BiliBiliSearch, BilibiliChannel, Embedding thumbnail in
2794 mp4/ogg/opus, playlist infojson etc. Note that NicoNico livestreams
2795 are not available. See #31 (https://github.com/yt-dlp/yt-
2796 dlp/pull/31) for details.
2797 • YouTube improvements:
2799 • Supports Clips, Stories (ytstories:<channel UCID>), Search (includ‐
2801 ing filters)*, YouTube Music Search, Channel-specific search,
2802 Search prefixes (ytsearch:, ytsearchdate:)*, Mixes, YouTube Music
2803 Albums/Channels (except self-uploaded music (https://github.com/yt-
2804 dlp/yt-dlp/issues/723)), and Feeds (:ytfav, :ytwatchlater, :ytsubs,
2805 :ythistory, :ytrec, :ytnotif)
2806 • Fix for n-sig based throttling (https://github.com/ytdl-
2808 org/youtube-dl/issues/29326) *
2809 • Supports some (but not all) age-gated content without cookies
2811 • Download livestreams from the start using --live-from-start (exper‐
2813 imental)
2814 • 255kbps audio is extracted (if available) from YouTube Music when
2816 premium cookies are given
2817 • Channel URLs download all uploads of the channel, including shorts
2819 and live
2820 • Cookies from browser: Cookies can be automatically extracted from all
2822 major web browsers using --cookies-from-browser BROWS‐
2823 ER[+KEYRING][:PROFILE][::CONTAINER]
2824 • Download time range: Videos can be downloaded partially based on ei‐
2826 ther timestamps or chapters using --download-sections
2827 • Split video by chapters: Videos can be split into multiple files
2829 based on chapters using --split-chapters
2830 • Multi-threaded fragment downloads: Download multiple fragments of
2832 m3u8/mpd videos in parallel. Use --concurrent-fragments (-N) option
2833 to set the number of threads used
2834 • Aria2c with HLS/DASH: You can use aria2c as the external downloader
2836 for DASH(mpd) and HLS(m3u8) formats
2837 • New and fixed extractors: Many new extractors have been added and a
2839 lot of existing ones have been fixed. See the changelog or the list
2840 of supported sites
2841 • New MSOs: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
2843 • Subtitle extraction from manifests: Subtitles can be extracted from
2845 streaming media manifests. See commit/be6202f
2846 (https://github.com/yt-dlp/yt-dlp/com‐
2847 mit/be6202f12b97858b9d716e608394b51065d0419f) for details
2848 • Multiple paths and output templates: You can give different output
2850 templates and download paths for different types of files. You can
2851 also set a temporary path where intermediary files are downloaded to
2852 using --paths (-P)
2853 • Portable Configuration: Configuration files are automatically loaded
2855 from the home and root directories. See CONFIGURATION for details
2856 • Output template improvements: Output templates can now have date-time
2858 formatting, numeric offsets, object traversal etc. See output tem‐
2859 plate for details. Even more advanced operations can also be done
2860 with the help of --parse-metadata and --replace-in-metadata
2861 • Other new options: Many new options have been added such as --alias,
2863 --print, --concat-playlist, --wait-for-video, --retry-sleep, --sleep-
2864 requests, --convert-thumbnails, --force-download-archive, --force-
2865 overwrites, --break-on-reject etc
2866 • Improvements: Regex and other operators in --format/--match-filter,
2868 multiple --postprocessor-args and --downloader-args, faster archive
2869 checking, more format selection options, merge multi-video/audio,
2870 multiple --config-locations, --exec at different stages, etc
2871 • Plugins: Extractors and PostProcessors can be loaded from an external
2873 file. See plugins for details
2874 • Self-updater: The releases can be updated using yt-dlp -U
2876 See changelog or commits (https://github.com/yt-dlp/yt-dlp/commits) for
2878 the full list of changes
2879 Features marked with a * have been back-ported to youtube-dl
2881 Differences in default behavior
2883 Some of yt-dlp's default options are different from that of youtube-dl
2884 and youtube-dlc:
2885 • The options --auto-number (-A), --title (-t) and --literal (-l), no
2887 longer work. See removed options for details
2888 • avconv is not supported as an alternative to ffmpeg
2890 • yt-dlp stores config files in slightly different locations to
2892 youtube-dl. See CONFIGURATION for a list of correct locations
2893 • The default output template is %(title)s [%(id)s].%(ext)s. There is
2895 no real reason for this change. This was changed before yt-dlp was
2896 ever made public and now there are no plans to change it back to
2897 %(title)s-%(id)s.%(ext)s. Instead, you may use --compat-options
2898 filename
2899 • The default format sorting is different from youtube-dl and prefers
2901 higher resolution and better codecs rather than higher bitrates. You
2902 can use the --format-sort option to change this to any order you pre‐
2903 fer, or use --compat-options format-sort to use youtube-dl's sorting
2904 order
2905 • The default format selector is bv*+ba/b. This means that if a com‐
2907 bined video + audio format that is better than the best video-only
2908 format is found, the former will be preferred. Use -f bv+ba/b or
2909 --compat-options format-spec to revert this
2910 • Unlike youtube-dlc, yt-dlp does not allow merging multiple au‐
2912 dio/video streams into one file by default (since this conflicts with
2913 the use of -f bv*+ba). If needed, this feature must be enabled using
2914 --audio-multistreams and --video-multistreams. You can also use
2915 --compat-options multistreams to enable both
2916 • --no-abort-on-error is enabled by default. Use --abort-on-error or
2918 --compat-options abort-on-error to abort on errors instead
2919 • When writing metadata files such as thumbnails, description or infoj‐
2921 son, the same information (if available) is also written for
2922 playlists. Use --no-write-playlist-metafiles or --compat-options no-
2923 playlist-metafiles to not write these files
2924 • --add-metadata attaches the infojson to mkv files in addition to
2926 writing the metadata when used with --write-info-json. Use --no-em‐
2927 bed-info-json or --compat-options no-attach-info-json to revert this
2928 • Some metadata are embedded into different fields when using --add-
2930 metadata as compared to youtube-dl. Most notably, comment field con‐
2931 tains the webpage_url and synopsis contains the description. You can
2932 use --parse-metadata to modify this to your liking or use --compat-
2933 options embed-metadata to revert this
2934 • playlist_index behaves differently when used with options like
2936 --playlist-reverse and --playlist-items. See #302
2937 (https://github.com/yt-dlp/yt-dlp/issues/302) for details. You can
2938 use --compat-options playlist-index if you want to keep the earlier
2939 behavior
2940 • The output of -F is listed in a new format. Use --compat-options
2942 list-formats to revert this
2943 • Live chats (if available) are considered as subtitles. Use --sub-
2945 langs all,-live_chat to download all subtitles except live chat. You
2946 can also use --compat-options no-live-chat to prevent any live
2947 chat/danmaku from downloading
2948 • YouTube channel URLs download all uploads of the channel. To down‐
2950 load only the videos in a specific tab, pass the tab's URL. If the
2951 channel does not show the requested tab, an error will be raised.
2952 Also, /live URLs raise an error if there are no live videos instead
2953 of silently downloading the entire channel. You may use --compat-op‐
2954 tions no-youtube-channel-redirect to revert all these redirections
2955 • Unavailable videos are also listed for YouTube playlists. Use --com‐
2957 pat-options no-youtube-unavailable-videos to remove this
2958 • The upload dates extracted from YouTube are in UTC when available
2960 (https://github.com/yt-dlp/yt-
2961 dlp/blob/89e4d86171c7b7c997c77d4714542e0383bf0db0/yt_dlp/extrac‐
2962 tor/youtube.py#L3898-L3900). Use --compat-options no-youtube-prefer-
2963 utc-upload-date to prefer the non-UTC upload date.
2964 • If ffmpeg is used as the downloader, the downloading and merging of
2966 formats happen in a single step when possible. Use --compat-options
2967 no-direct-merge to revert this
2968 • Thumbnail embedding in mp4 is done with mutagen if possible. Use
2970 --compat-options embed-thumbnail-atomicparsley to force the use of
2971 AtomicParsley instead
2972 • Some private fields such as filenames are removed by default from the
2974 infojson. Use --no-clean-infojson or --compat-options no-clean-info‐
2975 json to revert this
2976 • When --embed-subs and --write-subs are used together, the subtitles
2978 are written to disk and also embedded in the media file. You can use
2979 just --embed-subs to embed the subs and automatically delete the sep‐
2980 arate file. See #630 (comment) (https://github.com/yt-dlp/yt-dlp/is‐
2981 sues/630#issuecomment-893659460) for more info. --compat-options no-
2982 keep-subs can be used to revert this
2983 • certifi will be used for SSL root certificates, if installed. If you
2985 want to use system certificates (e.g. self-signed), use --compat-op‐
2986 tions no-certifi
2987 • yt-dlp's sanitization of invalid characters in filenames is differ‐
2989 ent/smarter than in youtube-dl. You can use --compat-options file‐
2990 name-sanitization to revert to youtube-dl's behavior
2991 • yt-dlp tries to parse the external downloader outputs into the stan‐
2993 dard progress output if possible (Currently implemented: [STRIKE‐
2994 OUT:aria2c] (https://github.com/yt-dlp/yt-dlp/issues/5931)). You can
2995 use --compat-options no-external-downloader-progress to get the down‐
2996 loader output as-is
2997 For ease of use, a few more compat options are available:
2999 • --compat-options all: Use all compat options (Do NOT use)
3001 • --compat-options youtube-dl: Same as --compat-options all,-multi‐
3003 streams
3004 • --compat-options youtube-dlc: Same as --compat-options all,-no-live-
3006 chat,-no-youtube-channel-redirect
3007 • --compat-options 2021: Same as --compat-options 2022,no-certifi,file‐
3009 name-sanitization,no-youtube-prefer-utc-upload-date
3010 • --compat-options 2022: Same as --compat-options no-external-download‐
3012 er-progress. Use this to enable all future compat options
3013
3015 These are all the deprecated options and the current alternative to
3016 achieve the same effect
3017 Almost redundant options
3019 While these options are almost the same as their new counterparts,
3020 there are some differences that prevents them being redundant
3021 -j, --dump-json --print "%()j"
3023 -F, --list-formats --print formats_table
3024 --list-thumbnails --print thumbnails_table --print playlist:thumbnails_table
3025 --list-subs --print automatic_captions_table --print subtitles_table
3026 Redundant options
3028 While these options are redundant, they are still expected to be used
3029 due to their ease of use
3030 --get-description --print description
3032 --get-duration --print duration_string
3033 --get-filename --print filename
3034 --get-format --print format
3035 --get-id --print id
3036 --get-thumbnail --print thumbnail
3037 -e, --get-title --print title
3038 -g, --get-url --print urls
3039 --match-title REGEX --match-filter "title ~= (?i)REGEX"
3040 --reject-title REGEX --match-filter "title !~= (?i)REGEX"
3041 --min-views COUNT --match-filter "view_count >=? COUNT"
3042 --max-views COUNT --match-filter "view_count <=? COUNT"
3043 --user-agent UA --add-header "User-Agent:UA"
3044 --referer URL --add-header "Referer:URL"
3045 --playlist-start NUMBER -I NUMBER:
3046 --playlist-end NUMBER -I :NUMBER
3047 --playlist-reverse -I ::-1
3048 --no-playlist-reverse Default
3049 Not recommended
3051 While these options still work, their use is not recommended since
3052 there are other alternatives to achieve the same
3053 --force-generic-extractor --ies generic,default
3055 --exec-before-download CMD --exec "before_dl:CMD"
3056 --no-exec-before-download --no-exec
3057 --all-formats -f all
3058 --all-subs --sub-langs all --write-subs
3059 --print-json -j --no-simulate
3060 --autonumber-size NUMBER Use string formatting, e.g. %(autonumber)03d
3061 --autonumber-start NUMBER Use internal field formatting like %(autonumber+NUMBER)s
3062 --id -o "%(id)s.%(ext)s"
3063 --metadata-from-title FORMAT --parse-metadata "%(title)s:FORMAT"
3064 --hls-prefer-native --downloader "m3u8:native"
3065 --hls-prefer-ffmpeg --downloader "m3u8:ffmpeg"
3066 --list-formats-old --compat-options list-formats (Alias: --no-list-formats-as-table)
3067 --list-formats-as-table --compat-options -list-formats [Default] (Alias: --no-list-formats-old)
3068 --youtube-skip-dash-manifest --extractor-args "youtube:skip=dash" (Alias: --no-youtube-include-dash-manifest)
3069 --youtube-skip-hls-manifest --extractor-args "youtube:skip=hls" (Alias: --no-youtube-include-hls-manifest)
3070 --youtube-include-dash-manifest Default (Alias: --no-youtube-skip-dash-manifest)
3071 --youtube-include-hls-manifest Default (Alias: --no-youtube-skip-hls-manifest)
3072 Developer options
3074 These options are not intended to be used by the end-user
3075 --test Download only part of video for testing extractors
3077 --load-pages Load pages dumped by --write-pages
3078 --youtube-print-sig-code For testing youtube signatures
3079 --allow-unplayable-formats List unplayable formats also
3080 --no-allow-unplayable-formats Default
3081 Old aliases
3083 These are aliases that are no longer documented for various reasons
3084 --avconv-location --ffmpeg-location
3086 --clean-infojson --clean-info-json
3087 --cn-verification-proxy URL --geo-verification-proxy URL
3088 --dump-headers --print-traffic
3089 --dump-intermediate-pages --dump-pages
3090 --force-write-download-archive --force-write-archive
3091 --load-info --load-info-json
3092 --no-clean-infojson --no-clean-info-json
3093 --no-split-tracks --no-split-chapters
3094 --no-write-srt --no-write-subs
3095 --prefer-unsecure --prefer-insecure
3096 --rate-limit RATE --limit-rate RATE
3097 --split-tracks --split-chapters
3098 --srt-lang LANGS --sub-langs LANGS
3099 --trim-file-names LENGTH --trim-filenames LENGTH
3100 --write-srt --write-subs
3101 --yes-overwrites --force-overwrites
3102 Sponskrub Options
3104 Support for SponSkrub (https://github.com/faissaloo/SponSkrub) has been
3105 deprecated in favor of the --sponsorblock options
3106 --sponskrub --sponsorblock-mark all
3108 --no-sponskrub --no-sponsorblock
3109 --sponskrub-cut --sponsorblock-remove all
3110 --no-sponskrub-cut --sponsorblock-remove -all
3111 --sponskrub-force Not applicable
3112 --no-sponskrub-force Not applicable
3113 --sponskrub-location Not applicable
3114 --sponskrub-args Not applicable
3115 No longer supported
3117 These options may no longer work as intended
3118 --prefer-avconv avconv is not officially supported by yt-dlp (Alias: --no-prefer-ffmpeg)
3120 --prefer-ffmpeg Default (Alias: --no-prefer-avconv)
3121 -C, --call-home Not implemented
3122 --no-call-home Default
3123 --include-ads No longer supported
3124 --no-include-ads Default
3125 --write-annotations No supported site has annotations now
3126 --no-write-annotations Default
3127 --compat-options seperate-video-versions No longer needed
3128 Removed
3130 These options were deprecated since 2014 and have now been entirely re‐
3131 moved
3132 -A, --auto-number -o "%(autonumber)s-%(id)s.%(ext)s"
3134 -t, -l, --title, --literal -o "%(title)s-%(id)s.%(ext)s"
3135
3137 See CONTRIBUTING.md for instructions on Opening an Issue and Contribut‐
3138 ing code to the project
3139
3141 See the Wiki (https://github.com/yt-dlp/yt-dlp/wiki) for more informa‐
3142 tion
3143 yt-dlp(1)