<!-- See: https://github.com/marketplace/actions/dynamic-badges -->
[](https://github.com/pukkandan/yt-dlp/releases/latest)
[](https://github.com/pukkandan/yt-dlp/blob/master/LICENSE)
-[](https://github.com/pukkandan/yt-dlp/actions?query=workflow%3ACore)
-[](https://github.com/pukkandan/yt-dlp/actions?query=workflow%3AFull)
+[](https://github.com/pukkandan/yt-dlp/actions)
A command-line program to download videos from youtube.com and many other [video platforms](docs/supportedsites.md)
* **[Format Sorting](#sorting-formats)**: The default format sorting options have been changed so that higher resolution and better codecs will be now preferred instead of simply using larger bitrate. Furthermore, you can now specify the sort order using `-S`. This allows for much easier format selection that what is possible by simply using `--format` ([examples](#format-selection-examples))
-* **Merged with youtube-dl v2021.01.08**: You get all the latest features and patches of [youtube-dl](https://github.com/ytdl-org/youtube-dl) in addition to all the features of [youtube-dlc](https://github.com/blackjack4494/yt-dlc)
+* **Merged with youtube-dl v2021.01.16**: You get all the latest features and patches of [youtube-dl](https://github.com/ytdl-org/youtube-dl) in addition to all the features of [youtube-dlc](https://github.com/blackjack4494/yt-dlc)
* **Youtube improvements**:
* All Youtube Feeds (`:ytfav`, `:ytwatchlater`, `:ytsubs`, `:ythistory`, `:ytrec`) works correctly and support downloading multiple pages of content
* Youtube search works correctly (`ytsearch:`, `ytsearchdate:`) along with Search URLs
* Redirect channel's home URL automatically to `/video` to preserve the old behaviour
-* **New extractors**: AnimeLab, Philo MSO, Rcs, Gedi, bitwave.tv
+* **New extractors**: Trovo.live, AnimeLab, Philo MSO, Rcs, Gedi, bitwave.tv
* **Fixed extractors**: archive.org, roosterteeth.com, skyit, instagram, itv, SouthparkDe, spreaker, Vlive, tiktok, akamai, ina
-* **New options**: `--list-formats-as-table`, `--write-link`, `--force-download-archive`, `--force-overwrites` etc
+* **New options**: `--list-formats-as-table`, `--write-link`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
-and many other features and patches. See [changelog](Changelog.md) or [commits](https://github.com/pukkandan/yt-dlp/commits) for the full list of changes
+* **Improvements**: Multiple `--postprocessor-args`, `%(duration_string)s` in `-o`, faster archive checking, more [format selection options](#format-selection) etc
+
+See [changelog](Changelog.md) or [commits](https://github.com/pukkandan/yt-dlp/commits) for the full list of changes
**PS**: Some of these changes are already in youtube-dlc, but are still unreleased. See [this](Changelog.md#unreleased-changes-in-blackjack4494yt-dlc) for details
compatibility) if this option is found
inside the system configuration file, the
user configuration is not loaded
- --config-location PATH Location of the configuration file; either
- the path to the config or its containing
- directory
+ --config-location PATH Location of the main configuration file;
+ either the path to the config or its
+ containing directory
--flat-playlist Do not extract the videos of a playlist,
only list them
--flat-videos Do not resolve the video urls
allowing to play the video while
downloading (some players may not be able
to play it)
- --external-downloader COMMAND Use the specified external downloader.
- Currently supports
- aria2c,avconv,axel,curl,ffmpeg,httpie,wget
- --external-downloader-args ARGS Give these arguments to the external
- downloader
+ --external-downloader NAME Use the specified external downloader.
+ Currently supports aria2c, avconv, axel,
+ curl, ffmpeg, httpie, wget
+ --downloader-args NAME:ARGS Give these arguments to the external
+ downloader. Specify the downloader name and
+ the arguments separated by a colon ":". You
+ can use this option multiple times (Alias:
+ --external-downloader-args)
## Filesystem Options:
-a, --batch-file FILE File containing URLs to download ('-' for
stdin), one URL per line. Lines starting
with '#', ';' or ']' are considered as
comments and ignored
+ -P, --paths TYPE:PATH The paths where the files should be
+ downloaded. Specify the type of file and
+ the path separated by a colon ":"
+ (supported: description|annotation|subtitle
+ |infojson|thumbnail). Additionally, you can
+ also provide "home" and "temp" paths. All
+ intermediary files are first downloaded to
+ the temp path and then the final files are
+ moved over to the home path after download
+ is finished. Note that this option is
+ ignored if --output is an absolute path
-o, --output TEMPLATE Output filename template, see "OUTPUT
TEMPLATE" for details
--autonumber-start NUMBER Specify the start value for %(autonumber)s
--referer URL Specify a custom referer, use if the video
access is restricted to one domain
--add-header FIELD:VALUE Specify a custom HTTP header and its value,
- separated by a colon ':'. You can use this
+ separated by a colon ":". You can use this
option multiple times
--bidi-workaround Work around terminals that lack
bidirectional text support. Requires bidiv
re-encoding is necessary (currently
supported: mp4|flv|ogg|webm|mkv|avi)
--postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
- Specify the postprocessor name and the
- arguments separated by a colon ':' to give
- the argument to only the specified
- postprocessor. Supported names are
+ Specify the postprocessor/executable name
+ and the arguments separated by a colon ":"
+ to give the argument to the specified
+ postprocessor/executable. Supported
+ postprocessors are: SponSkrub,
ExtractAudio, VideoRemuxer, VideoConvertor,
EmbedSubtitle, Metadata, Merger,
FixupStretched, FixupM4a, FixupM3u8,
- SubtitlesConvertor, EmbedThumbnail,
- XAttrMetadata, SponSkrub and Default. You
- can use this option multiple times to give
- different arguments to different
- postprocessors
+ SubtitlesConvertor and EmbedThumbnail. The
+ supported executables are: SponSkrub,
+ FFmpeg, FFprobe, avconf, avprobe and
+ AtomicParsley. You can use this option
+ multiple times to give different arguments
+ to different postprocessors. You can also
+ specify "PP+EXE:ARGS" to give the arguments
+ to the specified executable only when being
+ used by the specified postprocessor. You
+ can use this option multiple times (Alias:
+ --ppa)
-k, --keep-video Keep the intermediate video file on disk
after post-processing
--no-keep-video Delete the intermediate video file after
You can configure youtube-dlc by placing any supported command line option to a configuration file. The configuration is loaded from the following locations:
-1. The file given by `--config-location`
+1. **Main Configuration**: The file given by `--config-location`
1. **Portable Configuration**: `yt-dlp.conf` or `youtube-dlc.conf` in the same directory as the bundled binary. If you are running from source-code (`<root dir>/youtube_dlc/__main__.py`), the root directory is used instead.
+1. **Home Configuration**: `yt-dlp.conf` or `youtube-dlc.conf` in the home path given by `-P "home:<path>"`, or in the current directory if no such path is given
1. **User Configuration**:
* `%XDG_CONFIG_HOME%/yt-dlp/config` (recommended on Linux/macOS)
* `%XDG_CONFIG_HOME%/yt-dlp.conf`
# OUTPUT TEMPLATE
-The `-o` option allows users to indicate a template for the output file names.
+The `-o` option is used to indicate a template for the output file names while `-P` option is used to specify the path each type of file should be saved to.
**tl;dr:** [navigate me to examples](#output-template-examples).
You can change the criteria for being considered the `best` by using `-S` (`--format-sort`). The general format for this is `--format-sort field1,field2...`. The available fields are:
- - `video`, `has_video`: Gives priority to formats that has a video stream
- - `audio`, `has_audio`: Gives priority to formats that has a audio stream
- - `extractor`, `preference`, `extractor_preference`: The format preference as given by the extractor
- - `lang`, `language_preference`: Language preference as given by the extractor
+ - `hasvid`: Gives priority to formats that has a video stream
+ - `hasaud`: Gives priority to formats that has a audio stream
+ - `ie_pref`: The format preference as given by the extractor
+ - `lang`: Language preference as given by the extractor
- `quality`: The quality of the format. This is a metadata field available in some websites
- - `source`, `source_preference`: Preference of the source as given by the extractor
- - `proto`, `protocol`: Protocol used for download (`https`/`ftps` > `http`/`ftp` > `m3u8-native` > `m3u8` > `http-dash-segments` > other > `mms`/`rtsp` > unknown > `f4f`/`f4m`)
- - `vcodec`, `video_codec`: Video Codec (`vp9` > `h265` > `h264` > `vp8` > `h263` > `theora` > other > unknown)
- - `acodec`, `audio_codec`: Audio Codec (`opus` > `vorbis` > `aac` > `mp4a` > `mp3` > `ac3` > `dts` > other > unknown)
+ - `source`: Preference of the source as given by the extractor
+ - `proto`: Protocol used for download (`https`/`ftps` > `http`/`ftp` > `m3u8-native` > `m3u8` > `http-dash-segments` > other > `mms`/`rtsp` > unknown > `f4f`/`f4m`)
+ - `vcodec`: Video Codec (`vp9` > `h265` > `h264` > `vp8` > `h263` > `theora` > other > unknown)
+ - `acodec`: Audio Codec (`opus` > `vorbis` > `aac` > `mp4a` > `mp3` > `ac3` > `dts` > other > unknown)
- `codec`: Equivalent to `vcodec,acodec`
- - `vext`, `video_ext`: Video Extension (`mp4` > `webm` > `flv` > other > unknown). If `--prefer-free-formats` is used, `webm` is prefered.
- - `aext`, `audio_ext`: Audio Extension (`m4a` > `aac` > `mp3` > `ogg` > `opus` > `webm` > other > unknown). If `--prefer-free-formats` is used, the order changes to `opus` > `ogg` > `webm` > `m4a` > `mp3` > `aac`.
- - `ext`, `extension`: Equivalent to `vext,aext`
+ - `vext`: Video Extension (`mp4` > `webm` > `flv` > other > unknown). If `--prefer-free-formats` is used, `webm` is prefered.
+ - `aext`: Audio Extension (`m4a` > `aac` > `mp3` > `ogg` > `opus` > `webm` > other > unknown). If `--prefer-free-formats` is used, the order changes to `opus` > `ogg` > `webm` > `m4a` > `mp3` > `aac`.
+ - `ext`: Equivalent to `vext,aext`
- `filesize`: Exact filesize, if know in advance. This will be unavailable for mu38 and DASH formats.
- - `filesize_approx`: Approximate filesize calculated from the manifests
- - `size`, `filesize_estimate`: Exact filesize if available, otherwise approximate filesize
+ - `fs_approx`: Approximate filesize calculated from the manifests
+ - `size`: Exact filesize if available, otherwise approximate filesize
- `height`: Height of video
- `width`: Width of video
- - `res`, `dimension`: Video resolution, calculated as the smallest dimension.
- - `fps`, `framerate`: Framerate of video
- - `tbr`, `total_bitrate`: Total average bitrate in KBit/s
- - `vbr`, `video_bitrate`: Average video bitrate in KBit/s
- - `abr`, `audio_bitrate`: Average audio bitrate in KBit/s
- - `br`, `bitrate`: Equivalent to using `tbr,vbr,abr`
- - `samplerate`, `asr`: Audio sample rate in Hz
+ - `res`: Video resolution, calculated as the smallest dimension.
+ - `fps`: Framerate of video
+ - `tbr`: Total average bitrate in KBit/s
+ - `vbr`: Average video bitrate in KBit/s
+ - `abr`: Average audio bitrate in KBit/s
+ - `br`: Equivalent to using `tbr,vbr,abr`
+ - `asr`: Audio sample rate in Hz
Note that any other **numerical** field made available by the extractor can also be used. All fields, unless specified otherwise, are sorted in decending order. To reverse this, prefix the field with a `+`. Eg: `+res` prefers format with the smallest resolution. Additionally, you can suffix a prefered value for the fields, seperated by a `:`. Eg: `res:720` prefers larger videos, but no larger than 720p and the smallest video if there are no videos less than 720p. For `codec` and `ext`, you can provide two prefered values, the first for video and the second for audio. Eg: `+codec:avc:m4a` (equivalent to `+vcodec:avc,+acodec:m4a`) sets the video codec preference to `h264` > `h265` > `vp9` > `vp8` > `h263` > `theora` and audio codec preference to `mp4a` > `aac` > `vorbis` > `opus` > `mp3` > `ac3` > `dts`. You can also make the sorting prefer the nearest values to the provided by using `~` as the delimiter. Eg: `filesize~1G` prefers the format with filesize closest to 1 GiB.
-The fields `has_video`, `extractor`, `lang`, `quality` are always given highest priority in sorting, irrespective of the user-defined order. This behaviour can be changed by using `--force-format-sort`. Apart from these, the default order used is: `res,fps,codec,size,br,asr,proto,ext,has_audio,source,format_id`. Note that the extractors may override this default order, but they cannot override the user-provided order.
+The fields `hasvid`, `ie_pref`, `lang`, `quality` are always given highest priority in sorting, irrespective of the user-defined order. This behaviour can be changed by using `--force-format-sort`. Apart from these, the default order used is: `res,fps,codec,size,br,asr,proto,ext,hasaud,source,id`. Note that the extractors may override this default order, but they cannot override the user-provided order.
If your format selector is `worst`, the last item is selected after sorting. This means it will select the format that is worst in all repects. Most of the time, what you actually want is the video with the smallest filesize instead. So it is generally better to use `-f best -S +size,+br,+res,+fps`.
$ youtube-dlc -S '+res'
# Download the smallest video available
-$ youtube-dlc -S '+size,+bitrate'
+$ youtube-dlc -S '+size,+br'
# Download best video available via the best protocol
# (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
-$ youtube-dlc -S 'protocol'
+$ youtube-dlc -S 'proto'
projects / yt-dlp.git / blobdiff