]> Raphaƫl G. Git Repositories - youtubedl/blob - README.txt
24d43149bf85ef1ccf1a0b96e114ec06aec10ad3
[youtubedl] / README.txt
1 youtube-dl - download videos from youtube.com or other video platforms
2
3 - INSTALLATION
4 - DESCRIPTION
5 - OPTIONS
6 - CONFIGURATION
7 - OUTPUT TEMPLATE
8 - FORMAT SELECTION
9 - VIDEO SELECTION
10 - FAQ
11 - DEVELOPER INSTRUCTIONS
12 - EMBEDDING YOUTUBE-DL
13 - BUGS
14 - COPYRIGHT
15
16
17
18 INSTALLATION
19
20
21 To install it right away for all UNIX users (Linux, OS X, etc.), type:
22
23 sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl
24 sudo chmod a+rx /usr/local/bin/youtube-dl
25
26 If you do not have curl, you can alternatively use a recent wget:
27
28 sudo wget https://yt-dl.org/downloads/latest/youtube-dl -O /usr/local/bin/youtube-dl
29 sudo chmod a+rx /usr/local/bin/youtube-dl
30
31 Windows users can download an .exe file and place it in any location on
32 their PATH except for %SYSTEMROOT%\System32 (e.g. DO NOT put in
33 C:\Windows\System32).
34
35 You can also use pip:
36
37 sudo -H pip install --upgrade youtube-dl
38
39 This command will update youtube-dl if you have already installed it.
40 See the pypi page for more information.
41
42 OS X users can install youtube-dl with Homebrew:
43
44 brew install youtube-dl
45
46 Or with MacPorts:
47
48 sudo port install youtube-dl
49
50 Alternatively, refer to the developer instructions for how to check out
51 and work with the git repository. For further options, including PGP
52 signatures, see the youtube-dl Download Page.
53
54
55
56 DESCRIPTION
57
58
59 YOUTUBE-DL is a command-line program to download videos from YouTube.com
60 and a few more sites. It requires the Python interpreter, version 2.6,
61 2.7, or 3.2+, and it is not platform specific. It should work on your
62 Unix box, on Windows or on Mac OS X. It is released to the public
63 domain, which means you can modify it, redistribute it or use it however
64 you like.
65
66 youtube-dl [OPTIONS] URL [URL...]
67
68
69
70 OPTIONS
71
72
73 -h, --help Print this help text and exit
74 --version Print program version and exit
75 -U, --update Update this program to latest version. Make
76 sure that you have sufficient permissions
77 (run with sudo if needed)
78 -i, --ignore-errors Continue on download errors, for example to
79 skip unavailable videos in a playlist
80 --abort-on-error Abort downloading of further videos (in the
81 playlist or the command line) if an error
82 occurs
83 --dump-user-agent Display the current browser identification
84 --list-extractors List all supported extractors
85 --extractor-descriptions Output descriptions of all supported
86 extractors
87 --force-generic-extractor Force extraction to use the generic
88 extractor
89 --default-search PREFIX Use this prefix for unqualified URLs. For
90 example "gvsearch2:" downloads two videos
91 from google videos for youtube-dl "large
92 apple". Use the value "auto" to let
93 youtube-dl guess ("auto_warning" to emit a
94 warning when guessing). "error" just throws
95 an error. The default value "fixup_error"
96 repairs broken URLs, but emits an error if
97 this is not possible instead of searching.
98 --ignore-config Do not read configuration files. When given
99 in the global configuration file
100 /etc/youtube-dl.conf: Do not read the user
101 configuration in ~/.config/youtube-
102 dl/config (%APPDATA%/youtube-dl/config.txt
103 on Windows)
104 --config-location PATH Location of the configuration file; either
105 the path to the config or its containing
106 directory.
107 --flat-playlist Do not extract the videos of a playlist,
108 only list them.
109 --mark-watched Mark videos watched (YouTube only)
110 --no-mark-watched Do not mark videos watched (YouTube only)
111 --no-color Do not emit color codes in output
112
113
114 Network Options:
115
116 --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
117 To enable experimental SOCKS proxy, specify
118 a proper scheme. For example
119 socks5://127.0.0.1:1080/. Pass in an empty
120 string (--proxy "") for direct connection
121 --socket-timeout SECONDS Time to wait before giving up, in seconds
122 --source-address IP Client-side IP address to bind to
123 -4, --force-ipv4 Make all connections via IPv4
124 -6, --force-ipv6 Make all connections via IPv6
125 --geo-verification-proxy URL Use this proxy to verify the IP address for
126 some geo-restricted sites. The default
127 proxy specified by --proxy (or none, if the
128 options is not present) is used for the
129 actual downloading.
130
131
132 Video Selection:
133
134 --playlist-start NUMBER Playlist video to start at (default is 1)
135 --playlist-end NUMBER Playlist video to end at (default is last)
136 --playlist-items ITEM_SPEC Playlist video items to download. Specify
137 indices of the videos in the playlist
138 separated by commas like: "--playlist-items
139 1,2,5,8" if you want to download videos
140 indexed 1, 2, 5, 8 in the playlist. You can
141 specify range: "--playlist-items
142 1-3,7,10-13", it will download the videos
143 at index 1, 2, 3, 7, 10, 11, 12 and 13.
144 --match-title REGEX Download only matching titles (regex or
145 caseless sub-string)
146 --reject-title REGEX Skip download for matching titles (regex or
147 caseless sub-string)
148 --max-downloads NUMBER Abort after downloading NUMBER files
149 --min-filesize SIZE Do not download any videos smaller than
150 SIZE (e.g. 50k or 44.6m)
151 --max-filesize SIZE Do not download any videos larger than SIZE
152 (e.g. 50k or 44.6m)
153 --date DATE Download only videos uploaded in this date
154 --datebefore DATE Download only videos uploaded on or before
155 this date (i.e. inclusive)
156 --dateafter DATE Download only videos uploaded on or after
157 this date (i.e. inclusive)
158 --min-views COUNT Do not download any videos with less than
159 COUNT views
160 --max-views COUNT Do not download any videos with more than
161 COUNT views
162 --match-filter FILTER Generic video filter. Specify any key (see
163 help for -o for a list of available keys)
164 to match if the key is present, !key to
165 check if the key is not present,key >
166 NUMBER (like "comment_count > 12", also
167 works with >=, <, <=, !=, =) to compare
168 against a number, and & to require multiple
169 matches. Values which are not known are
170 excluded unless you put a question mark (?)
171 after the operator.For example, to only
172 match videos that have been liked more than
173 100 times and disliked less than 50 times
174 (or the dislike functionality is not
175 available at the given service), but who
176 also have a description, use --match-filter
177 "like_count > 100 & dislike_count <? 50 &
178 description" .
179 --no-playlist Download only the video, if the URL refers
180 to a video and a playlist.
181 --yes-playlist Download the playlist, if the URL refers to
182 a video and a playlist.
183 --age-limit YEARS Download only videos suitable for the given
184 age
185 --download-archive FILE Download only videos not listed in the
186 archive file. Record the IDs of all
187 downloaded videos in it.
188 --include-ads Download advertisements as well
189 (experimental)
190
191
192 Download Options:
193
194 -r, --limit-rate RATE Maximum download rate in bytes per second
195 (e.g. 50K or 4.2M)
196 -R, --retries RETRIES Number of retries (default is 10), or
197 "infinite".
198 --fragment-retries RETRIES Number of retries for a fragment (default
199 is 10), or "infinite" (DASH and hlsnative
200 only)
201 --skip-unavailable-fragments Skip unavailable fragments (DASH and
202 hlsnative only)
203 --abort-on-unavailable-fragment Abort downloading when some fragment is not
204 available
205 --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
206 (default is 1024)
207 --no-resize-buffer Do not automatically adjust the buffer
208 size. By default, the buffer size is
209 automatically resized from an initial value
210 of SIZE.
211 --playlist-reverse Download playlist videos in reverse order
212 --playlist-random Download playlist videos in random order
213 --xattr-set-filesize Set file xattribute ytdl.filesize with
214 expected file size (experimental)
215 --hls-prefer-native Use the native HLS downloader instead of
216 ffmpeg
217 --hls-prefer-ffmpeg Use ffmpeg instead of the native HLS
218 downloader
219 --hls-use-mpegts Use the mpegts container for HLS videos,
220 allowing to play the video while
221 downloading (some players may not be able
222 to play it)
223 --external-downloader COMMAND Use the specified external downloader.
224 Currently supports
225 aria2c,avconv,axel,curl,ffmpeg,httpie,wget
226 --external-downloader-args ARGS Give these arguments to the external
227 downloader
228
229
230 Filesystem Options:
231
232 -a, --batch-file FILE File containing URLs to download ('-' for
233 stdin)
234 --id Use only video ID in file name
235 -o, --output TEMPLATE Output filename template, see the "OUTPUT
236 TEMPLATE" for all the info
237 --autonumber-size NUMBER Specify the number of digits in
238 %(autonumber)s when it is present in output
239 filename template or --auto-number option
240 is given (default is 5)
241 --autonumber-start NUMBER Specify the start value for %(autonumber)s
242 (default is 1)
243 --restrict-filenames Restrict filenames to only ASCII
244 characters, and avoid "&" and spaces in
245 filenames
246 -A, --auto-number [deprecated; use -o
247 "%(autonumber)s-%(title)s.%(ext)s" ] Number
248 downloaded files starting from 00000
249 -t, --title [deprecated] Use title in file name
250 (default)
251 -l, --literal [deprecated] Alias of --title
252 -w, --no-overwrites Do not overwrite files
253 -c, --continue Force resume of partially downloaded files.
254 By default, youtube-dl will resume
255 downloads if possible.
256 --no-continue Do not resume partially downloaded files
257 (restart from beginning)
258 --no-part Do not use .part files - write directly
259 into output file
260 --no-mtime Do not use the Last-modified header to set
261 the file modification time
262 --write-description Write video description to a .description
263 file
264 --write-info-json Write video metadata to a .info.json file
265 --write-annotations Write video annotations to a
266 .annotations.xml file
267 --load-info-json FILE JSON file containing the video information
268 (created with the "--write-info-json"
269 option)
270 --cookies FILE File to read cookies from and dump cookie
271 jar in
272 --cache-dir DIR Location in the filesystem where youtube-dl
273 can store some downloaded information
274 permanently. By default
275 $XDG_CACHE_HOME/youtube-dl or
276 ~/.cache/youtube-dl . At the moment, only
277 YouTube player files (for videos with
278 obfuscated signatures) are cached, but that
279 may change.
280 --no-cache-dir Disable filesystem caching
281 --rm-cache-dir Delete all filesystem cache files
282
283
284 Thumbnail images:
285
286 --write-thumbnail Write thumbnail image to disk
287 --write-all-thumbnails Write all thumbnail image formats to disk
288 --list-thumbnails Simulate and list all available thumbnail
289 formats
290
291
292 Verbosity / Simulation Options:
293
294 -q, --quiet Activate quiet mode
295 --no-warnings Ignore warnings
296 -s, --simulate Do not download the video and do not write
297 anything to disk
298 --skip-download Do not download the video
299 -g, --get-url Simulate, quiet but print URL
300 -e, --get-title Simulate, quiet but print title
301 --get-id Simulate, quiet but print id
302 --get-thumbnail Simulate, quiet but print thumbnail URL
303 --get-description Simulate, quiet but print video description
304 --get-duration Simulate, quiet but print video length
305 --get-filename Simulate, quiet but print output filename
306 --get-format Simulate, quiet but print output format
307 -j, --dump-json Simulate, quiet but print JSON information.
308 See --output for a description of available
309 keys.
310 -J, --dump-single-json Simulate, quiet but print JSON information
311 for each command-line argument. If the URL
312 refers to a playlist, dump the whole
313 playlist information in a single line.
314 --print-json Be quiet and print the video information as
315 JSON (video is still being downloaded).
316 --newline Output progress bar as new lines
317 --no-progress Do not print progress bar
318 --console-title Display progress in console titlebar
319 -v, --verbose Print various debugging information
320 --dump-pages Print downloaded pages encoded using base64
321 to debug problems (very verbose)
322 --write-pages Write downloaded intermediary pages to
323 files in the current directory to debug
324 problems
325 --print-traffic Display sent and read HTTP traffic
326 -C, --call-home Contact the youtube-dl server for debugging
327 --no-call-home Do NOT contact the youtube-dl server for
328 debugging
329
330
331 Workarounds:
332
333 --encoding ENCODING Force the specified encoding (experimental)
334 --no-check-certificate Suppress HTTPS certificate validation
335 --prefer-insecure Use an unencrypted connection to retrieve
336 information about the video. (Currently
337 supported only for YouTube)
338 --user-agent UA Specify a custom user agent
339 --referer URL Specify a custom referer, use if the video
340 access is restricted to one domain
341 --add-header FIELD:VALUE Specify a custom HTTP header and its value,
342 separated by a colon ':'. You can use this
343 option multiple times
344 --bidi-workaround Work around terminals that lack
345 bidirectional text support. Requires bidiv
346 or fribidi executable in PATH
347 --sleep-interval SECONDS Number of seconds to sleep before each
348 download when used alone or a lower bound
349 of a range for randomized sleep before each
350 download (minimum possible number of
351 seconds to sleep) when used along with
352 --max-sleep-interval.
353 --max-sleep-interval SECONDS Upper bound of a range for randomized sleep
354 before each download (maximum possible
355 number of seconds to sleep). Must only be
356 used along with --min-sleep-interval.
357
358
359 Video Format Options:
360
361 -f, --format FORMAT Video format code, see the "FORMAT
362 SELECTION" for all the info
363 --all-formats Download all available video formats
364 --prefer-free-formats Prefer free video formats unless a specific
365 one is requested
366 -F, --list-formats List all available formats of requested
367 videos
368 --youtube-skip-dash-manifest Do not download the DASH manifests and
369 related data on YouTube videos
370 --merge-output-format FORMAT If a merge is required (e.g.
371 bestvideo+bestaudio), output to given
372 container format. One of mkv, mp4, ogg,
373 webm, flv. Ignored if no merge is required
374
375
376 Subtitle Options:
377
378 --write-sub Write subtitle file
379 --write-auto-sub Write automatically generated subtitle file
380 (YouTube only)
381 --all-subs Download all the available subtitles of the
382 video
383 --list-subs List all available subtitles for the video
384 --sub-format FORMAT Subtitle format, accepts formats
385 preference, for example: "srt" or
386 "ass/srt/best"
387 --sub-lang LANGS Languages of the subtitles to download
388 (optional) separated by commas, use --list-
389 subs for available language tags
390
391
392 Authentication Options:
393
394 -u, --username USERNAME Login with this account ID
395 -p, --password PASSWORD Account password. If this option is left
396 out, youtube-dl will ask interactively.
397 -2, --twofactor TWOFACTOR Two-factor authentication code
398 -n, --netrc Use .netrc authentication data
399 --video-password PASSWORD Video password (vimeo, smotri, youku)
400
401
402 Adobe Pass Options:
403
404 --ap-mso MSO Adobe Pass multiple-system operator (TV
405 provider) identifier, use --ap-list-mso for
406 a list of available MSOs
407 --ap-username USERNAME Multiple-system operator account login
408 --ap-password PASSWORD Multiple-system operator account password.
409 If this option is left out, youtube-dl will
410 ask interactively.
411 --ap-list-mso List all supported multiple-system
412 operators
413
414
415 Post-processing Options:
416
417 -x, --extract-audio Convert video files to audio-only files
418 (requires ffmpeg or avconv and ffprobe or
419 avprobe)
420 --audio-format FORMAT Specify audio format: "best", "aac",
421 "vorbis", "mp3", "m4a", "opus", or "wav";
422 "best" by default; No effect without -x
423 --audio-quality QUALITY Specify ffmpeg/avconv audio quality, insert
424 a value between 0 (better) and 9 (worse)
425 for VBR or a specific bitrate like 128K
426 (default 5)
427 --recode-video FORMAT Encode the video to another format if
428 necessary (currently supported:
429 mp4|flv|ogg|webm|mkv|avi)
430 --postprocessor-args ARGS Give these arguments to the postprocessor
431 -k, --keep-video Keep the video file on disk after the post-
432 processing; the video is erased by default
433 --no-post-overwrites Do not overwrite post-processed files; the
434 post-processed files are overwritten by
435 default
436 --embed-subs Embed subtitles in the video (only for mp4,
437 webm and mkv videos)
438 --embed-thumbnail Embed thumbnail in the audio as cover art
439 --add-metadata Write metadata to the video file
440 --metadata-from-title FORMAT Parse additional metadata like song title /
441 artist from the video title. The format
442 syntax is the same as --output, the parsed
443 parameters replace existing values.
444 Additional templates: %(album)s,
445 %(artist)s. Example: --metadata-from-title
446 "%(artist)s - %(title)s" matches a title
447 like "Coldplay - Paradise"
448 --xattrs Write metadata to the video file's xattrs
449 (using dublin core and xdg standards)
450 --fixup POLICY Automatically correct known faults of the
451 file. One of never (do nothing), warn (only
452 emit a warning), detect_or_warn (the
453 default; fix file if we can, warn
454 otherwise)
455 --prefer-avconv Prefer avconv over ffmpeg for running the
456 postprocessors (default)
457 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
458 postprocessors
459 --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
460 either the path to the binary or its
461 containing directory.
462 --exec CMD Execute a command on the file after
463 downloading, similar to find's -exec
464 syntax. Example: --exec 'adb push {}
465 /sdcard/Music/ && rm {}'
466 --convert-subs FORMAT Convert the subtitles to other format
467 (currently supported: srt|ass|vtt)
468
469
470
471 CONFIGURATION
472
473
474 You can configure youtube-dl by placing any supported command line
475 option to a configuration file. On Linux and OS X, the system wide
476 configuration file is located at /etc/youtube-dl.conf and the user wide
477 configuration file at ~/.config/youtube-dl/config. On Windows, the user
478 wide configuration file locations are %APPDATA%\youtube-dl\config.txt or
479 C:\Users\<user name>\youtube-dl.conf. Note that by default configuration
480 file may not exist so you may need to create it yourself.
481
482 For example, with the following configuration file youtube-dl will
483 always extract the audio, not copy the mtime, use a proxy and save all
484 videos under Movies directory in your home directory:
485
486 # Lines starting with # are comments
487
488 # Always extract audio
489 -x
490
491 # Do not copy the mtime
492 --no-mtime
493
494 # Use this proxy
495 --proxy 127.0.0.1:3128
496
497 # Save all videos under Movies directory in your home directory
498 -o ~/Movies/%(title)s.%(ext)s
499
500 Note that options in configuration file are just the same options aka
501 switches used in regular command line calls thus there MUST BE NO
502 WHITESPACE after - or --, e.g. -o or --proxy but not - o or -- proxy.
503
504 You can use --ignore-config if you want to disable the configuration
505 file for a particular youtube-dl run.
506
507 You can also use --config-location if you want to use custom
508 configuration file for a particular youtube-dl run.
509
510 Authentication with .netrc file
511
512 You may also want to configure automatic credentials storage for
513 extractors that support authentication (by providing login and password
514 with --username and --password) in order not to pass credentials as
515 command line arguments on every youtube-dl execution and prevent
516 tracking plain text passwords in the shell command history. You can
517 achieve this using a .netrc file on a per extractor basis. For that you
518 will need to create a .netrc file in your $HOME and restrict permissions
519 to read/write by only you:
520
521 touch $HOME/.netrc
522 chmod a-rwx,u+rw $HOME/.netrc
523
524 After that you can add credentials for an extractor in the following
525 format, where _extractor_ is the name of the extractor in lowercase:
526
527 machine <extractor> login <login> password <password>
528
529 For example:
530
531 machine youtube login myaccount@gmail.com password my_youtube_password
532 machine twitch login my_twitch_account_name password my_twitch_password
533
534 To activate authentication with the .netrc file you should pass --netrc
535 to youtube-dl or place it in the configuration file.
536
537 On Windows you may also need to setup the %HOME% environment variable
538 manually.
539
540
541
542 OUTPUT TEMPLATE
543
544
545 The -o option allows users to indicate a template for the output file
546 names.
547
548 TL;DR: navigate me to examples.
549
550 The basic usage is not to set any template arguments when downloading a
551 single file, like in youtube-dl -o funny_video.flv "http://some/video".
552 However, it may contain special sequences that will be replaced when
553 downloading each video. The special sequences have the format %(NAME)s.
554 To clarify, that is a percent symbol followed by a name in parentheses,
555 followed by a lowercase S. Allowed names are:
556
557 - id: Video identifier
558 - title: Video title
559 - url: Video URL
560 - ext: Video filename extension
561 - alt_title: A secondary title of the video
562 - display_id: An alternative identifier for the video
563 - uploader: Full name of the video uploader
564 - license: License name the video is licensed under
565 - creator: The creator of the video
566 - release_date: The date (YYYYMMDD) when the video was released
567 - timestamp: UNIX timestamp of the moment the video became available
568 - upload_date: Video upload date (YYYYMMDD)
569 - uploader_id: Nickname or id of the video uploader
570 - location: Physical location where the video was filmed
571 - duration: Length of the video in seconds
572 - view_count: How many users have watched the video on the platform
573 - like_count: Number of positive ratings of the video
574 - dislike_count: Number of negative ratings of the video
575 - repost_count: Number of reposts of the video
576 - average_rating: Average rating give by users, the scale used depends
577 on the webpage
578 - comment_count: Number of comments on the video
579 - age_limit: Age restriction for the video (years)
580 - format: A human-readable description of the format
581 - format_id: Format code specified by --format
582 - format_note: Additional info about the format
583 - width: Width of the video
584 - height: Height of the video
585 - resolution: Textual description of width and height
586 - tbr: Average bitrate of audio and video in KBit/s
587 - abr: Average audio bitrate in KBit/s
588 - acodec: Name of the audio codec in use
589 - asr: Audio sampling rate in Hertz
590 - vbr: Average video bitrate in KBit/s
591 - fps: Frame rate
592 - vcodec: Name of the video codec in use
593 - container: Name of the container format
594 - filesize: The number of bytes, if known in advance
595 - filesize_approx: An estimate for the number of bytes
596 - protocol: The protocol that will be used for the actual download
597 - extractor: Name of the extractor
598 - extractor_key: Key name of the extractor
599 - epoch: Unix epoch when creating the file
600 - autonumber: Five-digit number that will be increased with each
601 download, starting at zero
602 - playlist: Name or id of the playlist that contains the video
603 - playlist_index: Index of the video in the playlist padded with
604 leading zeros according to the total length of the playlist
605 - playlist_id: Playlist identifier
606 - playlist_title: Playlist title
607
608 Available for the video that belongs to some logical chapter or section:
609 - chapter: Name or title of the chapter the video belongs to -
610 chapter_number: Number of the chapter the video belongs to - chapter_id:
611 Id of the chapter the video belongs to
612
613 Available for the video that is an episode of some series or programme:
614 - series: Title of the series or programme the video episode belongs to
615 - season: Title of the season the video episode belongs to -
616 season_number: Number of the season the video episode belongs to -
617 season_id: Id of the season the video episode belongs to - episode:
618 Title of the video episode - episode_number: Number of the video episode
619 within a season - episode_id: Id of the video episode
620
621 Available for the media that is a track or a part of a music album: -
622 track: Title of the track - track_number: Number of the track within an
623 album or a disc - track_id: Id of the track - artist: Artist(s) of the
624 track - genre: Genre(s) of the track - album: Title of the album the
625 track belongs to - album_type: Type of the album - album_artist: List of
626 all artists appeared on the album - disc_number: Number of the disc or
627 other physical medium the track belongs to - release_year: Year (YYYY)
628 when the album was released
629
630 Each aforementioned sequence when referenced in an output template will
631 be replaced by the actual value corresponding to the sequence name. Note
632 that some of the sequences are not guaranteed to be present since they
633 depend on the metadata obtained by a particular extractor. Such
634 sequences will be replaced with NA.
635
636 For example for -o %(title)s-%(id)s.%(ext)s and an mp4 video with title
637 youtube-dl test video and id BaW_jenozKcj, this will result in a
638 youtube-dl test video-BaW_jenozKcj.mp4 file created in the current
639 directory.
640
641 Output templates can also contain arbitrary hierarchical path, e.g.
642 -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' which will
643 result in downloading each video in a directory corresponding to this
644 path template. Any missing directory will be automatically created for
645 you.
646
647 To use percent literals in an output template use %%. To output to
648 stdout use -o -.
649
650 The current default template is %(title)s-%(id)s.%(ext)s.
651
652 In some cases, you don't want special characters such as äø­, spaces, or
653 &, such as when transferring the downloaded filename to a Windows system
654 or the filename through an 8bit-unsafe channel. In these cases, add the
655 --restrict-filenames flag to get a shorter title:
656
657 Output template and Windows batch files
658
659 If you are using an output template inside a Windows batch file then you
660 must escape plain percent characters (%) by doubling, so that
661 -o "%(title)s-%(id)s.%(ext)s" should become
662 -o "%%(title)s-%%(id)s.%%(ext)s". However you should not touch %'s that
663 are not plain characters, e.g. environment variables for expansion
664 should stay intact: -o "C:\%HOMEPATH%\Desktop\%%(title)s.%%(ext)s".
665
666 Output template examples
667
668 Note on Windows you may need to use double quotes instead of single.
669
670 $ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc
671 youtube-dl test video ''_Ƥā†­š•.mp4 # All kinds of weird characters
672
673 $ youtube-dl --get-filename -o '%(title)s.%(ext)s' BaW_jenozKc --restrict-filenames
674 youtube-dl_test_video_.mp4 # A simple file name
675
676 # Download YouTube playlist videos in separate directory indexed by video order in a playlist
677 $ youtube-dl -o '%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re
678
679 # Download all playlists of YouTube channel/user keeping each playlist in separate directory:
680 $ youtube-dl -o '%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s' https://www.youtube.com/user/TheLinuxFoundation/playlists
681
682 # Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
683 $ youtube-dl -u user -p password -o '~/MyVideos/%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s' https://www.udemy.com/java-tutorial/
684
685 # Download entire series season keeping each series and each season in separate directory under C:/MyVideos
686 $ youtube-dl -o "C:/MyVideos/%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" http://videomore.ru/kino_v_detalayah/5_sezon/367617
687
688 # Stream the video being downloaded to stdout
689 $ youtube-dl -o - BaW_jenozKc
690
691
692
693 FORMAT SELECTION
694
695
696 By default youtube-dl tries to download the best available quality, i.e.
697 if you want the best quality you DON'T NEED to pass any special options,
698 youtube-dl will guess it for you by DEFAULT.
699
700 But sometimes you may want to download in a different format, for
701 example when you are on a slow or intermittent connection. The key
702 mechanism for achieving this is so-called _format selection_ based on
703 which you can explicitly specify desired format, select formats based on
704 some criterion or criteria, setup precedence and much more.
705
706 The general syntax for format selection is --format FORMAT or shorter
707 -f FORMAT where FORMAT is a _selector expression_, i.e. an expression
708 that describes format or formats you would like to download.
709
710 TL;DR: navigate me to examples.
711
712 The simplest case is requesting a specific format, for example with
713 -f 22 you can download the format with format code equal to 22. You can
714 get the list of available format codes for particular video using
715 --list-formats or -F. Note that these format codes are extractor
716 specific.
717
718 You can also use a file extension (currently 3gp, aac, flv, m4a, mp3,
719 mp4, ogg, wav, webm are supported) to download the best quality format
720 of a particular file extension served as a single file, e.g. -f webm
721 will download the best quality format with the webm extension served as
722 a single file.
723
724 You can also use special names to select particular edge case formats: -
725 best: Select the best quality format represented by a single file with
726 video and audio. - worst: Select the worst quality format represented by
727 a single file with video and audio. - bestvideo: Select the best quality
728 video-only format (e.g. DASH video). May not be available. - worstvideo:
729 Select the worst quality video-only format. May not be available. -
730 bestaudio: Select the best quality audio only-format. May not be
731 available. - worstaudio: Select the worst quality audio only-format. May
732 not be available.
733
734 For example, to download the worst quality video-only format you can use
735 -f worstvideo.
736
737 If you want to download multiple videos and they don't have the same
738 formats available, you can specify the order of preference using
739 slashes. Note that slash is left-associative, i.e. formats on the left
740 hand side are preferred, for example -f 22/17/18 will download format 22
741 if it's available, otherwise it will download format 17 if it's
742 available, otherwise it will download format 18 if it's available,
743 otherwise it will complain that no suitable formats are available for
744 download.
745
746 If you want to download several formats of the same video use a comma as
747 a separator, e.g. -f 22,17,18 will download all these three formats, of
748 course if they are available. Or a more sophisticated example combined
749 with the precedence feature: -f 136/137/mp4/bestvideo,140/m4a/bestaudio.
750
751 You can also filter the video formats by putting a condition in
752 brackets, as in -f "best[height=720]" (or -f "[filesize>10M]").
753
754 The following numeric meta fields can be used with comparisons <, <=, >,
755 >=, = (equals), != (not equals): - filesize: The number of bytes, if
756 known in advance - width: Width of the video, if known - height: Height
757 of the video, if known - tbr: Average bitrate of audio and video in
758 KBit/s - abr: Average audio bitrate in KBit/s - vbr: Average video
759 bitrate in KBit/s - asr: Audio sampling rate in Hertz - fps: Frame rate
760
761 Also filtering work for comparisons = (equals), != (not equals), ^=
762 (begins with), $= (ends with), *= (contains) and following string meta
763 fields: - ext: File extension - acodec: Name of the audio codec in use -
764 vcodec: Name of the video codec in use - container: Name of the
765 container format - protocol: The protocol that will be used for the
766 actual download, lower-case (http, https, rtsp, rtmp, rtmpe, mms, f4m,
767 ism, m3u8, or m3u8_native) - format_id: A short description of the
768 format
769
770 Note that none of the aforementioned meta fields are guaranteed to be
771 present since this solely depends on the metadata obtained by particular
772 extractor, i.e. the metadata offered by the video hoster.
773
774 Formats for which the value is not known are excluded unless you put a
775 question mark (?) after the operator. You can combine format filters, so
776 -f "[height <=? 720][tbr>500]" selects up to 720p videos (or videos
777 where the height is not known) with a bitrate of at least 500 KBit/s.
778
779 You can merge the video and audio of two formats into a single file
780 using -f <video-format>+<audio-format> (requires ffmpeg or avconv
781 installed), for example -f bestvideo+bestaudio will download the best
782 video-only format, the best audio-only format and mux them together with
783 ffmpeg/avconv.
784
785 Format selectors can also be grouped using parentheses, for example if
786 you want to download the best mp4 and webm formats with a height lower
787 than 480 you can use -f '(mp4,webm)[height<480]'.
788
789 Since the end of April 2015 and version 2015.04.26, youtube-dl uses
790 -f bestvideo+bestaudio/best as the default format selection (see #5447,
791 #5456). If ffmpeg or avconv are installed this results in downloading
792 bestvideo and bestaudio separately and muxing them together into a
793 single file giving the best overall quality available. Otherwise it
794 falls back to best and results in downloading the best available quality
795 served as a single file. best is also needed for videos that don't come
796 from YouTube because they don't provide the audio and video in two
797 different files. If you want to only download some DASH formats (for
798 example if you are not interested in getting videos with a resolution
799 higher than 1080p), you can add
800 -f bestvideo[height<=?1080]+bestaudio/best to your configuration file.
801 Note that if you use youtube-dl to stream to stdout (and most likely to
802 pipe it to your media player then), i.e. you explicitly specify output
803 template as -o -, youtube-dl still uses -f best format selection in
804 order to start content delivery immediately to your player and not to
805 wait until bestvideo and bestaudio are downloaded and muxed.
806
807 If you want to preserve the old format selection behavior (prior to
808 youtube-dl 2015.04.26), i.e. you want to download the best available
809 quality media served as a single file, you should explicitly specify
810 your choice with -f best. You may want to add it to the configuration
811 file in order not to type it every time you run youtube-dl.
812
813 Format selection examples
814
815 Note on Windows you may need to use double quotes instead of single.
816
817 # Download best mp4 format available or any other best if no mp4 available
818 $ youtube-dl -f 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best'
819
820 # Download best format available but not better that 480p
821 $ youtube-dl -f 'bestvideo[height<=480]+bestaudio/best[height<=480]'
822
823 # Download best video only format but no bigger than 50 MB
824 $ youtube-dl -f 'best[filesize<50M]'
825
826 # Download best format available via direct link over HTTP/HTTPS protocol
827 $ youtube-dl -f '(bestvideo+bestaudio/best)[protocol^=http]'
828
829 # Download the best video format and the best audio format without merging them
830 $ youtube-dl -f 'bestvideo,bestaudio' -o '%(title)s.f%(format_id)s.%(ext)s'
831
832 Note that in the last example, an output template is recommended as
833 bestvideo and bestaudio may have the same file name.
834
835
836
837 VIDEO SELECTION
838
839
840 Videos can be filtered by their upload date using the options --date,
841 --datebefore or --dateafter. They accept dates in two formats:
842
843 - Absolute dates: Dates in the format YYYYMMDD.
844 - Relative dates: Dates in the format
845 (now|today)[+-][0-9](day|week|month|year)(s)?
846
847 Examples:
848
849 # Download only the videos uploaded in the last 6 months
850 $ youtube-dl --dateafter now-6months
851
852 # Download only the videos uploaded on January 1, 1970
853 $ youtube-dl --date 19700101
854
855 $ # Download only the videos uploaded in the 200x decade
856 $ youtube-dl --dateafter 20000101 --datebefore 20091231
857
858
859
860 FAQ
861
862
863 How do I update youtube-dl?
864
865 If you've followed our manual installation instructions, you can simply
866 run youtube-dl -U (or, on Linux, sudo youtube-dl -U).
867
868 If you have used pip, a simple sudo pip install -U youtube-dl is
869 sufficient to update.
870
871 If you have installed youtube-dl using a package manager like _apt-get_
872 or _yum_, use the standard system update mechanism to update. Note that
873 distribution packages are often outdated. As a rule of thumb, youtube-dl
874 releases at least once a month, and often weekly or even daily. Simply
875 go to http://yt-dl.org/ to find out the current version. Unfortunately,
876 there is nothing we youtube-dl developers can do if your distribution
877 serves a really outdated version. You can (and should) complain to your
878 distribution in their bugtracker or support forum.
879
880 As a last resort, you can also uninstall the version installed by your
881 package manager and follow our manual installation instructions. For
882 that, remove the distribution's package, with a line like
883
884 sudo apt-get remove -y youtube-dl
885
886 Afterwards, simply follow our manual installation instructions:
887
888 sudo wget https://yt-dl.org/latest/youtube-dl -O /usr/local/bin/youtube-dl
889 sudo chmod a+x /usr/local/bin/youtube-dl
890 hash -r
891
892 Again, from then on you'll be able to update with sudo youtube-dl -U.
893
894 youtube-dl is extremely slow to start on Windows
895
896 Add a file exclusion for youtube-dl.exe in Windows Defender settings.
897
898 I'm getting an error Unable to extract OpenGraph title on YouTube playlists
899
900 YouTube changed their playlist format in March 2014 and later on, so
901 you'll need at least youtube-dl 2014.07.25 to download all YouTube
902 videos.
903
904 If you have installed youtube-dl with a package manager, pip, setup.py
905 or a tarball, please use that to update. Note that Ubuntu packages do
906 not seem to get updated anymore. Since we are not affiliated with
907 Ubuntu, there is little we can do. Feel free to report bugs to the
908 Ubuntu packaging people - all they have to do is update the package to a
909 somewhat recent version. See above for a way to update.
910
911 I'm getting an error when trying to use output template: error: using output template conflicts with using title, video ID or auto number
912
913 Make sure you are not using -o with any of these options -t, --title,
914 --id, -A or --auto-number set in command line or in a configuration
915 file. Remove the latter if any.
916
917 Do I always have to pass -citw?
918
919 By default, youtube-dl intends to have the best options (incidentally,
920 if you have a convincing case that these should be different, please
921 file an issue where you explain that). Therefore, it is unnecessary and
922 sometimes harmful to copy long option strings from webpages. In
923 particular, the only option out of -citw that is regularly useful is -i.
924
925 Can you please put the -b option back?
926
927 Most people asking this question are not aware that youtube-dl now
928 defaults to downloading the highest available quality as reported by
929 YouTube, which will be 1080p or 720p in some cases, so you no longer
930 need the -b option. For some specific videos, maybe YouTube does not
931 report them to be available in a specific high quality format you're
932 interested in. In that case, simply request it with the -f option and
933 youtube-dl will try to download it.
934
935 I get HTTP error 402 when trying to download a video. What's this?
936
937 Apparently YouTube requires you to pass a CAPTCHA test if you download
938 too much. We're considering to provide a way to let you solve the
939 CAPTCHA, but at the moment, your best course of action is pointing a web
940 browser to the youtube URL, solving the CAPTCHA, and restart youtube-dl.
941
942 Do I need any other programs?
943
944 youtube-dl works fine on its own on most sites. However, if you want to
945 convert video/audio, you'll need avconv or ffmpeg. On some sites - most
946 notably YouTube - videos can be retrieved in a higher quality format
947 without sound. youtube-dl will detect whether avconv/ffmpeg is present
948 and automatically pick the best option.
949
950 Videos or video formats streamed via RTMP protocol can only be
951 downloaded when rtmpdump is installed. Downloading MMS and RTSP videos
952 requires either mplayer or mpv to be installed.
953
954 I have downloaded a video but how can I play it?
955
956 Once the video is fully downloaded, use any video player, such as mpv,
957 vlc or mplayer.
958
959 I extracted a video URL with -g, but it does not play on another machine / in my web browser.
960
961 It depends a lot on the service. In many cases, requests for the video
962 (to download/play it) must come from the same IP address and with the
963 same cookies and/or HTTP headers. Use the --cookies option to write the
964 required cookies into a file, and advise your downloader to read cookies
965 from that file. Some sites also require a common user agent to be used,
966 use --dump-user-agent to see the one in use by youtube-dl. You can also
967 get necessary cookies and HTTP headers from JSON output obtained with
968 --dump-json.
969
970 It may be beneficial to use IPv6; in some cases, the restrictions are
971 only applied to IPv4. Some services (sometimes only for a subset of
972 videos) do not restrict the video URL by IP address, cookie, or
973 user-agent, but these are the exception rather than the rule.
974
975 Please bear in mind that some URL protocols are NOT supported by
976 browsers out of the box, including RTMP. If you are using -g, your own
977 downloader must support these as well.
978
979 If you want to play the video on a machine that is not running
980 youtube-dl, you can relay the video content from the machine that runs
981 youtube-dl. You can use -o - to let youtube-dl stream a video to stdout,
982 or simply allow the player to download the files written by youtube-dl
983 in turn.
984
985 ERROR: no fmt_url_map or conn information found in video info
986
987 YouTube has switched to a new video info format in July 2011 which is
988 not supported by old versions of youtube-dl. See above for how to update
989 youtube-dl.
990
991 ERROR: unable to download video
992
993 YouTube requires an additional signature since September 2012 which is
994 not supported by old versions of youtube-dl. See above for how to update
995 youtube-dl.
996
997 Video URL contains an ampersand and I'm getting some strange output [1] 2839 or 'v' is not recognized as an internal or external command
998
999 That's actually the output from your shell. Since ampersand is one of
1000 the special shell characters it's interpreted by the shell preventing
1001 you from passing the whole URL to youtube-dl. To disable your shell from
1002 interpreting the ampersands (or any other special characters) you have
1003 to either put the whole URL in quotes or escape them with a backslash
1004 (which approach will work depends on your shell).
1005
1006 For example if your URL is
1007 https://www.youtube.com/watch?t=4&v=BaW_jenozKc you should end up with
1008 following command:
1009
1010 youtube-dl 'https://www.youtube.com/watch?t=4&v=BaW_jenozKc'
1011
1012 or
1013
1014 youtube-dl https://www.youtube.com/watch?t=4\&v=BaW_jenozKc
1015
1016 For Windows you have to use the double quotes:
1017
1018 youtube-dl "https://www.youtube.com/watch?t=4&v=BaW_jenozKc"
1019
1020 ExtractorError: Could not find JS function u'OF'
1021
1022 In February 2015, the new YouTube player contained a character sequence
1023 in a string that was misinterpreted by old versions of youtube-dl. See
1024 above for how to update youtube-dl.
1025
1026 HTTP Error 429: Too Many Requests or 402: Payment Required
1027
1028 These two error codes indicate that the service is blocking your IP
1029 address because of overuse. Contact the service and ask them to unblock
1030 your IP address, or - if you have acquired a whitelisted IP address
1031 already - use the --proxy or --source-address options to select another
1032 IP address.
1033
1034 SyntaxError: Non-ASCII character
1035
1036 The error
1037
1038 File "youtube-dl", line 2
1039 SyntaxError: Non-ASCII character '\x93' ...
1040
1041 means you're using an outdated version of Python. Please update to
1042 Python 2.6 or 2.7.
1043
1044 What is this binary file? Where has the code gone?
1045
1046 Since June 2012 (#342) youtube-dl is packed as an executable zipfile,
1047 simply unzip it (might need renaming to youtube-dl.zip first on some
1048 systems) or clone the git repository, as laid out above. If you modify
1049 the code, you can run it by executing the __main__.py file. To recompile
1050 the executable, run make youtube-dl.
1051
1052 The exe throws an error due to missing MSVCR100.dll
1053
1054 To run the exe you need to install first the Microsoft Visual C++ 2010
1055 Redistributable Package (x86).
1056
1057 On Windows, how should I set up ffmpeg and youtube-dl? Where should I put the exe files?
1058
1059 If you put youtube-dl and ffmpeg in the same directory that you're
1060 running the command from, it will work, but that's rather cumbersome.
1061
1062 To make a different directory work - either for ffmpeg, or for
1063 youtube-dl, or for both - simply create the directory (say, C:\bin, or
1064 C:\Users\<User name>\bin), put all the executables directly in there,
1065 and then set your PATH environment variable to include that directory.
1066
1067 From then on, after restarting your shell, you will be able to access
1068 both youtube-dl and ffmpeg (and youtube-dl will be able to find ffmpeg)
1069 by simply typing youtube-dl or ffmpeg, no matter what directory you're
1070 in.
1071
1072 How do I put downloads into a specific folder?
1073
1074 Use the -o to specify an output template, for example
1075 -o "/home/user/videos/%(title)s-%(id)s.%(ext)s". If you want this for
1076 all of your downloads, put the option into your configuration file.
1077
1078 How do I download a video starting with a -?
1079
1080 Either prepend http://www.youtube.com/watch?v= or separate the ID from
1081 the options with --:
1082
1083 youtube-dl -- -wNyEUrxzFU
1084 youtube-dl "http://www.youtube.com/watch?v=-wNyEUrxzFU"
1085
1086 How do I pass cookies to youtube-dl?
1087
1088 Use the --cookies option, for example
1089 --cookies /path/to/cookies/file.txt.
1090
1091 In order to extract cookies from browser use any conforming browser
1092 extension for exporting cookies. For example, cookies.txt (for Chrome)
1093 or Export Cookies (for Firefox).
1094
1095 Note that the cookies file must be in Mozilla/Netscape format and the
1096 first line of the cookies file must be either # HTTP Cookie File or
1097 # Netscape HTTP Cookie File. Make sure you have correct newline format
1098 in the cookies file and convert newlines if necessary to correspond with
1099 your OS, namely CRLF (\r\n) for Windows and LF (\n) for Unix and
1100 Unix-like systems (Linux, Mac OS, etc.). HTTP Error 400: Bad Request
1101 when using --cookies is a good sign of invalid newline format.
1102
1103 Passing cookies to youtube-dl is a good way to workaround login when a
1104 particular extractor does not implement it explicitly. Another use case
1105 is working around CAPTCHA some websites require you to solve in
1106 particular cases in order to get access (e.g. YouTube, CloudFlare).
1107
1108 How do I stream directly to media player?
1109
1110 You will first need to tell youtube-dl to stream media to stdout with
1111 -o -, and also tell your media player to read from stdin (it must be
1112 capable of this for streaming) and then pipe former to latter. For
1113 example, streaming to vlc can be achieved with:
1114
1115 youtube-dl -o - "http://www.youtube.com/watch?v=BaW_jenozKcj" | vlc -
1116
1117 How do I download only new videos from a playlist?
1118
1119 Use download-archive feature. With this feature you should initially
1120 download the complete playlist with
1121 --download-archive /path/to/download/archive/file.txt that will record
1122 identifiers of all the videos in a special file. Each subsequent run
1123 with the same --download-archive will download only new videos and skip
1124 all videos that have been downloaded before. Note that only successful
1125 downloads are recorded in the file.
1126
1127 For example, at first,
1128
1129 youtube-dl --download-archive archive.txt "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1130
1131 will download the complete PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re playlist
1132 and create a file archive.txt. Each subsequent run will only download
1133 new videos if any:
1134
1135 youtube-dl --download-archive archive.txt "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"
1136
1137 Should I add --hls-prefer-native into my config?
1138
1139 When youtube-dl detects an HLS video, it can download it either with the
1140 built-in downloader or ffmpeg. Since many HLS streams are slightly
1141 invalid and ffmpeg/youtube-dl each handle some invalid cases better than
1142 the other, there is an option to switch the downloader if needed.
1143
1144 When youtube-dl knows that one particular downloader works better for a
1145 given website, that downloader will be picked. Otherwise, youtube-dl
1146 will pick the best downloader for general compatibility, which at the
1147 moment happens to be ffmpeg. This choice may change in future versions
1148 of youtube-dl, with improvements of the built-in downloader and/or
1149 ffmpeg.
1150
1151 In particular, the generic extractor (used when your website is not in
1152 the list of supported sites by youtube-dl cannot mandate one specific
1153 downloader.
1154
1155 If you put either --hls-prefer-native or --hls-prefer-ffmpeg into your
1156 configuration, a different subset of videos will fail to download
1157 correctly. Instead, it is much better to file an issue or a pull request
1158 which details why the native or the ffmpeg HLS downloader is a better
1159 choice for your use case.
1160
1161 Can you add support for this anime video site, or site which shows current movies for free?
1162
1163 As a matter of policy (as well as legality), youtube-dl does not include
1164 support for services that specialize in infringing copyright. As a rule
1165 of thumb, if you cannot easily find a video that the service is quite
1166 obviously allowed to distribute (i.e. that has been uploaded by the
1167 creator, the creator's distributor, or is published under a free
1168 license), the service is probably unfit for inclusion to youtube-dl.
1169
1170 A note on the service that they don't host the infringing content, but
1171 just link to those who do, is evidence that the service should NOT be
1172 included into youtube-dl. The same goes for any DMCA note when the whole
1173 front page of the service is filled with videos they are not allowed to
1174 distribute. A "fair use" note is equally unconvincing if the service
1175 shows copyright-protected videos in full without authorization.
1176
1177 Support requests for services that DO purchase the rights to distribute
1178 their content are perfectly fine though. If in doubt, you can simply
1179 include a source that mentions the legitimate purchase of content.
1180
1181 How can I speed up work on my issue?
1182
1183 (Also known as: Help, my important issue not being solved!) The
1184 youtube-dl core developer team is quite small. While we do our best to
1185 solve as many issues as possible, sometimes that can take quite a while.
1186 To speed up your issue, here's what you can do:
1187
1188 First of all, please do report the issue at our issue tracker. That
1189 allows us to coordinate all efforts by users and developers, and serves
1190 as a unified point. Unfortunately, the youtube-dl project has grown too
1191 large to use personal email as an effective communication channel.
1192
1193 Please read the bug reporting instructions below. A lot of bugs lack all
1194 the necessary information. If you can, offer proxy, VPN, or shell access
1195 to the youtube-dl developers. If you are able to, test the issue from
1196 multiple computers in multiple countries to exclude local censorship or
1197 misconfiguration issues.
1198
1199 If nobody is interested in solving your issue, you are welcome to take
1200 matters into your own hands and submit a pull request (or coerce/pay
1201 somebody else to do so).
1202
1203 Feel free to bump the issue from time to time by writing a small comment
1204 ("Issue is still present in youtube-dl version ...from France, but fixed
1205 from Belgium"), but please not more than once a month. Please do not
1206 declare your issue as important or urgent.
1207
1208 How can I detect whether a given URL is supported by youtube-dl?
1209
1210 For one, have a look at the list of supported sites. Note that it can
1211 sometimes happen that the site changes its URL scheme (say, from
1212 http://example.com/video/1234567 to http://example.com/v/1234567 ) and
1213 youtube-dl reports an URL of a service in that list as unsupported. In
1214 that case, simply report a bug.
1215
1216 It is _not_ possible to detect whether a URL is supported or not. That's
1217 because youtube-dl contains a generic extractor which matches ALL URLs.
1218 You may be tempted to disable, exclude, or remove the generic extractor,
1219 but the generic extractor not only allows users to extract videos from
1220 lots of websites that embed a video from another service, but may also
1221 be used to extract video from a service that it's hosting itself.
1222 Therefore, we neither recommend nor support disabling, excluding, or
1223 removing the generic extractor.
1224
1225 If you want to find out whether a given URL is supported, simply call
1226 youtube-dl with it. If you get no videos back, chances are the URL is
1227 either not referring to a video or unsupported. You can find out which
1228 by examining the output (if you run youtube-dl on the console) or
1229 catching an UnsupportedError exception if you run it from a Python
1230 program.
1231
1232
1233
1234 WHY DO I NEED TO GO THROUGH THAT MUCH RED TAPE WHEN FILING BUGS?
1235
1236
1237 Before we had the issue template, despite our extensive bug reporting
1238 instructions, about 80% of the issue reports we got were useless, for
1239 instance because people used ancient versions hundreds of releases old,
1240 because of simple syntactic errors (not in youtube-dl but in general
1241 shell usage), because the problem was already reported multiple times
1242 before, because people did not actually read an error message, even if
1243 it said "please install ffmpeg", because people did not mention the URL
1244 they were trying to download and many more simple, easy-to-avoid
1245 problems, many of whom were totally unrelated to youtube-dl.
1246
1247 youtube-dl is an open-source project manned by too few volunteers, so
1248 we'd rather spend time fixing bugs where we are certain none of those
1249 simple problems apply, and where we can be reasonably confident to be
1250 able to reproduce the issue without asking the reporter repeatedly. As
1251 such, the output of youtube-dl -v YOUR_URL_HERE is really all that's
1252 required to file an issue. The issue template also guides you through
1253 some basic steps you can do, such as checking that your version of
1254 youtube-dl is current.
1255
1256
1257
1258 DEVELOPER INSTRUCTIONS
1259
1260
1261 Most users do not need to build youtube-dl and can download the builds
1262 or get them from their distribution.
1263
1264 To run youtube-dl as a developer, you don't need to build anything
1265 either. Simply execute
1266
1267 python -m youtube_dl
1268
1269 To run the test, simply invoke your favorite test runner, or execute a
1270 test file directly; any of the following work:
1271
1272 python -m unittest discover
1273 python test/test_download.py
1274 nosetests
1275
1276 If you want to create a build of youtube-dl yourself, you'll need
1277
1278 - python
1279 - make (only GNU make is supported)
1280 - pandoc
1281 - zip
1282 - nosetests
1283
1284 Adding support for a new site
1285
1286 If you want to add support for a new site, first of all MAKE SURE this
1287 site is NOT DEDICATED TO COPYRIGHT INFRINGEMENT. youtube-dl does NOT
1288 SUPPORT such sites thus pull requests adding support for them WILL BE
1289 REJECTED.
1290
1291 After you have ensured this site is distributing its content legally,
1292 you can follow this quick list (assuming your service is called
1293 yourextractor):
1294
1295 1. Fork this repository
1296 2. Check out the source code with:
1297
1298 git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
1299
1300 3. Start a new git branch with
1301
1302 cd youtube-dl
1303 git checkout -b yourextractor
1304
1305 4. Start with this simple template and save it to
1306 youtube_dl/extractor/yourextractor.py:
1307
1308 # coding: utf-8
1309 from __future__ import unicode_literals
1310
1311 from .common import InfoExtractor
1312
1313
1314 class YourExtractorIE(InfoExtractor):
1315 _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
1316 _TEST = {
1317 'url': 'http://yourextractor.com/watch/42',
1318 'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
1319 'info_dict': {
1320 'id': '42',
1321 'ext': 'mp4',
1322 'title': 'Video title goes here',
1323 'thumbnail': r're:^https?://.*\.jpg$',
1324 # TODO more properties, either as:
1325 # * A value
1326 # * MD5 checksum; start the string with md5:
1327 # * A regular expression; start the string with re:
1328 # * Any Python type (for example int or float)
1329 }
1330 }
1331
1332 def _real_extract(self, url):
1333 video_id = self._match_id(url)
1334 webpage = self._download_webpage(url, video_id)
1335
1336 # TODO more code goes here, for example ...
1337 title = self._html_search_regex(r'<h1>(.+?)</h1>', webpage, 'title')
1338
1339 return {
1340 'id': video_id,
1341 'title': title,
1342 'description': self._og_search_description(webpage),
1343 'uploader': self._search_regex(r'<div[^>]+id="uploader"[^>]*>([^<]+)<', webpage, 'uploader', fatal=False),
1344 # TODO more properties (see youtube_dl/extractor/common.py)
1345 }
1346
1347 5. Add an import in youtube_dl/extractor/extractors.py.
1348 6. Run python test/test_download.py TestDownload.test_YourExtractor.
1349 This _should fail_ at first, but you can continually re-run it until
1350 you're done. If you decide to add more than one test, then rename
1351 _TEST to _TESTS and make it into a list of dictionaries. The tests
1352 will then be named TestDownload.test_YourExtractor,
1353 TestDownload.test_YourExtractor_1,
1354 TestDownload.test_YourExtractor_2, etc.
1355 7. Have a look at youtube_dl/extractor/common.py for possible helper
1356 methods and a detailed description of what your extractor should and
1357 may return. Add tests and code for as many as you want.
1358 8. Make sure your code follows youtube-dl coding conventions and check
1359 the code with flake8. Also make sure your code works under all
1360 Python versions claimed supported by youtube-dl, namely 2.6, 2.7,
1361 and 3.2+.
1362 9. When the tests pass, add the new files and commit them and push the
1363 result, like this:
1364
1365 $ git add youtube_dl/extractor/extractors.py
1366 $ git add youtube_dl/extractor/yourextractor.py
1367 $ git commit -m '[yourextractor] Add new extractor'
1368 $ git push origin yourextractor
1369
1370 10. Finally, create a pull request. We'll then review and merge it.
1371
1372 In any case, thank you very much for your contributions!
1373
1374
1375 youtube-dl coding conventions
1376
1377 This section introduces a guide lines for writing idiomatic, robust and
1378 future-proof extractor code.
1379
1380 Extractors are very fragile by nature since they depend on the layout of
1381 the source data provided by 3rd party media hosters out of your control
1382 and this layout tends to change. As an extractor implementer your task
1383 is not only to write code that will extract media links and metadata
1384 correctly but also to minimize dependency on the source's layout and
1385 even to make the code foresee potential future changes and be ready for
1386 that. This is important because it will allow the extractor not to break
1387 on minor layout changes thus keeping old youtube-dl versions working.
1388 Even though this breakage issue is easily fixed by emitting a new
1389 version of youtube-dl with a fix incorporated, all the previous versions
1390 become broken in all repositories and distros' packages that may not be
1391 so prompt in fetching the update from us. Needless to say, some non
1392 rolling release distros may never receive an update at all.
1393
1394 Mandatory and optional metafields
1395
1396 For extraction to work youtube-dl relies on metadata your extractor
1397 extracts and provides to youtube-dl expressed by an information
1398 dictionary or simply _info dict_. Only the following meta fields in the
1399 _info dict_ are considered mandatory for a successful extraction process
1400 by youtube-dl:
1401
1402 - id (media identifier)
1403 - title (media title)
1404 - url (media download URL) or formats
1405
1406 In fact only the last option is technically mandatory (i.e. if you can't
1407 figure out the download location of the media the extraction does not
1408 make any sense). But by convention youtube-dl also treats id and title
1409 as mandatory. Thus the aforementioned metafields are the critical data
1410 that the extraction does not make any sense without and if any of them
1411 fail to be extracted then the extractor is considered completely broken.
1412
1413 Any field apart from the aforementioned ones are considered OPTIONAL.
1414 That means that extraction should be TOLERANT to situations when sources
1415 for these fields can potentially be unavailable (even if they are always
1416 available at the moment) and FUTURE-PROOF in order not to break the
1417 extraction of general purpose mandatory fields.
1418
1419 Example
1420
1421 Say you have some source dictionary meta that you've fetched as JSON
1422 with HTTP request and it has a key summary:
1423
1424 meta = self._download_json(url, video_id)
1425
1426 Assume at this point meta's layout is:
1427
1428 {
1429 ...
1430 "summary": "some fancy summary text",
1431 ...
1432 }
1433
1434 Assume you want to extract summary and put it into the resulting info
1435 dict as description. Since description is an optional meta field you
1436 should be ready that this key may be missing from the meta dict, so that
1437 you should extract it like:
1438
1439 description = meta.get('summary') # correct
1440
1441 and not like:
1442
1443 description = meta['summary'] # incorrect
1444
1445 The latter will break extraction process with KeyError if summary
1446 disappears from meta at some later time but with the former approach
1447 extraction will just go ahead with description set to None which is
1448 perfectly fine (remember None is equivalent to the absence of data).
1449
1450 Similarly, you should pass fatal=False when extracting optional data
1451 from a webpage with _search_regex, _html_search_regex or similar
1452 methods, for instance:
1453
1454 description = self._search_regex(
1455 r'<span[^>]+id="title"[^>]*>([^<]+)<',
1456 webpage, 'description', fatal=False)
1457
1458 With fatal set to False if _search_regex fails to extract description it
1459 will emit a warning and continue extraction.
1460
1461 You can also pass default=<some fallback value>, for example:
1462
1463 description = self._search_regex(
1464 r'<span[^>]+id="title"[^>]*>([^<]+)<',
1465 webpage, 'description', default=None)
1466
1467 On failure this code will silently continue the extraction with
1468 description set to None. That is useful for metafields that may or may
1469 not be present.
1470
1471 Provide fallbacks
1472
1473 When extracting metadata try to do so from multiple sources. For example
1474 if title is present in several places, try extracting from at least some
1475 of them. This makes it more future-proof in case some of the sources
1476 become unavailable.
1477
1478 Example
1479
1480 Say meta from the previous example has a title and you are about to
1481 extract it. Since title is a mandatory meta field you should end up with
1482 something like:
1483
1484 title = meta['title']
1485
1486 If title disappears from meta in future due to some changes on the
1487 hoster's side the extraction would fail since title is mandatory. That's
1488 expected.
1489
1490 Assume that you have some another source you can extract title from, for
1491 example og:title HTML meta of a webpage. In this case you can provide a
1492 fallback scenario:
1493
1494 title = meta.get('title') or self._og_search_title(webpage)
1495
1496 This code will try to extract from meta first and if it fails it will
1497 try extracting og:title from a webpage.
1498
1499 Make regular expressions flexible
1500
1501 When using regular expressions try to write them fuzzy and flexible.
1502
1503 Example
1504
1505 Say you need to extract title from the following HTML code:
1506
1507 <span style="position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;" class="title">some fancy title</span>
1508
1509 The code for that task should look similar to:
1510
1511 title = self._search_regex(
1512 r'<span[^>]+class="title"[^>]*>([^<]+)', webpage, 'title')
1513
1514 Or even better:
1515
1516 title = self._search_regex(
1517 r'<span[^>]+class=(["\'])title\1[^>]*>(?P<title>[^<]+)',
1518 webpage, 'title', group='title')
1519
1520 Note how you tolerate potential changes in the style attribute's value
1521 or switch from using double quotes to single for class attribute:
1522
1523 The code definitely should not look like:
1524
1525 title = self._search_regex(
1526 r'<span style="position: absolute; left: 910px; width: 90px; float: right; z-index: 9999;" class="title">(.*?)</span>',
1527 webpage, 'title', group='title')
1528
1529 Use safe conversion functions
1530
1531 Wrap all extracted numeric data into safe functions from utils:
1532 int_or_none, float_or_none. Use them for string to number conversions as
1533 well.
1534
1535
1536
1537 EMBEDDING YOUTUBE-DL
1538
1539
1540 youtube-dl makes the best effort to be a good command-line program, and
1541 thus should be callable from any programming language. If you encounter
1542 any problems parsing its output, feel free to create a report.
1543
1544 From a Python program, you can embed youtube-dl in a more powerful
1545 fashion, like this:
1546
1547 from __future__ import unicode_literals
1548 import youtube_dl
1549
1550 ydl_opts = {}
1551 with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1552 ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc'])
1553
1554 Most likely, you'll want to use various options. For a list of options
1555 available, have a look at youtube_dl/YoutubeDL.py. For a start, if you
1556 want to intercept youtube-dl's output, set a logger object.
1557
1558 Here's a more complete example of a program that outputs only errors
1559 (and a short message after the download is finished), and
1560 downloads/converts the video to an mp3 file:
1561
1562 from __future__ import unicode_literals
1563 import youtube_dl
1564
1565
1566 class MyLogger(object):
1567 def debug(self, msg):
1568 pass
1569
1570 def warning(self, msg):
1571 pass
1572
1573 def error(self, msg):
1574 print(msg)
1575
1576
1577 def my_hook(d):
1578 if d['status'] == 'finished':
1579 print('Done downloading, now converting ...')
1580
1581
1582 ydl_opts = {
1583 'format': 'bestaudio/best',
1584 'postprocessors': [{
1585 'key': 'FFmpegExtractAudio',
1586 'preferredcodec': 'mp3',
1587 'preferredquality': '192',
1588 }],
1589 'logger': MyLogger(),
1590 'progress_hooks': [my_hook],
1591 }
1592 with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1593 ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc'])
1594
1595
1596
1597 BUGS
1598
1599
1600 Bugs and suggestions should be reported at:
1601 https://github.com/rg3/youtube-dl/issues. Unless you were prompted to or
1602 there is another pertinent reason (e.g. GitHub fails to accept the bug
1603 report), please do not send bug reports via personal email. For
1604 discussions, join us in the IRC channel #youtube-dl on freenode
1605 (webchat).
1606
1607 PLEASE INCLUDE THE FULL OUTPUT OF YOUTUBE-DL WHEN RUN WITH -v, i.e. ADD
1608 -v flag to YOUR COMMAND LINE, copy the WHOLE output and post it in the
1609 issue body wrapped in ``` for better formatting. It should look similar
1610 to this:
1611
1612 $ youtube-dl -v <your command line>
1613 [debug] System config: []
1614 [debug] User config: []
1615 [debug] Command-line args: [u'-v', u'http://www.youtube.com/watch?v=BaW_jenozKcj']
1616 [debug] Encodings: locale cp1251, fs mbcs, out cp866, pref cp1251
1617 [debug] youtube-dl version 2015.12.06
1618 [debug] Git HEAD: 135392e
1619 [debug] Python version 2.6.6 - Windows-2003Server-5.2.3790-SP2
1620 [debug] exe versions: ffmpeg N-75573-g1d0487f, ffprobe N-75573-g1d0487f, rtmpdump 2.4
1621 [debug] Proxy map: {}
1622 ...
1623
1624 DO NOT POST SCREENSHOTS OF VERBOSE LOGS; ONLY PLAIN TEXT IS ACCEPTABLE.
1625
1626 The output (including the first lines) contains important debugging
1627 information. Issues without the full output are often not reproducible
1628 and therefore do not get solved in short order, if ever.
1629
1630 Please re-read your issue once again to avoid a couple of common
1631 mistakes (you can and should use this as a checklist):
1632
1633 Is the description of the issue itself sufficient?
1634
1635 We often get issue reports that we cannot really decipher. While in most
1636 cases we eventually get the required information after asking back
1637 multiple times, this poses an unnecessary drain on our resources. Many
1638 contributors, including myself, are also not native speakers, so we may
1639 misread some parts.
1640
1641 So please elaborate on what feature you are requesting, or what bug you
1642 want to be fixed. Make sure that it's obvious
1643
1644 - What the problem is
1645 - How it could be fixed
1646 - How your proposed solution would look like
1647
1648 If your report is shorter than two lines, it is almost certainly missing
1649 some of these, which makes it hard for us to respond to it. We're often
1650 too polite to close the issue outright, but the missing info makes
1651 misinterpretation likely. As a committer myself, I often get frustrated
1652 by these issues, since the only possible way for me to move forward on
1653 them is to ask for clarification over and over.
1654
1655 For bug reports, this means that your report should contain the
1656 _complete_ output of youtube-dl when called with the -v flag. The error
1657 message you get for (most) bugs even says so, but you would not believe
1658 how many of our bug reports do not contain this information.
1659
1660 If your server has multiple IPs or you suspect censorship, adding
1661 --call-home may be a good idea to get more diagnostics. If the error is
1662 ERROR: Unable to extract ... and you cannot reproduce it from multiple
1663 countries, add --dump-pages (warning: this will yield a rather large
1664 output, redirect it to the file log.txt by adding >log.txt 2>&1 to your
1665 command-line) or upload the .dump files you get when you add
1666 --write-pages somewhere.
1667
1668 SITE SUPPORT REQUESTS MUST CONTAIN AN EXAMPLE URL. An example URL is a
1669 URL you might want to download, like
1670 http://www.youtube.com/watch?v=BaW_jenozKc. There should be an obvious
1671 video present. Except under very special circumstances, the main page of
1672 a video service (e.g. http://www.youtube.com/) is _not_ an example URL.
1673
1674 Are you using the latest version?
1675
1676 Before reporting any issue, type youtube-dl -U. This should report that
1677 you're up-to-date. About 20% of the reports we receive are already
1678 fixed, but people are using outdated versions. This goes for feature
1679 requests as well.
1680
1681 Is the issue already documented?
1682
1683 Make sure that someone has not already opened the issue you're trying to
1684 open. Search at the top of the window or browse the GitHub Issues of
1685 this repository. If there is an issue, feel free to write something
1686 along the lines of "This affects me as well, with version 2015.01.01.
1687 Here is some more information on the issue: ...". While some issues may
1688 be old, a new post into them often spurs rapid activity.
1689
1690 Why are existing options not enough?
1691
1692 Before requesting a new feature, please have a quick peek at the list of
1693 supported options. Many feature requests are for features that actually
1694 exist already! Please, absolutely do show off your work in the issue
1695 report and detail how the existing similar options do _not_ solve your
1696 problem.
1697
1698 Is there enough context in your bug report?
1699
1700 People want to solve problems, and often think they do us a favor by
1701 breaking down their larger problems (e.g. wanting to skip already
1702 downloaded files) to a specific request (e.g. requesting us to look
1703 whether the file exists before downloading the info page). However, what
1704 often happens is that they break down the problem into two steps: One
1705 simple, and one impossible (or extremely complicated one).
1706
1707 We are then presented with a very complicated request when the original
1708 problem could be solved far easier, e.g. by recording the downloaded
1709 video IDs in a separate file. To avoid this, you must include the
1710 greater context where it is non-obvious. In particular, every feature
1711 request that does not consist of adding support for a new site should
1712 contain a use case scenario that explains in what situation the missing
1713 feature would be useful.
1714
1715 Does the issue involve one problem, and one problem only?
1716
1717 Some of our users seem to think there is a limit of issues they can or
1718 should open. There is no limit of issues they can or should open. While
1719 it may seem appealing to be able to dump all your issues into one
1720 ticket, that means that someone who solves one of your issues cannot
1721 mark the issue as closed. Typically, reporting a bunch of issues leads
1722 to the ticket lingering since nobody wants to attack that behemoth,
1723 until someone mercifully splits the issue into multiple ones.
1724
1725 In particular, every site support request issue should only pertain to
1726 services at one site (generally under a common domain, but always using
1727 the same backend technology). Do not request support for vimeo user
1728 videos, White house podcasts, and Google Plus pages in the same issue.
1729 Also, make sure that you don't post bug reports alongside feature
1730 requests. As a rule of thumb, a feature request does not include outputs
1731 of youtube-dl that are not immediately related to the feature at hand.
1732 Do not post reports of a network error alongside the request for a new
1733 video service.
1734
1735 Is anyone going to need the feature?
1736
1737 Only post features that you (or an incapacitated friend you can
1738 personally talk to) require. Do not post features because they seem like
1739 a good idea. If they are really useful, they will be requested by
1740 someone who requires them.
1741
1742 Is your question about youtube-dl?
1743
1744 It may sound strange, but some bug reports we receive are completely
1745 unrelated to youtube-dl and relate to a different, or even the
1746 reporter's own, application. Please make sure that you are actually
1747 using youtube-dl. If you are using a UI for youtube-dl, report the bug
1748 to the maintainer of the actual application providing the UI. On the
1749 other hand, if your UI for youtube-dl fails in some way you believe is
1750 related to youtube-dl, by all means, go ahead and report the bug.
1751
1752
1753
1754 COPYRIGHT
1755
1756
1757 youtube-dl is released into the public domain by the copyright holders.
1758
1759 This README file was originally written by Daniel Bolton and is likewise
1760 released into the public domain.