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