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