]> jfr.im git - yt-dlp.git/blame_incremental - README.md
projects / yt-dlp.git / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
[skip travis] added win/unix executable to readme
[yt-dlp.git] / README.md
... / ...
CommitLineData
1[![Build Status](https://travis-ci.com/blackjack4494/youtube-dlc.svg?branch=master)](https://travis-ci.com/blackjack4494/youtube-dlc)
2
3youtube-dlc - download videos from youtube.com or other video platforms
4
5- [INSTALLATION](#installation)
6- [DESCRIPTION](#description)
7- [OPTIONS](#options)
8- [COPYRIGHT](#copyright)
9
10# INSTALLATION
11
12**All Platforms**
13Preferred way using pip:
14You may want to use `python3` instead of `python`
15
16 python -m pip install --upgrade youtube-dlc
17
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
34
35 python -m pip install --upgrade pyinstaller
36 pyinstaller.exe youtube_dl\__main__.py --onefile --name youtube-dlc
37
38Or simply execute the `make_win.bat` if pyinstaller is installed.
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
48
49# DESCRIPTION
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.
51
52 youtube-dlc [OPTIONS] URL [URL...]
53
54# OPTIONS
55 -h, --help Print this help text and exit
56 --version Print program version and exit
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
65 --dump-user-agent Display the current browser identification
66 --list-extractors List all supported extractors
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
81 in the global configuration file
82 /etc/youtube-dl.conf: Do not read the user
83 configuration in ~/.config/youtube-
84 dl/config (%APPDATA%/youtube-dl/config.txt
85 on Windows)
86 --config-location PATH Location of the configuration file; either
87 the path to the config or its containing
88 directory.
89 --flat-playlist Do not extract the videos of a playlist,
90 only list them.
91 --mark-watched Mark videos watched (YouTube only)
92 --no-mark-watched Do not mark videos watched (YouTube only)
93 --no-color Do not emit color codes in output
94
95## Network Options:
96 --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
97 To enable SOCKS proxy, specify a proper
98 scheme. For example
99 socks5://127.0.0.1:1080/. Pass in an empty
100 string (--proxy "") for direct connection
101 --socket-timeout SECONDS Time to wait before giving up, in seconds
102 --source-address IP Client-side IP address to bind to
103 -4, --force-ipv4 Make all connections via IPv4
104 -6, --force-ipv6 Make all connections via IPv6
105
106## Geo Restriction:
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
110 option is not present) is used for the
111 actual downloading.
112 --geo-bypass Bypass geographic restriction via faking
113 X-Forwarded-For HTTP header
114 --no-geo-bypass Do not bypass geographic restriction via
115 faking X-Forwarded-For HTTP header
116 --geo-bypass-country CODE Force bypass geographic restriction with
117 explicitly provided two-letter ISO 3166-2
118 country code
119 --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
120 explicitly provided IP block in CIDR
121 notation
122
123## Video Selection:
124 --playlist-start NUMBER Playlist video to start at (default is 1)
125 --playlist-end NUMBER Playlist video to end at (default is last)
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)
138 --max-downloads NUMBER Abort after downloading NUMBER files
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)
143 --date DATE Download only videos uploaded in this date
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
152 --match-filter FILTER Generic video filter. Specify any key (see
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
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" .
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)
182
183## Download Options:
184 -r, --limit-rate RATE Maximum download rate in bytes per second
185 (e.g. 50K or 4.2M)
186 -R, --retries RETRIES Number of retries (default is 10), or
187 "infinite".
188 --fragment-retries RETRIES Number of retries for a fragment (default
189 is 10), or "infinite" (DASH, hlsnative and
190 ISM)
191 --skip-unavailable-fragments Skip unavailable fragments (DASH, hlsnative
192 and ISM)
193 --abort-on-unavailable-fragment Abort downloading when some fragment is not
194 available
195 --keep-fragments Keep downloaded fragments on disk after
196 downloading is finished; fragments are
197 erased by default
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.
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)
209 --playlist-reverse Download playlist videos in reverse order
210 --playlist-random Download playlist videos in random order
211 --xattr-set-filesize Set file xattribute ytdl.filesize with
212 expected file size
213 --hls-prefer-native Use the native HLS downloader instead of
214 ffmpeg
215 --hls-prefer-ffmpeg Use ffmpeg instead of the native HLS
216 downloader
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)
221 --external-downloader COMMAND Use the specified external downloader.
222 Currently supports
223 aria2c,avconv,axel,curl,ffmpeg,httpie,wget
224 --external-downloader-args ARGS Give these arguments to the external
225 downloader
226
227## Filesystem Options:
228 -a, --batch-file FILE File containing URLs to download ('-' for
229 stdin), one URL per line. Lines starting
230 with '#', ';' or ']' are considered as
231 comments and ignored.
232 --id Use only video ID in file name
233 -o, --output TEMPLATE Output filename template, see the "OUTPUT
234 TEMPLATE" for all the info
235 --autonumber-start NUMBER Specify the start value for %(autonumber)s
236 (default is 1)
237 --restrict-filenames Restrict filenames to only ASCII
238 characters, and avoid "&" and spaces in
239 filenames
240 -w, --no-overwrites Do not overwrite files
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
252 --write-info-json Write video metadata to a .info.json file
253 --write-annotations Write video annotations to a
254 .annotations.xml file
255 --load-info-json FILE JSON file containing the video information
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
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.
268 --no-cache-dir Disable filesystem caching
269 --rm-cache-dir Delete all filesystem cache files
270
271## Thumbnail images:
272 --write-thumbnail Write thumbnail image to disk
273 --write-all-thumbnails Write all thumbnail image formats to disk
274 --list-thumbnails Simulate and list all available thumbnail
275 formats
276
277## Verbosity / Simulation Options:
278 -q, --quiet Activate quiet mode
279 --no-warnings Ignore warnings
280 -s, --simulate Do not download the video and do not write
281 anything to disk
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
291 -j, --dump-json Simulate, quiet but print JSON information.
292 See the "OUTPUT TEMPLATE" for a description
293 of available keys.
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).
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
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
309 --print-traffic Display sent and read HTTP traffic
310 -C, --call-home Contact the youtube-dl server for debugging
311 --no-call-home Do NOT contact the youtube-dl server for
312 debugging
313
314## Workarounds:
315 --encoding ENCODING Force the specified encoding (experimental)
316 --no-check-certificate Suppress HTTPS certificate validation
317 --prefer-insecure Use an unencrypted connection to retrieve
318 information about the video. (Currently
319 supported only for YouTube)
320 --user-agent UA Specify a custom user agent
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
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.
339
340## Video Format Options:
341 -f, --format FORMAT Video format code, see the "FORMAT
342 SELECTION" for all the info
343 --all-formats Download all available video formats
344 --prefer-free-formats Prefer free video formats unless a specific
345 one is requested
346 -F, --list-formats List all available formats of requested
347 videos
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
354
355## Subtitle Options:
356 --write-sub Write subtitle file
357 --write-auto-sub Write automatically generated subtitle file
358 (YouTube only)
359 --all-subs Download all the available subtitles of the
360 video
361 --list-subs List all available subtitles for the video
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
366 (optional) separated by commas, use --list-
367 subs for available language tags
368
369## Authentication Options:
370 -u, --username USERNAME Login with this account ID
371 -p, --password PASSWORD Account password. If this option is left
372 out, youtube-dl will ask interactively.
373 -2, --twofactor TWOFACTOR Two-factor authentication code
374 -n, --netrc Use .netrc authentication data
375 --video-password PASSWORD Video password (vimeo, smotri, youku)
376
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
388## Post-processing Options:
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",
393 "flac", "mp3", "m4a", "opus", "vorbis", or
394 "wav"; "best" by default; No effect without
395 -x
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 mp4,
410 webm and mkv 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. 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>.+)"
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
431 postprocessors
432 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
433 postprocessors (default)
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
438 downloading and post-processing, similar to
439 find's -exec syntax. Example: --exec 'adb
440 push {} /sdcard/Music/ && rm {}'
441 --convert-subs FORMAT Convert the subtitles to other format
442 (currently supported: srt|ass|vtt|lrc)
443
444# COPYRIGHT
445
446youtube-dl is released into the public domain by the copyright holders.
447
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/