]> jfr.im git - yt-dlp.git/blame - README.md
projects / yt-dlp.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
[skip travis] added win/unix executable to readme
[yt-dlp.git] / README.md
CommitLineData
c8598bbe 1[![Build Status](https://travis-ci.com/blackjack4494/youtube-dlc.svg?branch=master)](https://travis-ci.com/blackjack4494/youtube-dlc)
5c0e5bc4 2
9ab41610 3youtube-dlc - download videos from youtube.com or other video platforms
6bcd846b 4
b50e3bc6
PH		 5- [INSTALLATION](#installation)
6- [DESCRIPTION](#description)
7- [OPTIONS](#options)
b50e3bc6 8- [COPYRIGHT](#copyright)
cfcec693 9
d19bb9c0
PH		 10# INSTALLATION
11
5f326cf5
TOH		 12**All Platforms**
13Preferred way using pip:
9ab41610 14You may want to use `python3` instead of `python`
d19bb9c0 15
9ab41610 16 python -m pip install --upgrade youtube-dlc
d19bb9c0 17
5f326cf5
TOH		 18**UNIX** (Linux, macOS, etc.)
19Using wget:
20
21 sudo wget https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -O /usr/local/bin/youtube-dlc
22 sudo chmod a+rx /usr/local/bin/youtube-dlc
23
24Using curl:
25
26 sudo curl -L https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc -o /usr/local/bin/youtube-dlc
27 sudo chmod a+rx /usr/local/bin/youtube-dlc
28
29
30**Windows** users can download [youtube-dlc.exe](https://github.com/blackjack4494/youtube-dlc/releases/latest/download/youtube-dlc.exe) (**do not** put in `C:\Windows\System32`!).
31
32**Compile**
33To build the Windows executable yourself
d19bb9c0 34
9ab41610
TOH		 35 python -m pip install --upgrade pyinstaller
36 pyinstaller.exe youtube_dl\__main__.py --onefile --name youtube-dlc
8f1aaa97 37
9ab41610 38Or simply execute the `make_win.bat` if pyinstaller is installed.
5f326cf5
TOH		 39There will be a `youtube-dlc.exe` in `/dist`
40
41For Unix:
42You will need the required build tools
43python, make (GNU), pandoc, zip, nosetests
44Then simply type this
45
46 make
47
d19bb9c0 48
cfcec693 49# DESCRIPTION
9ab41610 50**youtube-dlc** is a command-line program to download videos from YouTube.com and a few more sites. It requires the Python interpreter, version 2.6, 2.7, or 3.2+, and it is not platform specific. It should work on your Unix box, on Windows or on macOS. It is released to the public domain, which means you can modify it, redistribute it or use it however you like.
6bcd846b 51
9ab41610 52 youtube-dlc [OPTIONS] URL [URL...]
b50e3bc6 53
cfcec693 54# OPTIONS
1dc2726f
PH		 55 -h, --help Print this help text and exit
56 --version Print program version and exit
c4af7684
PH		 57 -U, --update Update this program to latest version. Make
58 sure that you have sufficient permissions
59 (run with sudo if needed)
60 -i, --ignore-errors Continue on download errors, for example to
61 skip unavailable videos in a playlist
62 --abort-on-error Abort downloading of further videos (in the
63 playlist or the command line) if an error
64 occurs
1dc2726f 65 --dump-user-agent Display the current browser identification
4b9f9010 66 --list-extractors List all supported extractors
c4af7684
PH		 67 --extractor-descriptions Output descriptions of all supported
68 extractors
69 --force-generic-extractor Force extraction to use the generic
70 extractor
71 --default-search PREFIX Use this prefix for unqualified URLs. For
72 example "gvsearch2:" downloads two videos
73 from google videos for youtube-dl "large
74 apple". Use the value "auto" to let
75 youtube-dl guess ("auto_warning" to emit a
76 warning when guessing). "error" just throws
77 an error. The default value "fixup_error"
78 repairs broken URLs, but emits an error if
79 this is not possible instead of searching.
80 --ignore-config Do not read configuration files. When given
82674236
S		 81 in the global configuration file
82 /etc/youtube-dl.conf: Do not read the user
c4af7684
PH		 83 configuration in ~/.config/youtube-
84 dl/config (%APPDATA%/youtube-dl/config.txt
85 on Windows)
dc48a354
S		 86 --config-location PATH Location of the configuration file; either
87 the path to the config or its containing
88 directory.
c4af7684
PH		 89 --flat-playlist Do not extract the videos of a playlist,
90 only list them.
bdf7f139
PH		 91 --mark-watched Mark videos watched (YouTube only)
92 --no-mark-watched Do not mark videos watched (YouTube only)
1dc2726f 93 --no-color Do not emit color codes in output
08c1d0d3 94
149f05c7 95## Network Options:
28b4f736 96 --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
0934c9d4
S		 97 To enable SOCKS proxy, specify a proper
98 scheme. For example
28b4f736
PH		 99 socks5://127.0.0.1:1080/. Pass in an empty
100 string (--proxy "") for direct connection
149f05c7 101 --socket-timeout SECONDS Time to wait before giving up, in seconds
c4af7684 102 --source-address IP Client-side IP address to bind to
c4af7684 103 -4, --force-ipv4 Make all connections via IPv4
c4af7684 104 -6, --force-ipv6 Make all connections via IPv6
8c6c88c7
S		 105
106## Geo Restriction:
c25f1a9b
S		 107 --geo-verification-proxy URL Use this proxy to verify the IP address for
108 some geo-restricted sites. The default
109 proxy specified by --proxy (or none, if the
7550ea50 110 option is not present) is used for the
4d2fdb07 111 actual downloading.
8c6c88c7 112 --geo-bypass Bypass geographic restriction via faking
0934c9d4 113 X-Forwarded-For HTTP header
8c6c88c7
S		 114 --no-geo-bypass Do not bypass geographic restriction via
115 faking X-Forwarded-For HTTP header
8c6c88c7
S		 116 --geo-bypass-country CODE Force bypass geographic restriction with
117 explicitly provided two-letter ISO 3166-2
0934c9d4 118 country code
9e18bb4c
S		 119 --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
120 explicitly provided IP block in CIDR
0934c9d4 121 notation
149f05c7 122
cfcec693 123## Video Selection:
1dc2726f
PH		 124 --playlist-start NUMBER Playlist video to start at (default is 1)
125 --playlist-end NUMBER Playlist video to end at (default is last)
c4af7684
PH		 126 --playlist-items ITEM_SPEC Playlist video items to download. Specify
127 indices of the videos in the playlist
128 separated by commas like: "--playlist-items
129 1,2,5,8" if you want to download videos
130 indexed 1, 2, 5, 8 in the playlist. You can
131 specify range: "--playlist-items
132 1-3,7,10-13", it will download the videos
133 at index 1, 2, 3, 7, 10, 11, 12 and 13.
134 --match-title REGEX Download only matching titles (regex or
135 caseless sub-string)
136 --reject-title REGEX Skip download for matching titles (regex or
137 caseless sub-string)
780083db 138 --max-downloads NUMBER Abort after downloading NUMBER files
c4af7684
PH		 139 --min-filesize SIZE Do not download any videos smaller than
140 SIZE (e.g. 50k or 44.6m)
141 --max-filesize SIZE Do not download any videos larger than SIZE
142 (e.g. 50k or 44.6m)
1dc2726f 143 --date DATE Download only videos uploaded in this date
c4af7684
PH		 144 --datebefore DATE Download only videos uploaded on or before
145 this date (i.e. inclusive)
146 --dateafter DATE Download only videos uploaded on or after
147 this date (i.e. inclusive)
148 --min-views COUNT Do not download any videos with less than
149 COUNT views
150 --max-views COUNT Do not download any videos with more than
151 COUNT views
4d2fdb07 152 --match-filter FILTER Generic video filter. Specify any key (see
cb1e6d89
S		 153 the "OUTPUT TEMPLATE" for a list of
154 available keys) to match if the key is
155 present, !key to check if the key is not
156 present, key > NUMBER (like "comment_count
157 > 12", also works with >=, <, <=, !=, =) to
158 compare against a number, key = 'LITERAL'
159 (like "uploader = 'Mike Smith'", also works
160 with !=) to match against a string literal
161 and & to require multiple matches. Values
162 which are not known are excluded unless you
163 put a question mark (?) after the operator.
164 For example, to only match videos that have
8c6c88c7
S		 165 been liked more than 100 times and disliked
166 less than 50 times (or the dislike
167 functionality is not available at the given
168 service), but who also have a description,
169 use --match-filter "like_count > 100 &
170 dislike_count <? 50 & description" .
c4af7684
PH		 171 --no-playlist Download only the video, if the URL refers
172 to a video and a playlist.
173 --yes-playlist Download the playlist, if the URL refers to
174 a video and a playlist.
175 --age-limit YEARS Download only videos suitable for the given
176 age
177 --download-archive FILE Download only videos not listed in the
178 archive file. Record the IDs of all
179 downloaded videos in it.
180 --include-ads Download advertisements as well
181 (experimental)
6bcd846b 182
d5a62e4f 183## Download Options:
5e3856a2 184 -r, --limit-rate RATE Maximum download rate in bytes per second
c4af7684
PH		 185 (e.g. 50K or 4.2M)
186 -R, --retries RETRIES Number of retries (default is 10), or
187 "infinite".
0be8314d 188 --fragment-retries RETRIES Number of retries for a fragment (default
b56e41a7
S		 189 is 10), or "infinite" (DASH, hlsnative and
190 ISM)
191 --skip-unavailable-fragments Skip unavailable fragments (DASH, hlsnative
192 and ISM)
4d2fdb07
S		 193 --abort-on-unavailable-fragment Abort downloading when some fragment is not
194 available
a82f4184
S		 195 --keep-fragments Keep downloaded fragments on disk after
196 downloading is finished; fragments are
197 erased by default
c4af7684
PH		 198 --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
199 (default is 1024)
200 --no-resize-buffer Do not automatically adjust the buffer
201 size. By default, the buffer size is
202 automatically resized from an initial value
203 of SIZE.
db157d2a
S		 204 --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
205 downloading (e.g. 10485760 or 10M) (default
206 is disabled). May be useful for bypassing
207 bandwidth throttling imposed by a webserver
208 (experimental)
2101f5d4 209 --playlist-reverse Download playlist videos in reverse order
31487eb9 210 --playlist-random Download playlist videos in random order
c4af7684 211 --xattr-set-filesize Set file xattribute ytdl.filesize with
0934c9d4 212 expected file size
c4af7684 213 --hls-prefer-native Use the native HLS downloader instead of
8b38f2ac
PH		 214 ffmpeg
215 --hls-prefer-ffmpeg Use ffmpeg instead of the native HLS
216 downloader
a69bee47
PH		 217 --hls-use-mpegts Use the mpegts container for HLS videos,
218 allowing to play the video while
219 downloading (some players may not be able
220 to play it)
c4af7684
PH		 221 --external-downloader COMMAND Use the specified external downloader.
222 Currently supports
6bb26669 223 aria2c,avconv,axel,curl,ffmpeg,httpie,wget
c4af7684
PH		 224 --external-downloader-args ARGS Give these arguments to the external
225 downloader
d5a62e4f 226
cfcec693 227## Filesystem Options:
c4af7684 228 -a, --batch-file FILE File containing URLs to download ('-' for
e8dfecb3
S		 229 stdin), one URL per line. Lines starting
230 with '#', ';' or ']' are considered as
231 comments and ignored.
1dc2726f 232 --id Use only video ID in file name
bd1bcd3e
S		 233 -o, --output TEMPLATE Output filename template, see the "OUTPUT
234 TEMPLATE" for all the info
4d2fdb07
S		 235 --autonumber-start NUMBER Specify the start value for %(autonumber)s
236 (default is 1)
c4af7684
PH		 237 --restrict-filenames Restrict filenames to only ASCII
238 characters, and avoid "&" and spaces in
239 filenames
1dc2726f 240 -w, --no-overwrites Do not overwrite files
c4af7684
PH		 241 -c, --continue Force resume of partially downloaded files.
242 By default, youtube-dl will resume
243 downloads if possible.
244 --no-continue Do not resume partially downloaded files
245 (restart from beginning)
246 --no-part Do not use .part files - write directly
247 into output file
248 --no-mtime Do not use the Last-modified header to set
249 the file modification time
250 --write-description Write video description to a .description
251 file
1dc2726f 252 --write-info-json Write video metadata to a .info.json file
c4af7684
PH		 253 --write-annotations Write video annotations to a
254 .annotations.xml file
d845622b 255 --load-info-json FILE JSON file containing the video information
c4af7684
PH		 256 (created with the "--write-info-json"
257 option)
258 --cookies FILE File to read cookies from and dump cookie
259 jar in
260 --cache-dir DIR Location in the filesystem where youtube-dl
261 can store some downloaded information
82674236
S		 262 permanently. By default
263 $XDG_CACHE_HOME/youtube-dl or
264 ~/.cache/youtube-dl . At the moment, only
265 YouTube player files (for videos with
266 obfuscated signatures) are cached, but that
267 may change.
36f35428
PH		 268 --no-cache-dir Disable filesystem caching
269 --rm-cache-dir Delete all filesystem cache files
6bcd846b 270
2b1bd292 271## Thumbnail images:
1dc2726f
PH		 272 --write-thumbnail Write thumbnail image to disk
273 --write-all-thumbnails Write all thumbnail image formats to disk
c4af7684
PH		 274 --list-thumbnails Simulate and list all available thumbnail
275 formats
2b1bd292 276
cfcec693 277## Verbosity / Simulation Options:
1dc2726f 278 -q, --quiet Activate quiet mode
6c072e7d 279 --no-warnings Ignore warnings
c4af7684
PH		 280 -s, --simulate Do not download the video and do not write
281 anything to disk
1dc2726f
PH		 282 --skip-download Do not download the video
283 -g, --get-url Simulate, quiet but print URL
284 -e, --get-title Simulate, quiet but print title
285 --get-id Simulate, quiet but print id
286 --get-thumbnail Simulate, quiet but print thumbnail URL
287 --get-description Simulate, quiet but print video description
288 --get-duration Simulate, quiet but print video length
289 --get-filename Simulate, quiet but print output filename
290 --get-format Simulate, quiet but print output format
c4af7684 291 -j, --dump-json Simulate, quiet but print JSON information.
cb1e6d89
S		 292 See the "OUTPUT TEMPLATE" for a description
293 of available keys.
c4af7684
PH		 294 -J, --dump-single-json Simulate, quiet but print JSON information
295 for each command-line argument. If the URL
296 refers to a playlist, dump the whole
297 playlist information in a single line.
298 --print-json Be quiet and print the video information as
299 JSON (video is still being downloaded).
1dc2726f
PH		 300 --newline Output progress bar as new lines
301 --no-progress Do not print progress bar
302 --console-title Display progress in console titlebar
303 -v, --verbose Print various debugging information
c4af7684
PH		 304 --dump-pages Print downloaded pages encoded using base64
305 to debug problems (very verbose)
306 --write-pages Write downloaded intermediary pages to
307 files in the current directory to debug
308 problems
780083db 309 --print-traffic Display sent and read HTTP traffic
1dc2726f 310 -C, --call-home Contact the youtube-dl server for debugging
c4af7684
PH		 311 --no-call-home Do NOT contact the youtube-dl server for
312 debugging
6bcd846b 313
36f35428
PH		 314## Workarounds:
315 --encoding ENCODING Force the specified encoding (experimental)
1dc2726f 316 --no-check-certificate Suppress HTTPS certificate validation
c4af7684 317 --prefer-insecure Use an unencrypted connection to retrieve
05a7ffb1
S		 318 information about the video. (Currently
319 supported only for YouTube)
1dc2726f 320 --user-agent UA Specify a custom user agent
c4af7684
PH		 321 --referer URL Specify a custom referer, use if the video
322 access is restricted to one domain
323 --add-header FIELD:VALUE Specify a custom HTTP header and its value,
324 separated by a colon ':'. You can use this
325 option multiple times
326 --bidi-workaround Work around terminals that lack
327 bidirectional text support. Requires bidiv
328 or fribidi executable in PATH
329 --sleep-interval SECONDS Number of seconds to sleep before each
b1ce2ba1
S		 330 download when used alone or a lower bound
331 of a range for randomized sleep before each
332 download (minimum possible number of
333 seconds to sleep) when used along with
334 --max-sleep-interval.
335 --max-sleep-interval SECONDS Upper bound of a range for randomized sleep
336 before each download (maximum possible
337 number of seconds to sleep). Must only be
338 used along with --min-sleep-interval.
36f35428 339
cfcec693 340## Video Format Options:
c4af7684
PH		 341 -f, --format FORMAT Video format code, see the "FORMAT
342 SELECTION" for all the info
1dc2726f 343 --all-formats Download all available video formats
c4af7684
PH		 344 --prefer-free-formats Prefer free video formats unless a specific
345 one is requested
535d7b68 346 -F, --list-formats List all available formats of requested
bb6ac836 347 videos
c4af7684
PH		 348 --youtube-skip-dash-manifest Do not download the DASH manifests and
349 related data on YouTube videos
350 --merge-output-format FORMAT If a merge is required (e.g.
351 bestvideo+bestaudio), output to given
352 container format. One of mkv, mp4, ogg,
353 webm, flv. Ignored if no merge is required
8ae7be3e
PH		 354
355## Subtitle Options:
1dc2726f 356 --write-sub Write subtitle file
741dd8ea
RB		 357 --write-auto-sub Write automatically generated subtitle file
358 (YouTube only)
c4af7684
PH		 359 --all-subs Download all the available subtitles of the
360 video
1dc2726f 361 --list-subs List all available subtitles for the video
c4af7684
PH		 362 --sub-format FORMAT Subtitle format, accepts formats
363 preference, for example: "srt" or
364 "ass/srt/best"
365 --sub-lang LANGS Languages of the subtitles to download
f733b053
PH		 366 (optional) separated by commas, use --list-
367 subs for available language tags
6bcd846b 368
cfcec693 369## Authentication Options:
1dc2726f 370 -u, --username USERNAME Login with this account ID
c4af7684
PH		 371 -p, --password PASSWORD Account password. If this option is left
372 out, youtube-dl will ask interactively.
dc48a354 373 -2, --twofactor TWOFACTOR Two-factor authentication code
1dc2726f 374 -n, --netrc Use .netrc authentication data
804c343a 375 --video-password PASSWORD Video password (vimeo, smotri, youku)
6bcd846b 376
f5e008d1
S		 377## Adobe Pass Options:
378 --ap-mso MSO Adobe Pass multiple-system operator (TV
379 provider) identifier, use --ap-list-mso for
380 a list of available MSOs
381 --ap-username USERNAME Multiple-system operator account login
382 --ap-password PASSWORD Multiple-system operator account password.
383 If this option is left out, youtube-dl will
384 ask interactively.
385 --ap-list-mso List all supported multiple-system
386 operators
387
cfcec693 388## Post-processing Options:
c4af7684
PH		 389 -x, --extract-audio Convert video files to audio-only files
390 (requires ffmpeg or avconv and ffprobe or
391 avprobe)
392 --audio-format FORMAT Specify audio format: "best", "aac",
7d539ee1
S		 393 "flac", "mp3", "m4a", "opus", "vorbis", or
394 "wav"; "best" by default; No effect without
395 -x
c4af7684
PH		 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)
f72b0a60 403 --postprocessor-args ARGS Give these arguments to the postprocessor
c4af7684
PH		 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
0be8314d
PH		 409 --embed-subs Embed subtitles in the video (only for mp4,
410 webm and mkv videos)
1dc2726f
PH		 411 --embed-thumbnail Embed thumbnail in the audio as cover art
412 --add-metadata Write metadata to the video file
c4af7684
PH		 413 --metadata-from-title FORMAT Parse additional metadata like song title /
414 artist from the video title. The format
6f3c632c
S		 415 syntax is the same as --output. Regular
416 expression with named capture groups may
417 also be used. The parsed parameters replace
418 existing values. Example: --metadata-from-
419 title "%(artist)s - %(title)s" matches a
420 title like "Coldplay - Paradise". Example
421 (regex): --metadata-from-title
422 "(?P<artist>.+?) - (?P<title>.+)"
c4af7684
PH		 423 --xattrs Write metadata to the video file's xattrs
424 (using dublin core and xdg standards)
425 --fixup POLICY Automatically correct known faults of the
426 file. One of never (do nothing), warn (only
427 emit a warning), detect_or_warn (the
428 default; fix file if we can, warn
429 otherwise)
430 --prefer-avconv Prefer avconv over ffmpeg for running the
c4af7684 431 postprocessors
689af496
S		 432 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
433 postprocessors (default)
c4af7684
PH		 434 --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
435 either the path to the binary or its
436 containing directory.
437 --exec CMD Execute a command on the file after
00a41ca4
S		 438 downloading and post-processing, similar to
439 find's -exec syntax. Example: --exec 'adb
440 push {} /sdcard/Music/ && rm {}'
7de81fcc 441 --convert-subs FORMAT Convert the subtitles to other format
9fc41bcb 442 (currently supported: srt|ass|vtt|lrc)
6bcd846b 443
63ef36e8
PH		 444# COPYRIGHT
445
a1b8d815 446youtube-dl is released into the public domain by the copyright holders.
63ef36e8 447
46047c58 448This README file was originally written by [Daniel Bolton](https://github.com/dbbolton) and is likewise released into the public domain.
fork of https://github.com/yt-dlp/yt-dlp/