]> 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] versioning in pypi is fun..
[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-
e3671279
U		 85 dlc/config (%APPDATA%/youtube-
86 dlc/config.txt 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
e3671279
U		 261 --cache-dir DIR Location in the filesystem where youtube-
262 dlc 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
e3671279
U		 311 -C, --call-home Contact the youtube-dlc server for
312 debugging
cefecac1 313 --no-call-home Do NOT contact the youtube-dlc server for
c4af7684 314 debugging
6bcd846b 315
36f35428
PH		 316## Workarounds:
317 --encoding ENCODING Force the specified encoding (experimental)
1dc2726f 318 --no-check-certificate Suppress HTTPS certificate validation
c4af7684 319 --prefer-insecure Use an unencrypted connection to retrieve
05a7ffb1
S		 320 information about the video. (Currently
321 supported only for YouTube)
1dc2726f 322 --user-agent UA Specify a custom user agent
c4af7684
PH		 323 --referer URL Specify a custom referer, use if the video
324 access is restricted to one domain
325 --add-header FIELD:VALUE Specify a custom HTTP header and its value,
326 separated by a colon ':'. You can use this
327 option multiple times
328 --bidi-workaround Work around terminals that lack
329 bidirectional text support. Requires bidiv
330 or fribidi executable in PATH
331 --sleep-interval SECONDS Number of seconds to sleep before each
b1ce2ba1
S		 332 download when used alone or a lower bound
333 of a range for randomized sleep before each
334 download (minimum possible number of
335 seconds to sleep) when used along with
336 --max-sleep-interval.
337 --max-sleep-interval SECONDS Upper bound of a range for randomized sleep
338 before each download (maximum possible
339 number of seconds to sleep). Must only be
340 used along with --min-sleep-interval.
36f35428 341
cfcec693 342## Video Format Options:
c4af7684
PH		 343 -f, --format FORMAT Video format code, see the "FORMAT
344 SELECTION" for all the info
1dc2726f 345 --all-formats Download all available video formats
c4af7684
PH		 346 --prefer-free-formats Prefer free video formats unless a specific
347 one is requested
535d7b68 348 -F, --list-formats List all available formats of requested
bb6ac836 349 videos
c4af7684
PH		 350 --youtube-skip-dash-manifest Do not download the DASH manifests and
351 related data on YouTube videos
352 --merge-output-format FORMAT If a merge is required (e.g.
353 bestvideo+bestaudio), output to given
354 container format. One of mkv, mp4, ogg,
355 webm, flv. Ignored if no merge is required
8ae7be3e
PH		 356
357## Subtitle Options:
1dc2726f 358 --write-sub Write subtitle file
741dd8ea
RB		 359 --write-auto-sub Write automatically generated subtitle file
360 (YouTube only)
c4af7684
PH		 361 --all-subs Download all the available subtitles of the
362 video
1dc2726f 363 --list-subs List all available subtitles for the video
c4af7684
PH		 364 --sub-format FORMAT Subtitle format, accepts formats
365 preference, for example: "srt" or
366 "ass/srt/best"
367 --sub-lang LANGS Languages of the subtitles to download
f733b053
PH		 368 (optional) separated by commas, use --list-
369 subs for available language tags
6bcd846b 370
cfcec693 371## Authentication Options:
1dc2726f 372 -u, --username USERNAME Login with this account ID
c4af7684 373 -p, --password PASSWORD Account password. If this option is left
cefecac1 374 out, youtube-dlc will ask interactively.
dc48a354 375 -2, --twofactor TWOFACTOR Two-factor authentication code
1dc2726f 376 -n, --netrc Use .netrc authentication data
804c343a 377 --video-password PASSWORD Video password (vimeo, smotri, youku)
6bcd846b 378
f5e008d1
S		 379## Adobe Pass Options:
380 --ap-mso MSO Adobe Pass multiple-system operator (TV
381 provider) identifier, use --ap-list-mso for
382 a list of available MSOs
383 --ap-username USERNAME Multiple-system operator account login
384 --ap-password PASSWORD Multiple-system operator account password.
e3671279
U		 385 If this option is left out, youtube-dlc
386 will ask interactively.
f5e008d1
S		 387 --ap-list-mso List all supported multiple-system
388 operators
389
cfcec693 390## Post-processing Options:
c4af7684
PH		 391 -x, --extract-audio Convert video files to audio-only files
392 (requires ffmpeg or avconv and ffprobe or
393 avprobe)
394 --audio-format FORMAT Specify audio format: "best", "aac",
7d539ee1
S		 395 "flac", "mp3", "m4a", "opus", "vorbis", or
396 "wav"; "best" by default; No effect without
397 -x
c4af7684
PH		 398 --audio-quality QUALITY Specify ffmpeg/avconv audio quality, insert
399 a value between 0 (better) and 9 (worse)
400 for VBR or a specific bitrate like 128K
401 (default 5)
402 --recode-video FORMAT Encode the video to another format if
403 necessary (currently supported:
404 mp4|flv|ogg|webm|mkv|avi)
f72b0a60 405 --postprocessor-args ARGS Give these arguments to the postprocessor
c4af7684
PH		 406 -k, --keep-video Keep the video file on disk after the post-
407 processing; the video is erased by default
408 --no-post-overwrites Do not overwrite post-processed files; the
409 post-processed files are overwritten by
410 default
0be8314d
PH		 411 --embed-subs Embed subtitles in the video (only for mp4,
412 webm and mkv videos)
1dc2726f
PH		 413 --embed-thumbnail Embed thumbnail in the audio as cover art
414 --add-metadata Write metadata to the video file
c4af7684
PH		 415 --metadata-from-title FORMAT Parse additional metadata like song title /
416 artist from the video title. The format
6f3c632c
S		 417 syntax is the same as --output. Regular
418 expression with named capture groups may
419 also be used. The parsed parameters replace
420 existing values. Example: --metadata-from-
421 title "%(artist)s - %(title)s" matches a
422 title like "Coldplay - Paradise". Example
423 (regex): --metadata-from-title
424 "(?P<artist>.+?) - (?P<title>.+)"
c4af7684
PH		 425 --xattrs Write metadata to the video file's xattrs
426 (using dublin core and xdg standards)
427 --fixup POLICY Automatically correct known faults of the
428 file. One of never (do nothing), warn (only
429 emit a warning), detect_or_warn (the
430 default; fix file if we can, warn
431 otherwise)
432 --prefer-avconv Prefer avconv over ffmpeg for running the
c4af7684 433 postprocessors
689af496
S		 434 --prefer-ffmpeg Prefer ffmpeg over avconv for running the
435 postprocessors (default)
c4af7684
PH		 436 --ffmpeg-location PATH Location of the ffmpeg/avconv binary;
437 either the path to the binary or its
438 containing directory.
439 --exec CMD Execute a command on the file after
00a41ca4
S		 440 downloading and post-processing, similar to
441 find's -exec syntax. Example: --exec 'adb
442 push {} /sdcard/Music/ && rm {}'
7de81fcc 443 --convert-subs FORMAT Convert the subtitles to other format
9fc41bcb 444 (currently supported: srt|ass|vtt|lrc)
6bcd846b 445
fork of https://github.com/yt-dlp/yt-dlp/