]> Raphaƫl G. Git Repositories - youtubedl/blob - README.txt
fc369d2d2a0d34be41aad400ab3aafd4ff87e61f
[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 https://yt-dl.org/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 a .exe file and place it in their home
32 directory or any other location on their PATH.
33
34 OS X users can install YOUTUBE-DL with Homebrew.
35
36 brew install youtube-dl
37
38 You can also use pip:
39
40 sudo pip install youtube-dl
41
42 Alternatively, refer to the developer instructions for how to check out
43 and work with the git repository. For further options, including PGP
44 signatures, see https://rg3.github.io/youtube-dl/download.html .
45
46
47
48 DESCRIPTION
49
50
51 YOUTUBE-DL is a small command-line program to download videos from
52 YouTube.com and a few more sites. It requires the Python interpreter,
53 version 2.6, 2.7, or 3.2+, and it is not platform specific. It should
54 work on your Unix box, on Windows or on Mac OS X. It is released to the
55 public domain, which means you can modify it, redistribute it or use it
56 however you like.
57
58 youtube-dl [OPTIONS] URL [URL...]
59
60
61
62 OPTIONS
63
64
65 -h, --help Print this help text and exit
66 --version Print program version and exit
67 -U, --update Update this program to latest version. Make
68 sure that you have sufficient permissions
69 (run with sudo if needed)
70 -i, --ignore-errors Continue on download errors, for example to
71 skip unavailable videos in a playlist
72 --abort-on-error Abort downloading of further videos (in the
73 playlist or the command line) if an error
74 occurs
75 --dump-user-agent Display the current browser identification
76 --list-extractors List all supported extractors
77 --extractor-descriptions Output descriptions of all supported
78 extractors
79 --force-generic-extractor Force extraction to use the generic
80 extractor
81 --default-search PREFIX Use this prefix for unqualified URLs. For
82 example "gvsearch2:" downloads two videos
83 from google videos for youtube-dl "large
84 apple". Use the value "auto" to let
85 youtube-dl guess ("auto_warning" to emit a
86 warning when guessing). "error" just throws
87 an error. The default value "fixup_error"
88 repairs broken URLs, but emits an error if
89 this is not possible instead of searching.
90 --ignore-config Do not read configuration files. When given
91 in the global configuration file /etc
92 /youtube-dl.conf: Do not read the user
93 configuration in ~/.config/youtube-
94 dl/config (%APPDATA%/youtube-dl/config.txt
95 on Windows)
96 --flat-playlist Do not extract the videos of a playlist,
97 only list them.
98 --no-color Do not emit color codes in output
99
100
101 Network Options:
102
103 --proxy URL Use the specified HTTP/HTTPS proxy. Pass in
104 an empty string (--proxy "") for direct
105 connection
106 --socket-timeout SECONDS Time to wait before giving up, in seconds
107 --source-address IP Client-side IP address to bind to
108 (experimental)
109 -4, --force-ipv4 Make all connections via IPv4
110 (experimental)
111 -6, --force-ipv6 Make all connections via IPv6
112 (experimental)
113 --cn-verification-proxy URL Use this proxy to verify the IP address for
114 some Chinese sites. The default proxy
115 specified by --proxy (or none, if the
116 options is not present) is used for the
117 actual downloading. (experimental)
118
119
120 Video Selection:
121
122 --playlist-start NUMBER Playlist video to start at (default is 1)
123 --playlist-end NUMBER Playlist video to end at (default is last)
124 --playlist-items ITEM_SPEC Playlist video items to download. Specify
125 indices of the videos in the playlist
126 separated by commas like: "--playlist-items
127 1,2,5,8" if you want to download videos
128 indexed 1, 2, 5, 8 in the playlist. You can
129 specify range: "--playlist-items
130 1-3,7,10-13", it will download the videos
131 at index 1, 2, 3, 7, 10, 11, 12 and 13.
132 --match-title REGEX Download only matching titles (regex or
133 caseless sub-string)
134 --reject-title REGEX Skip download for matching titles (regex or
135 caseless sub-string)
136 --max-downloads NUMBER Abort after downloading NUMBER files
137 --min-filesize SIZE Do not download any videos smaller than
138 SIZE (e.g. 50k or 44.6m)
139 --max-filesize SIZE Do not download any videos larger than SIZE
140 (e.g. 50k or 44.6m)
141 --date DATE Download only videos uploaded in this date
142 --datebefore DATE Download only videos uploaded on or before
143 this date (i.e. inclusive)
144 --dateafter DATE Download only videos uploaded on or after
145 this date (i.e. inclusive)
146 --min-views COUNT Do not download any videos with less than
147 COUNT views
148 --max-views COUNT Do not download any videos with more than
149 COUNT views
150 --match-filter FILTER Generic video filter (experimental).
151 Specify any key (see help for -o for a list
152 of available keys) to match if the key is
153 present, !key to check if the key is not
154 present,key > NUMBER (like "comment_count >
155 12", also works with >=, <, <=, !=, =) to
156 compare against a number, and & to require
157 multiple matches. Values which are not
158 known are excluded unless you put a
159 question mark (?) after the operator.For
160 example, to only match videos that have
161 been liked more than 100 times and disliked
162 less than 50 times (or the dislike
163 functionality is not available at the given
164 service), but who also have a description,
165 use --match-filter "like_count > 100 &
166 dislike_count <? 50 & description" .
167 --no-playlist Download only the video, if the URL refers
168 to a video and a playlist.
169 --yes-playlist Download the playlist, if the URL refers to
170 a video and a playlist.
171 --age-limit YEARS Download only videos suitable for the given
172 age
173 --download-archive FILE Download only videos not listed in the
174 archive file. Record the IDs of all
175 downloaded videos in it.
176 --include-ads Download advertisements as well
177 (experimental)
178
179
180 Download Options:
181
182 -r, --rate-limit LIMIT Maximum download rate in bytes per second
183 (e.g. 50K or 4.2M)
184 -R, --retries RETRIES Number of retries (default is 10), or
185 "infinite".
186 --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
187 (default is 1024)
188 --no-resize-buffer Do not automatically adjust the buffer
189 size. By default, the buffer size is
190 automatically resized from an initial value
191 of SIZE.
192 --playlist-reverse Download playlist videos in reverse order
193 --xattr-set-filesize Set file xattribute ytdl.filesize with
194 expected filesize (experimental)
195 --hls-prefer-native Use the native HLS downloader instead of
196 ffmpeg (experimental)
197 --external-downloader COMMAND Use the specified external downloader.
198 Currently supports
199 aria2c,axel,curl,httpie,wget
200 --external-downloader-args ARGS Give these arguments to the external
201 downloader
202
203
204 Filesystem Options:
205
206 -a, --batch-file FILE File containing URLs to download ('-' for
207 stdin)
208 --id Use only video ID in file name
209 -o, --output TEMPLATE Output filename template. Use %(title)s to
210 get the title, %(uploader)s for the
211 uploader name, %(uploader_id)s for the
212 uploader nickname if different,
213 %(autonumber)s to get an automatically
214 incremented number, %(ext)s for the
215 filename extension, %(format)s for the
216 format description (like "22 - 1280x720" or
217 "HD"), %(format_id)s for the unique id of
218 the format (like YouTube's itags: "137"),
219 %(upload_date)s for the upload date
220 (YYYYMMDD), %(extractor)s for the provider
221 (youtube, metacafe, etc), %(id)s for the
222 video id, %(playlist_title)s,
223 %(playlist_id)s, or %(playlist)s (=title if
224 present, ID otherwise) for the playlist the
225 video is in, %(playlist_index)s for the
226 position in the playlist. %(height)s and
227 %(width)s for the width and height of the
228 video format. %(resolution)s for a textual
229 description of the resolution of the video
230 format. %% for a literal percent. Use - to
231 output to stdout. Can also be used to
232 download to a different directory, for
233 example with -o '/my/downloads/%(uploader)s
234 /%(title)s-%(id)s.%(ext)s' .
235 --autonumber-size NUMBER Specify the number of digits in
236 %(autonumber)s when it is present in output
237 filename template or --auto-number option
238 is given
239 --restrict-filenames Restrict filenames to only ASCII
240 characters, and avoid "&" and spaces in
241 filenames
242 -A, --auto-number [deprecated; use -o
243 "%(autonumber)s-%(title)s.%(ext)s" ] Number
244 downloaded files starting from 00000
245 -t, --title [deprecated] Use title in file name
246 (default)
247 -l, --literal [deprecated] Alias of --title
248 -w, --no-overwrites Do not overwrite files
249 -c, --continue Force resume of partially downloaded files.
250 By default, youtube-dl will resume
251 downloads if possible.
252 --no-continue Do not resume partially downloaded files
253 (restart from beginning)
254 --no-part Do not use .part files - write directly
255 into output file
256 --no-mtime Do not use the Last-modified header to set
257 the file modification time
258 --write-description Write video description to a .description
259 file
260 --write-info-json Write video metadata to a .info.json file
261 --write-annotations Write video annotations to a
262 .annotations.xml file
263 --load-info FILE JSON file containing the video information
264 (created with the "--write-info-json"
265 option)
266 --cookies FILE File to read cookies from and dump cookie
267 jar in
268 --cache-dir DIR Location in the filesystem where youtube-dl
269 can store some downloaded information
270 permanently. By default $XDG_CACHE_HOME
271 /youtube-dl or ~/.cache/youtube-dl . At the
272 moment, only YouTube player files (for
273 videos with obfuscated signatures) are
274 cached, but that may change.
275 --no-cache-dir Disable filesystem caching
276 --rm-cache-dir Delete all filesystem cache files
277
278
279 Thumbnail images:
280
281 --write-thumbnail Write thumbnail image to disk
282 --write-all-thumbnails Write all thumbnail image formats to disk
283 --list-thumbnails Simulate and list all available thumbnail
284 formats
285
286
287 Verbosity / Simulation Options:
288
289 -q, --quiet Activate quiet mode
290 --no-warnings Ignore warnings
291 -s, --simulate Do not download the video and do not write
292 anything to disk
293 --skip-download Do not download the video
294 -g, --get-url Simulate, quiet but print URL
295 -e, --get-title Simulate, quiet but print title
296 --get-id Simulate, quiet but print id
297 --get-thumbnail Simulate, quiet but print thumbnail URL
298 --get-description Simulate, quiet but print video description
299 --get-duration Simulate, quiet but print video length
300 --get-filename Simulate, quiet but print output filename
301 --get-format Simulate, quiet but print output format
302 -j, --dump-json Simulate, quiet but print JSON information.
303 See --output for a description of available
304 keys.
305 -J, --dump-single-json Simulate, quiet but print JSON information
306 for each command-line argument. If the URL
307 refers to a playlist, dump the whole
308 playlist information in a single line.
309 --print-json Be quiet and print the video information as
310 JSON (video is still being downloaded).
311 --newline Output progress bar as new lines
312 --no-progress Do not print progress bar
313 --console-title Display progress in console titlebar
314 -v, --verbose Print various debugging information
315 --dump-pages Print downloaded pages encoded using base64
316 to debug problems (very verbose)
317 --write-pages Write downloaded intermediary pages to
318 files in the current directory to debug
319 problems
320 --print-traffic Display sent and read HTTP traffic
321 -C, --call-home Contact the youtube-dl server for debugging
322 --no-call-home Do NOT contact the youtube-dl server for
323 debugging
324
325
326 Workarounds:
327
328 --encoding ENCODING Force the specified encoding (experimental)
329 --no-check-certificate Suppress HTTPS certificate validation
330 --prefer-insecure Use an unencrypted connection to retrieve
331 information about the video. (Currently
332 supported only for YouTube)
333 --user-agent UA Specify a custom user agent
334 --referer URL Specify a custom referer, use if the video
335 access is restricted to one domain
336 --add-header FIELD:VALUE Specify a custom HTTP header and its value,
337 separated by a colon ':'. You can use this
338 option multiple times
339 --bidi-workaround Work around terminals that lack
340 bidirectional text support. Requires bidiv
341 or fribidi executable in PATH
342 --sleep-interval SECONDS Number of seconds to sleep before each
343 download.
344
345
346 Video Format Options:
347
348 -f, --format FORMAT Video format code, see the "FORMAT
349 SELECTION" for all the info
350 --all-formats Download all available video formats
351 --prefer-free-formats Prefer free video formats unless a specific
352 one is requested
353 -F, --list-formats List all available formats
354 --youtube-skip-dash-manifest Do not download the DASH manifests and
355 related data on YouTube videos
356 --merge-output-format FORMAT If a merge is required (e.g.
357 bestvideo+bestaudio), output to given
358 container format. One of mkv, mp4, ogg,
359 webm, flv. Ignored if no merge is required
360
361
362 Subtitle Options:
363
364 --write-sub Write subtitle file
365 --write-auto-sub Write automatic subtitle file (YouTube
366 only)
367 --all-subs Download all the available subtitles of the
368 video
369 --list-subs List all available subtitles for the video
370 --sub-format FORMAT Subtitle format, accepts formats
371 preference, for example: "srt" or
372 "ass/srt/best"
373 --sub-lang LANGS Languages of the subtitles to download
374 (optional) separated by commas, use IETF
375 language tags like 'en,pt'
376
377
378 Authentication Options:
379
380 -u, --username USERNAME Login with this account ID
381 -p, --password PASSWORD Account password. If this option is left
382 out, youtube-dl will ask interactively.
383 -2, --twofactor TWOFACTOR Two-factor auth code
384 -n, --netrc Use .netrc authentication data
385 --video-password PASSWORD Video password (vimeo, smotri, youku)
386
387
388 Post-processing Options:
389
390 -x, --extract-audio Convert video files to audio-only files
391 (requires ffmpeg or avconv and ffprobe or
392 avprobe)
393 --audio-format FORMAT Specify audio format: "best", "aac",
394 "vorbis", "mp3", "m4a", "opus", or "wav";
395 "best" by default
396 --audio-quality QUALITY Specify ffmpeg/avconv audio quality, insert
397 a value between 0 (better) and 9 (worse)
398 for VBR or a specific bitrate like 128K
399 (default 5)
400 --recode-video FORMAT Encode the video to another format if
401 necessary (currently supported:
402 mp4|flv|ogg|webm|mkv|avi)
403 --postprocessor-args ARGS Give these arguments to the postprocessor
404 -k, --keep-video Keep the video file on disk after the post-
405 processing; the video is erased by default
406 --no-post-overwrites Do not overwrite post-processed files; the
407 post-processed files are overwritten by
408 default
409 --embed-subs Embed subtitles in the video (only for mkv
410 and mp4 videos)
411 --embed-thumbnail Embed thumbnail in the audio as cover art
412 --add-metadata Write metadata to the video file
413 --metadata-from-title FORMAT Parse additional metadata like song title /
414 artist from the video title. The format
415 syntax is the same as --output, the parsed
416 parameters replace existing values.
417 Additional templates: %(album)s,
418 %(artist)s. Example: --metadata-from-title
419 "%(artist)s - %(title)s" matches a title
420 like "Coldplay - Paradise"
421 --xattrs Write metadata to the video file's xattrs
422 (using dublin core and xdg standards)
423 --fixup POLICY Automatically correct known faults of the
424 file. One of never (do nothing), warn (only
425 emit a warning), detect_or_warn (the
426 default; fix file if we can, warn
427 otherwise)
428 --prefer-avconv Prefer avconv over ffmpeg for running the
429 postprocessors (default)
430 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
431 postprocessors
432 --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
433 either the path to the binary or its
434 containing directory.
435 --exec CMD Execute a command on the file after
436 downloading, similar to find's -exec
437 syntax. Example: --exec 'adb push {}
438 /sdcard/Music/ && rm {}'
439 --convert-subtitles FORMAT Convert the subtitles to other format
440 (currently supported: srt|ass|vtt)
441
442
443
444 CONFIGURATION
445
446
447 You can configure youtube-dl by placing any supported command line
448 option to a configuration file. On Linux, the system wide configuration
449 file is located at /etc/youtube-dl.conf and the user wide configuration
450 file at ~/.config/youtube-dl/config. On Windows, the user wide
451 configuration file locations are %APPDATA%\youtube-dl\config.txt or
452 C:\Users\<user name>\youtube-dl.conf. For example, with the following
453 configuration file youtube-dl will always extract the audio, not copy
454 the mtime and use a proxy:
455
456 --extract-audio
457 --no-mtime
458 --proxy 127.0.0.1:3128
459
460 You can use --ignore-config if you want to disable the configuration
461 file for a particular youtube-dl run.
462
463 Authentication with .netrc file
464
465 You may also want to configure automatic credentials storage for
466 extractors that support authentication (by providing login and password
467 with --username and --password) in order not to pass credentials as
468 command line arguments on every youtube-dl execution and prevent
469 tracking plain text passwords in the shell command history. You can
470 achieve this using a .netrc file on per extractor basis. For that you
471 will need to create a.netrc file in your $HOME and restrict permissions
472 to read/write by you only:
473
474 touch $HOME/.netrc
475 chmod a-rwx,u+rw $HOME/.netrc
476
477 After that you can add credentials for extractor in the following
478 format, where _extractor_ is the name of extractor in lowercase:
479
480 machine <extractor> login <login> password <password>
481
482 For example:
483
484 machine youtube login myaccount@gmail.com password my_youtube_password
485 machine twitch login my_twitch_account_name password my_twitch_password
486
487 To activate authentication with the .netrc file you should pass --netrc
488 to youtube-dl or place it in the configuration file.
489
490 On Windows you may also need to setup the %HOME% environment variable
491 manually.
492
493
494
495 OUTPUT TEMPLATE
496
497
498 The -o option allows users to indicate a template for the output file
499 names. The basic usage is not to set any template arguments when
500 downloading a single file, like in
501 youtube-dl -o funny_video.flv "http://some/video". However, it may
502 contain special sequences that will be replaced when downloading each
503 video. The special sequences have the format %(NAME)s. To clarify, that
504 is a percent symbol followed by a name in parentheses, followed by a
505 lowercase S. Allowed names are:
506
507 - id: The sequence will be replaced by the video identifier.
508 - url: The sequence will be replaced by the video URL.
509 - uploader: The sequence will be replaced by the nickname of the
510 person who uploaded the video.
511 - upload_date: The sequence will be replaced by the upload date in
512 YYYYMMDD format.
513 - title: The sequence will be replaced by the video title.
514 - ext: The sequence will be replaced by the appropriate extension
515 (like flv or mp4).
516 - epoch: The sequence will be replaced by the Unix epoch when creating
517 the file.
518 - autonumber: The sequence will be replaced by a five-digit number
519 that will be increased with each download, starting at zero.
520 - playlist: The sequence will be replaced by the name or the id of the
521 playlist that contains the video.
522 - playlist_index: The sequence will be replaced by the index of the
523 video in the playlist padded with leading zeros according to the
524 total length of the playlist.
525 - format_id: The sequence will be replaced by the format code
526 specified by --format.
527 - duration: The sequence will be replaced by the length of the video
528 in seconds.
529
530 The current default template is %(title)s-%(id)s.%(ext)s.
531
532 In some cases, you don't want special characters such as äø­, spaces, or
533 &, such as when transferring the downloaded filename to a Windows system
534 or the filename through an 8bit-unsafe channel. In these cases, add the
535 --restrict-filenames flag to get a shorter title:
536
537 ``` {.bash}
538 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc
539 youtube-dl test video ''_Ƥā†­š•.mp4 # All kinds of weird characters
540 $ youtube-dl --get-filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
541 youtube-dl_test_video_.mp4 # A simple file name
542 ```
543
544
545
546 FORMAT SELECTION
547
548
549 By default youtube-dl tries to download the best quality, but sometimes
550 you may want to download in a different format. The simplest case is
551 requesting a specific format, for example -f 22. You can get the list of
552 available formats using --list-formats, you can also use a file
553 extension (currently it supports aac, m4a, mp3, mp4, ogg, wav, webm) or
554 the special names best, bestvideo, bestaudio and worst.
555
556 If you want to download multiple videos and they don't have the same
557 formats available, you can specify the order of preference using
558 slashes, as in -f 22/17/18. You can also filter the video results by
559 putting a condition in brackets, as in -f "best[height=720]" (or
560 -f "[filesize>10M]"). This works for filesize, height, width, tbr, abr,
561 vbr, asr, and fps and the comparisons <, <=, >, >=, =, != and for ext,
562 acodec, vcodec, container, and protocol and the comparisons =, != .
563 Formats for which the value is not known are excluded unless you put a
564 question mark (?) after the operator. You can combine format filters, so
565 -f "[height <=? 720][tbr>500]" selects up to 720p videos (or videos
566 where the height is not known) with a bitrate of at least 500 KBit/s.
567 Use commas to download multiple formats, such as
568 -f 136/137/mp4/bestvideo,140/m4a/bestaudio. You can merge the video and
569 audio of two formats into a single file using
570 -f <video-format>+<audio-format> (requires ffmpeg or avconv), for
571 example -f bestvideo+bestaudio. Format selectors can also be grouped
572 using parentheses, for example if you want to download the best mp4 and
573 webm formats with a height lower than 480 you can use
574 -f '(mp4,webm)[height<480]'.
575
576 Since the end of April 2015 and version 2015.04.26 youtube-dl uses
577 -f bestvideo+bestaudio/best as default format selection (see #5447,
578 #5456). If ffmpeg or avconv are installed this results in downloading
579 bestvideo and bestaudio separately and muxing them together into a
580 single file giving the best overall quality available. Otherwise it
581 falls back to best and results in downloading the best available quality
582 served as a single file. best is also needed for videos that don't come
583 from YouTube because they don't provide the audio and video in two
584 different files. If you want to only download some dash formats (for
585 example if you are not interested in getting videos with a resolution
586 higher than 1080p), you can add
587 -f bestvideo[height<=?1080]+bestaudio/best to your configuration file.
588 Note that if you use youtube-dl to stream to stdout (and most likely to
589 pipe it to your media player then), i.e. you explicitly specify output
590 template as -o -, youtube-dl still uses -f best format selection in
591 order to start content delivery immediately to your player and not to
592 wait until bestvideo and bestaudio are downloaded and muxed.
593
594 If you want to preserve the old format selection behavior (prior to
595 youtube-dl 2015.04.26), i.e. you want to download the best available
596 quality media served as a single file, you should explicitly specify
597 your choice with -f best. You may want to add it to the configuration
598 file in order not to type it every time you run youtube-dl.
599
600
601
602 VIDEO SELECTION
603
604
605 Videos can be filtered by their upload date using the options --date,
606 --datebefore or --dateafter. They accept dates in two formats:
607
608 - Absolute dates: Dates in the format YYYYMMDD.
609 - Relative dates: Dates in the format
610 (now|today)[+-][0-9](day|week|month|year)(s)?
611
612 Examples:
613
614 ``` {.bash}
615 # Download only the videos uploaded in the last 6 months
616 $ youtube-dl --dateafter now-6months
617
618 # Download only the videos uploaded on January 1, 1970
619 $ youtube-dl --date 19700101
620
621 $ # Download only the videos uploaded in the 200x decade
622 $ youtube-dl --dateafter 20000101 --datebefore 20091231
623 ```
624
625
626
627 FAQ
628
629
630 How do I update youtube-dl?
631
632 If you've followed our manual installation instructions, you can simply
633 run youtube-dl -U (or, on Linux, sudo youtube-dl -U).
634
635 If you have used pip, a simple sudo pip install -U youtube-dl is
636 sufficient to update.
637
638 If you have installed youtube-dl using a package manager like _apt-get_
639 or _yum_, use the standard system update mechanism to update. Note that
640 distribution packages are often outdated. As a rule of thumb, youtube-dl
641 releases at least once a month, and often weekly or even daily. Simply
642 go to http://yt-dl.org/ to find out the current version. Unfortunately,
643 there is nothing we youtube-dl developers can do if your distribution
644 serves a really outdated version. You can (and should) complain to your
645 distribution in their bugtracker or support forum.
646
647 As a last resort, you can also uninstall the version installed by your
648 package manager and follow our manual installation instructions. For
649 that, remove the distribution's package, with a line like
650
651 sudo apt-get remove -y youtube-dl
652
653 Afterwards, simply follow our manual installation instructions:
654
655 sudo wget https://yt-dl.org/latest/youtube-dl -O /usr/local/bin/youtube-dl
656 sudo chmod a+x /usr/local/bin/youtube-dl
657 hash -r
658
659 Again, from then on you'll be able to update with sudo youtube-dl -U.
660
661 I'm getting an error Unable to extract OpenGraph title on YouTube playlists
662
663 YouTube changed their playlist format in March 2014 and later on, so
664 you'll need at least youtube-dl 2014.07.25 to download all YouTube
665 videos.
666
667 If you have installed youtube-dl with a package manager, pip, setup.py
668 or a tarball, please use that to update. Note that Ubuntu packages do
669 not seem to get updated anymore. Since we are not affiliated with
670 Ubuntu, there is little we can do. Feel free to report bugs to the
671 Ubuntu packaging guys - all they have to do is update the package to a
672 somewhat recent version. See above for a way to update.
673
674 Do I always have to pass -citw?
675
676 By default, youtube-dl intends to have the best options (incidentally,
677 if you have a convincing case that these should be different, please
678 file an issue where you explain that). Therefore, it is unnecessary and
679 sometimes harmful to copy long option strings from webpages. In
680 particular, the only option out of -citw that is regularly useful is -i.
681
682 Can you please put the -b option back?
683
684 Most people asking this question are not aware that youtube-dl now
685 defaults to downloading the highest available quality as reported by
686 YouTube, which will be 1080p or 720p in some cases, so you no longer
687 need the -b option. For some specific videos, maybe YouTube does not
688 report them to be available in a specific high quality format you're
689 interested in. In that case, simply request it with the -f option and
690 youtube-dl will try to download it.
691
692 I get HTTP error 402 when trying to download a video. What's this?
693
694 Apparently YouTube requires you to pass a CAPTCHA test if you download
695 too much. We're considering to provide a way to let you solve the
696 CAPTCHA, but at the moment, your best course of action is pointing a
697 webbrowser to the youtube URL, solving the CAPTCHA, and restart
698 youtube-dl.
699
700 I have downloaded a video but how can I play it?
701
702 Once the video is fully downloaded, use any video player, such as vlc or
703 mplayer.
704
705 I extracted a video URL with -g, but it does not play on another machine / in my webbrowser.
706
707 It depends a lot on the service. In many cases, requests for the video
708 (to download/play it) must come from the same IP address and with the
709 same cookies. Use the --cookies option to write the required cookies
710 into a file, and advise your downloader to read cookies from that file.
711 Some sites also require a common user agent to be used, use
712 --dump-user-agent to see the one in use by youtube-dl.
713
714 It may be beneficial to use IPv6; in some cases, the restrictions are
715 only applied to IPv4. Some services (sometimes only for a subset of
716 videos) do not restrict the video URL by IP address, cookie, or
717 user-agent, but these are the exception rather than the rule.
718
719 Please bear in mind that some URL protocols are NOT supported by
720 browsers out of the box, including RTMP. If you are using -g, your own
721 downloader must support these as well.
722
723 If you want to play the video on a machine that is not running
724 youtube-dl, you can relay the video content from the machine that runs
725 youtube-dl. You can use -o - to let youtube-dl stream a video to stdout,
726 or simply allow the player to download the files written by youtube-dl
727 in turn.
728
729 ERROR: no fmt_url_map or conn information found in video info
730
731 YouTube has switched to a new video info format in July 2011 which is
732 not supported by old versions of youtube-dl. See above for how to update
733 youtube-dl.
734
735 ERROR: unable to download video
736
737 YouTube requires an additional signature since September 2012 which is
738 not supported by old versions of youtube-dl. See above for how to update
739 youtube-dl.
740
741 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
742
743 That's actually the output from your shell. Since ampersand is one of
744 the special shell characters it's interpreted by the shell preventing
745 you from passing the whole URL to youtube-dl. To disable your shell from
746 interpreting the ampersands (or any other special characters) you have
747 to either put the whole URL in quotes or escape them with a backslash
748 (which approach will work depends on your shell).
749
750 For example if your URL is
751 https://www.youtube.com/watch?t=4&v=BaW_jenozKc you should end up with
752 following command:
753
754 youtube-dl 'https://www.youtube.com/watch?t=4&v=BaW_jenozKc'
755
756 or
757
758 youtube-dl https://www.youtube.com/watch?t=4\&v=BaW_jenozKc
759
760 For Windows you have to use the double quotes:
761
762 youtube-dl "https://www.youtube.com/watch?t=4&v=BaW_jenozKc"
763
764 ExtractorError: Could not find JS function u'OF'
765
766 In February 2015, the new YouTube player contained a character sequence
767 in a string that was misinterpreted by old versions of youtube-dl. See
768 above for how to update youtube-dl.
769
770 HTTP Error 429: Too Many Requests or 402: Payment Required
771
772 These two error codes indicate that the service is blocking your IP
773 address because of overuse. Contact the service and ask them to unblock
774 your IP address, or - if you have acquired a whitelisted IP address
775 already - use the --proxy or --source-address options to select another
776 IP address.
777
778 SyntaxError: Non-ASCII character
779
780 The error
781
782 File "youtube-dl", line 2
783 SyntaxError: Non-ASCII character '\x93' ...
784
785 means you're using an outdated version of Python. Please update to
786 Python 2.6 or 2.7.
787
788 What is this binary file? Where has the code gone?
789
790 Since June 2012 (#342) youtube-dl is packed as an executable zipfile,
791 simply unzip it (might need renaming to youtube-dl.zip first on some
792 systems) or clone the git repository, as laid out above. If you modify
793 the code, you can run it by executing the __main__.py file. To recompile
794 the executable, run make youtube-dl.
795
796 The exe throws a _Runtime error from Visual C++_
797
798 To run the exe you need to install first the Microsoft Visual C++ 2008
799 Redistributable Package.
800
801 On Windows, how should I set up ffmpeg and youtube-dl? Where should I put the exe files?
802
803 If you put youtube-dl and ffmpeg in the same directory that you're
804 running the command from, it will work, but that's rather cumbersome.
805
806 To make a different directory work - either for ffmpeg, or for
807 youtube-dl, or for both - simply create the directory (say, C:\bin, or
808 C:\Users\<User name>\bin), put all the executables directly in there,
809 and then set your PATH environment variable to include that directory.
810
811 From then on, after restarting your shell, you will be able to access
812 both youtube-dl and ffmpeg (and youtube-dl will be able to find ffmpeg)
813 by simply typing youtube-dl or ffmpeg, no matter what directory you're
814 in.
815
816 How do I put downloads into a specific folder?
817
818 Use the -o to specify an output template, for example
819 -o "/home/user/videos/%(title)s-%(id)s.%(ext)s". If you want this for
820 all of your downloads, put the option into your configuration file.
821
822 How do I download a video starting with a - ?
823
824 Either prepend http://www.youtube.com/watch?v= or separate the ID from
825 the options with --:
826
827 youtube-dl -- -wNyEUrxzFU
828 youtube-dl "http://www.youtube.com/watch?v=-wNyEUrxzFU"
829
830 How do I pass cookies to youtube-dl?
831
832 Use the --cookies option, for example
833 --cookies /path/to/cookies/file.txt. Note that the cookies file must be
834 in Mozilla/Netscape format and the first line of the cookies file must
835 be either # HTTP Cookie File or # Netscape HTTP Cookie File. Make sure
836 you have correct newline format in the cookies file and convert newlines
837 if necessary to correspond with your OS, namely CRLF (\r\n) for Windows,
838 LF (\n) for Linux and CR (\r) for Mac OS. HTTP Error 400: Bad Request
839 when using --cookies is a good sign of invalid newline format.
840
841 Passing cookies to youtube-dl is a good way to workaround login when a
842 particular extractor does not implement it explicitly.
843
844 Can you add support for this anime video site, or site which shows current movies for free?
845
846 As a matter of policy (as well as legality), youtube-dl does not include
847 support for services that specialize in infringing copyright. As a rule
848 of thumb, if you cannot easily find a video that the service is quite
849 obviously allowed to distribute (i.e. that has been uploaded by the
850 creator, the creator's distributor, or is published under a free
851 license), the service is probably unfit for inclusion to youtube-dl.
852
853 A note on the service that they don't host the infringing content, but
854 just link to those who do, is evidence that the service should NOT be
855 included into youtube-dl. The same goes for any DMCA note when the whole
856 front page of the service is filled with videos they are not allowed to
857 distribute. A "fair use" note is equally unconvincing if the service
858 shows copyright-protected videos in full without authorization.
859
860 Support requests for services that DO purchase the rights to distribute
861 their content are perfectly fine though. If in doubt, you can simply
862 include a source that mentions the legitimate purchase of content.
863
864 How can I speed up work on my issue?
865
866 (Also known as: Help, my important issue not being solved!) The
867 youtube-dl core developer team is quite small. While we do our best to
868 solve as many issues as possible, sometimes that can take quite a while.
869 To speed up your issue, here's what you can do:
870
871 First of all, please do report the issue at our issue tracker. That
872 allows us to coordinate all efforts by users and developers, and serves
873 as a unified point. Unfortunately, the youtube-dl project has grown too
874 large to use personal email as an effective communication channel.
875
876 Please read the bug reporting instructions below. A lot of bugs lack all
877 the necessary information. If you can, offer proxy, VPN, or shell access
878 to the youtube-dl developers. If you are able to, test the issue from
879 multiple computers in multiple countries to exclude local censorship or
880 misconfiguration issues.
881
882 If nobody is interested in solving your issue, you are welcome to take
883 matters into your own hands and submit a pull request (or coerce/pay
884 somebody else to do so).
885
886 Feel free to bump the issue from time to time by writing a small comment
887 ("Issue is still present in youtube-dl version ...from France, but fixed
888 from Belgium"), but please not more than once a month. Please do not
889 declare your issue as important or urgent.
890
891 How can I detect whether a given URL is supported by youtube-dl?
892
893 For one, have a look at the list of supported sites. Note that it can
894 sometimes happen that the site changes its URL scheme (say, from
895 http://example.com/video/1234567 to http://example.com/v/1234567 ) and
896 youtube-dl reports an URL of a service in that list as unsupported. In
897 that case, simply report a bug.
898
899 It is _not_ possible to detect whether a URL is supported or not. That's
900 because youtube-dl contains a generic extractor which matches ALL URLs.
901 You may be tempted to disable, exclude, or remove the generic extractor,
902 but the generic extractor not only allows users to extract videos from
903 lots of websites that embed a video from another service, but may also
904 be used to extract video from a service that it's hosting itself.
905 Therefore, we neither recommend nor support disabling, excluding, or
906 removing the generic extractor.
907
908 If you want to find out whether a given URL is supported, simply call
909 youtube-dl with it. If you get no videos back, chances are the URL is
910 either not referring to a video or unsupported. You can find out which
911 by examining the output (if you run youtube-dl on the console) or
912 catching an UnsupportedError exception if you run it from a Python
913 program.
914
915
916
917 DEVELOPER INSTRUCTIONS
918
919
920 Most users do not need to build youtube-dl and can download the builds
921 or get them from their distribution.
922
923 To run youtube-dl as a developer, you don't need to build anything
924 either. Simply execute
925
926 python -m youtube_dl
927
928 To run the test, simply invoke your favorite test runner, or execute a
929 test file directly; any of the following work:
930
931 python -m unittest discover
932 python test/test_download.py
933 nosetests
934
935 If you want to create a build of youtube-dl yourself, you'll need
936
937 - python
938 - make
939 - pandoc
940 - zip
941 - nosetests
942
943 Adding support for a new site
944
945 If you want to add support for a new site, you can follow this quick
946 list (assuming your service is called yourextractor):
947
948 1. Fork this repository
949 2. Check out the source code with
950 git clone git@github.com:YOUR_GITHUB_USERNAME/youtube-dl.git
951 3. Start a new git branch with
952 cd youtube-dl; git checkout -b yourextractor
953 4. Start with this simple template and save it to
954 youtube_dl/extractor/yourextractor.py:
955
956 ``` {.python}
957 # coding: utf-8
958 from __future__ import unicode_literals
959
960 from .common import InfoExtractor
961
962
963 class YourExtractorIE(InfoExtractor):
964 _VALID_URL = r'https?://(?:www\.)?yourextractor\.com/watch/(?P<id>[0-9]+)'
965 _TEST = {
966 'url': 'http://yourextractor.com/watch/42',
967 'md5': 'TODO: md5 sum of the first 10241 bytes of the video file (use --test)',
968 'info_dict': {
969 'id': '42',
970 'ext': 'mp4',
971 'title': 'Video title goes here',
972 'thumbnail': 're:^https?://.*\.jpg$',
973 # TODO more properties, either as:
974 # * A value
975 # * MD5 checksum; start the string with md5:
976 # * A regular expression; start the string with re:
977 # * Any Python type (for example int or float)
978 }
979 }
980
981 def _real_extract(self, url):
982 video_id = self._match_id(url)
983 webpage = self._download_webpage(url, video_id)
984
985 # TODO more code goes here, for example ...
986 title = self._html_search_regex(r'<h1>(.+?)</h1>', webpage, 'title')
987
988 return {
989 'id': video_id,
990 'title': title,
991 'description': self._og_search_description(webpage),
992 'uploader': self._search_regex(r'<div[^>]+id="uploader"[^>]*>([^<]+)<', webpage, 'uploader', fatal=False),
993 # TODO more properties (see youtube_dl/extractor/common.py)
994 }
995 ```
996
997 5. Add an import in youtube_dl/extractor/__init__.py.
998 6. Run python test/test_download.py TestDownload.test_YourExtractor.
999 This _should fail_ at first, but you can continually re-run it until
1000 you're done. If you decide to add more than one test, then rename
1001 _TEST to _TESTS and make it into a list of dictionaries. The tests
1002 will then be named TestDownload.test_YourExtractor,
1003 TestDownload.test_YourExtractor_1,
1004 TestDownload.test_YourExtractor_2, etc.
1005 7. Have a look at youtube_dl/extractor/common.py for possible helper
1006 methods and a detailed description of what your extractor should and
1007 may return. Add tests and code for as many as you want.
1008 8. If you can, check the code with flake8.
1009 9. When the tests pass, add the new files and commit them and push the
1010 result, like this:
1011
1012 $ git add youtube_dl/extractor/__init__.py
1013 $ git add youtube_dl/extractor/yourextractor.py
1014 $ git commit -m '[yourextractor] Add new extractor'
1015 $ git push origin yourextractor
1016
1017 10. Finally, create a pull request. We'll then review and merge it.
1018
1019 In any case, thank you very much for your contributions!
1020
1021
1022
1023 EMBEDDING YOUTUBE-DL
1024
1025
1026 youtube-dl makes the best effort to be a good command-line program, and
1027 thus should be callable from any programming language. If you encounter
1028 any problems parsing its output, feel free to create a report.
1029
1030 From a Python program, you can embed youtube-dl in a more powerful
1031 fashion, like this:
1032
1033 ``` {.python}
1034 from __future__ import unicode_literals
1035 import youtube_dl
1036
1037 ydl_opts = {}
1038 with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1039 ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc'])
1040 ```
1041
1042 Most likely, you'll want to use various options. For a list of what can
1043 be done, have a look at youtube_dl/YoutubeDL.py. For a start, if you
1044 want to intercept youtube-dl's output, set a logger object.
1045
1046 Here's a more complete example of a program that outputs only errors
1047 (and a short message after the download is finished), and
1048 downloads/converts the video to an mp3 file:
1049
1050 ``` {.python}
1051 from __future__ import unicode_literals
1052 import youtube_dl
1053
1054
1055 class MyLogger(object):
1056 def debug(self, msg):
1057 pass
1058
1059 def warning(self, msg):
1060 pass
1061
1062 def error(self, msg):
1063 print(msg)
1064
1065
1066 def my_hook(d):
1067 if d['status'] == 'finished':
1068 print('Done downloading, now converting ...')
1069
1070
1071 ydl_opts = {
1072 'format': 'bestaudio/best',
1073 'postprocessors': [{
1074 'key': 'FFmpegExtractAudio',
1075 'preferredcodec': 'mp3',
1076 'preferredquality': '192',
1077 }],
1078 'logger': MyLogger(),
1079 'progress_hooks': [my_hook],
1080 }
1081 with youtube_dl.YoutubeDL(ydl_opts) as ydl:
1082 ydl.download(['http://www.youtube.com/watch?v=BaW_jenozKc'])
1083 ```
1084
1085
1086
1087 BUGS
1088
1089
1090 Bugs and suggestions should be reported at:
1091 https://github.com/rg3/youtube-dl/issues . Unless you were prompted so
1092 or there is another pertinent reason (e.g. GitHub fails to accept the
1093 bug report), please do not send bug reports via personal email. For
1094 discussions, join us in the irc channel #youtube-dl on freenode.
1095
1096 PLEASE INCLUDE THE FULL OUTPUT OF YOUTUBE-DL WHEN RUN WITH -v.
1097
1098 The output (including the first lines) contains important debugging
1099 information. Issues without the full output are often not reproducible
1100 and therefore do not get solved in short order, if ever.
1101
1102 Please re-read your issue once again to avoid a couple of common
1103 mistakes (you can and should use this as a checklist):
1104
1105 Is the description of the issue itself sufficient?
1106
1107 We often get issue reports that we cannot really decipher. While in most
1108 cases we eventually get the required information after asking back
1109 multiple times, this poses an unnecessary drain on our resources. Many
1110 contributors, including myself, are also not native speakers, so we may
1111 misread some parts.
1112
1113 So please elaborate on what feature you are requesting, or what bug you
1114 want to be fixed. Make sure that it's obvious
1115
1116 - What the problem is
1117 - How it could be fixed
1118 - How your proposed solution would look like
1119
1120 If your report is shorter than two lines, it is almost certainly missing
1121 some of these, which makes it hard for us to respond to it. We're often
1122 too polite to close the issue outright, but the missing info makes
1123 misinterpretation likely. As a commiter myself, I often get frustrated
1124 by these issues, since the only possible way for me to move forward on
1125 them is to ask for clarification over and over.
1126
1127 For bug reports, this means that your report should contain the
1128 _complete_ output of youtube-dl when called with the -v flag. The error
1129 message you get for (most) bugs even says so, but you would not believe
1130 how many of our bug reports do not contain this information.
1131
1132 If your server has multiple IPs or you suspect censorship, adding
1133 --call-home may be a good idea to get more diagnostics. If the error is
1134 ERROR: Unable to extract ... and you cannot reproduce it from multiple
1135 countries, add --dump-pages (warning: this will yield a rather large
1136 output, redirect it to the file log.txt by adding >log.txt 2>&1 to your
1137 command-line) or upload the .dump files you get when you add
1138 --write-pages somewhere.
1139
1140 SITE SUPPORT REQUESTS MUST CONTAIN AN EXAMPLE URL. An example URL is a
1141 URL you might want to download, like
1142 http://www.youtube.com/watch?v=BaW_jenozKc . There should be an obvious
1143 video present. Except under very special circumstances, the main page of
1144 a video service (e.g. http://www.youtube.com/ ) is _not_ an example URL.
1145
1146 Are you using the latest version?
1147
1148 Before reporting any issue, type youtube-dl -U. This should report that
1149 you're up-to-date. About 20% of the reports we receive are already
1150 fixed, but people are using outdated versions. This goes for feature
1151 requests as well.
1152
1153 Is the issue already documented?
1154
1155 Make sure that someone has not already opened the issue you're trying to
1156 open. Search at the top of the window or at
1157 https://github.com/rg3/youtube-dl/search?type=Issues . If there is an
1158 issue, feel free to write something along the lines of "This affects me
1159 as well, with version 2015.01.01. Here is some more information on the
1160 issue: ...". While some issues may be old, a new post into them often
1161 spurs rapid activity.
1162
1163 Why are existing options not enough?
1164
1165 Before requesting a new feature, please have a quick peek at the list of
1166 supported options. Many feature requests are for features that actually
1167 exist already! Please, absolutely do show off your work in the issue
1168 report and detail how the existing similar options do _not_ solve your
1169 problem.
1170
1171 Is there enough context in your bug report?
1172
1173 People want to solve problems, and often think they do us a favor by
1174 breaking down their larger problems (e.g. wanting to skip already
1175 downloaded files) to a specific request (e.g. requesting us to look
1176 whether the file exists before downloading the info page). However, what
1177 often happens is that they break down the problem into two steps: One
1178 simple, and one impossible (or extremely complicated one).
1179
1180 We are then presented with a very complicated request when the original
1181 problem could be solved far easier, e.g. by recording the downloaded
1182 video IDs in a separate file. To avoid this, you must include the
1183 greater context where it is non-obvious. In particular, every feature
1184 request that does not consist of adding support for a new site should
1185 contain a use case scenario that explains in what situation the missing
1186 feature would be useful.
1187
1188 Does the issue involve one problem, and one problem only?
1189
1190 Some of our users seem to think there is a limit of issues they can or
1191 should open. There is no limit of issues they can or should open. While
1192 it may seem appealing to be able to dump all your issues into one
1193 ticket, that means that someone who solves one of your issues cannot
1194 mark the issue as closed. Typically, reporting a bunch of issues leads
1195 to the ticket lingering since nobody wants to attack that behemoth,
1196 until someone mercifully splits the issue into multiple ones.
1197
1198 In particular, every site support request issue should only pertain to
1199 services at one site (generally under a common domain, but always using
1200 the same backend technology). Do not request support for vimeo user
1201 videos, Whitehouse podcasts, and Google Plus pages in the same issue.
1202 Also, make sure that you don't post bug reports alongside feature
1203 requests. As a rule of thumb, a feature request does not include outputs
1204 of youtube-dl that are not immediately related to the feature at hand.
1205 Do not post reports of a network error alongside the request for a new
1206 video service.
1207
1208 Is anyone going to need the feature?
1209
1210 Only post features that you (or an incapacitated friend you can
1211 personally talk to) require. Do not post features because they seem like
1212 a good idea. If they are really useful, they will be requested by
1213 someone who requires them.
1214
1215 Is your question about youtube-dl?
1216
1217 It may sound strange, but some bug reports we receive are completely
1218 unrelated to youtube-dl and relate to a different or even the reporter's
1219 own application. Please make sure that you are actually using
1220 youtube-dl. If you are using a UI for youtube-dl, report the bug to the
1221 maintainer of the actual application providing the UI. On the other
1222 hand, if your UI for youtube-dl fails in some way you believe is related
1223 to youtube-dl, by all means, go ahead and report the bug.
1224
1225
1226
1227 COPYRIGHT
1228
1229
1230 youtube-dl is released into the public domain by the copyright holders.
1231
1232 This README file was originally written by Daniel Bolton
1233 (https://github.com/dbbolton) and is likewise released into the public
1234 domain.