# NEW FEATURES
-* Based on **youtube-dl 2021.12.17 [commit/6508688](https://github.com/ytdl-org/youtube-dl/commit/6508688e88c83bb811653083db9351702cd39a6a)** ([exceptions](https://github.com/yt-dlp/yt-dlp/issues/21)) and **youtube-dlc 2020.11.11-3 [commit/f9401f2](https://github.com/blackjack4494/yt-dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee)**: You get all the features and patches of [youtube-dlc](https://github.com/blackjack4494/yt-dlc) in addition to the latest [youtube-dl](https://github.com/ytdl-org/youtube-dl)
+* Merged with **youtube-dl v2021.12.17+ [commit/a03b977](https://github.com/ytdl-org/youtube-dl/commit/a03b9775d544b06a5b4f2aa630214c7c22fc2229)**<!--([exceptions](https://github.com/yt-dlp/yt-dlp/issues/21))--> and **youtube-dlc v2020.11.11-3+ [commit/f9401f2](https://github.com/blackjack4494/yt-dlc/commit/f9401f2a91987068139c5f757b12fc711d4c0cee)**: You get all the features and patches of [youtube-dlc](https://github.com/blackjack4494/yt-dlc) in addition to the latest [youtube-dl](https://github.com/ytdl-org/youtube-dl)
* **[SponsorBlock Integration](#sponsorblock-options)**: You can mark/remove sponsor sections in youtube videos by utilizing the [SponsorBlock](https://sponsor.ajay.app) API
* **Merged with animelover1984/youtube-dl**: You get most of the features and improvements from [animelover1984/youtube-dl](https://github.com/animelover1984/youtube-dl) including `--write-comments`, `BiliBiliSearch`, `BilibiliChannel`, Embedding thumbnail in mp4/ogg/opus, playlist infojson etc. Note that the NicoNico livestreams are not available. See [#31](https://github.com/yt-dlp/yt-dlp/pull/31) for details.
-* **Youtube improvements**:
- * All Feeds (`:ytfav`, `:ytwatchlater`, `:ytsubs`, `:ythistory`, `:ytrec`, `:ytnotif`) and private playlists supports downloading multiple pages of content
- * Search (`ytsearch:`, `ytsearchdate:`), search URLs and in-channel search works
- * Mixes supports downloading multiple pages of content
- * Some (but not all) age-gated content can be downloaded without cookies
- * Fix for [n-sig based throttling](https://github.com/ytdl-org/youtube-dl/issues/29326)
+* **YouTube improvements**:
+ * Supports Clips, Stories (`ytstories:<channel UCID>`), Search (including filters)**\***, YouTube Music Search, Channel-specific search, Search prefixes (`ytsearch:`, `ytsearchdate:`)**\***, Mixes, YouTube Music Albums/Channels ([except self-uploaded music](https://github.com/yt-dlp/yt-dlp/issues/723)), and Feeds (`:ytfav`, `:ytwatchlater`, `:ytsubs`, `:ythistory`, `:ytrec`, `:ytnotif`)
+ * Fix for [n-sig based throttling](https://github.com/ytdl-org/youtube-dl/issues/29326) **\***
+ * Supports some (but not all) age-gated content without cookies
+ * Download livestreams from the start using `--live-from-start` (*experimental*)
+ * `255kbps` audio is extracted (if available) from YouTube Music when premium cookies are given
* Redirect channel's home URL automatically to `/video` to preserve the old behaviour
- * `255kbps` audio is extracted (if available) from youtube music when premium cookies are given
- * Youtube music Albums, channels etc can be downloaded ([except self-uploaded music](https://github.com/yt-dlp/yt-dlp/issues/723))
- * Download livestreams from the start using `--live-from-start` (experimental)
* **Cookies from browser**: Cookies can be automatically extracted from all major web browsers using `--cookies-from-browser BROWSER[+KEYRING][:PROFILE]`
+* **Download time range**: Videos can be downloaded partially based on either timestamps or chapters using `--download-sections`
+
* **Split video by chapters**: Videos can be split into multiple files based on chapters using `--split-chapters`
* **Multi-threaded fragment downloads**: Download multiple fragments of m3u8/mpd videos in parallel. Use `--concurrent-fragments` (`-N`) option to set the number of threads used
* **New and fixed extractors**: Many new extractors have been added and a lot of existing ones have been fixed. See the [changelog](Changelog.md) or the [list of supported sites](supportedsites.md)
-* **New MSOs**: Philo, Spectrum, SlingTV, Cablevision, RCN
+* **New MSOs**: Philo, Spectrum, SlingTV, Cablevision, RCN etc.
* **Subtitle extraction from manifests**: Subtitles can be extracted from streaming media manifests. See [commit/be6202f](https://github.com/yt-dlp/yt-dlp/commit/be6202f12b97858b9d716e608394b51065d0419f) for details
* **Output template improvements**: Output templates can now have date-time formatting, numeric offsets, object traversal etc. See [output template](#output-template) for details. Even more advanced operations can also be done with the help of `--parse-metadata` and `--replace-in-metadata`
-* **Other new options**: Many new options have been added such as `--concat-playlist`, `--print`, `--wait-for-video`, `--sleep-requests`, `--convert-thumbnails`, `--write-link`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
+* **Other new options**: Many new options have been added such as `--alias`, `--print`, `--concat-playlist`, `--wait-for-video`, `--retry-sleep`, `--sleep-requests`, `--convert-thumbnails`, `--force-download-archive`, `--force-overwrites`, `--break-on-reject` etc
* **Improvements**: Regex and other operators in `--format`/`--match-filter`, multiple `--postprocessor-args` and `--downloader-args`, faster archive checking, more [format selection options](#format-selection), merge multi-video/audio, multiple `--config-locations`, `--exec` at different stages, etc
See [changelog](Changelog.md) or [commits](https://github.com/yt-dlp/yt-dlp/commits) for the full list of changes
+Features marked with a **\*** have been back-ported to youtube-dl
+
### Differences in default behavior
Some of yt-dlp's default options are different from that of youtube-dl and youtube-dlc:
* Some private fields such as filenames are removed by default from the infojson. Use `--no-clean-infojson` or `--compat-options no-clean-infojson` to revert this
* When `--embed-subs` and `--write-subs` are used together, the subtitles are written to disk and also embedded in the media file. You can use just `--embed-subs` to embed the subs and automatically delete the separate file. See [#630 (comment)](https://github.com/yt-dlp/yt-dlp/issues/630#issuecomment-893659460) for more info. `--compat-options no-keep-subs` can be used to revert this
* `certifi` will be used for SSL root certificates, if installed. If you want to use system certificates (e.g. self-signed), use `--compat-options no-certifi`
-* youtube-dl tries to remove some superfluous punctuations from filenames. While this can sometimes be helpfull, it is often undesirable. So yt-dlp tries to keep the fields in the filenames as close to their original values as possible. You can use `--compat-options filename-sanitization` to revert to youtube-dl's behavior
+* youtube-dl tries to remove some superfluous punctuations from filenames. While this can sometimes be helpful, it is often undesirable. So yt-dlp tries to keep the fields in the filenames as close to their original values as possible. You can use `--compat-options filename-sanitization` to revert to youtube-dl's behavior
For ease of use, a few more compat options are available:
-* `--compat-options all`: Use all compat options
+* `--compat-options all`: Use all compat options (Do NOT use)
* `--compat-options youtube-dl`: Same as `--compat-options all,-multistreams`
* `--compat-options youtube-dlc`: Same as `--compat-options all,-no-live-chat,-no-youtube-channel-redirect`
<!-- MANPAGE: BEGIN EXCLUDED SECTION -->
[](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe)
-[](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp)
+[](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp)
+[](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos)
[](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz)
[](#release-files)
[](https://github.com/yt-dlp/yt-dlp/releases)
python3 -m pip install --force-reinstall https://github.com/yt-dlp/yt-dlp/archive/master.tar.gz
```
-Note that on some systems, you may need to use `py` or `python` instead of `python3`
+On some systems, you may need to use `py` or `python` instead of `python3`
<!-- TODO: Add to Wiki, Remove Taps -->
### With [Homebrew](https://brew.sh)
File|Description
:---|:---
-[yt-dlp](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp)|Platform-independant binary. Needs Python (recommended for **Linux/BSD**)
+[yt-dlp](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp)|Platform-independent [zipimport](https://docs.python.org/3/library/zipimport.html) binary. Needs Python (recommended for **Linux/BSD**)
[yt-dlp.exe](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe)|Windows (Win7 SP1+) standalone x64 binary (recommended for **Windows**)
-[yt-dlp_macos](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos)|MacOS (10.15+) standalone executable (recommended for **MacOS**)
+[yt-dlp_macos](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos)|Universal MacOS (10.15+) standalone executable (recommended for **MacOS**)
#### Alternatives
File|Description
:---|:---
[yt-dlp_x86.exe](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_x86.exe)|Windows (Vista SP2+) standalone x86 (32-bit) binary
-[yt-dlp_min.exe](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_min.exe)|Windows (Win7 SP1+) standalone x64 binary built with `py2exe`.<br/> Does not contain `pycryptodomex`, needs VC++14
+[yt-dlp_min.exe](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_min.exe)|Windows (Win7 SP1+) standalone x64 binary built with `py2exe`<br/> ([Not recommended](#standalone-py2exe-builds-windows))
+[yt-dlp_linux](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux)|Linux standalone x64 binary
+[yt-dlp_linux.zip](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux.zip)|Unpackaged Linux executable (no auto-update)
[yt-dlp_win.zip](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_win.zip)|Unpackaged Windows executable (no auto-update)
[yt-dlp_macos.zip](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos.zip)|Unpackaged MacOS (10.15+) executable (no auto-update)
+[yt-dlp_macos_legacy](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos_legacy)|MacOS (10.9+) standalone x64 executable
#### Misc
<!-- MANPAGE: END EXCLUDED SECTION -->
## DEPENDENCIES
-Python versions 3.6+ (CPython and PyPy) are supported. Other versions and implementations may or may not work correctly.
+Python versions 3.7+ (CPython and PyPy) are supported. Other versions and implementations may or may not work correctly.
<!-- Python 3.5+ uses VC++14 and it is already embedded in the binary created
<!x-- https://www.microsoft.com/en-us/download/details.aspx?id=26999 --x>
While all the other dependencies are optional, `ffmpeg` and `ffprobe` are highly recommended
+### Strongly recommended
+
* [**ffmpeg** and **ffprobe**](https://www.ffmpeg.org) - Required for [merging separate video and audio files](#format-selection) as well as for various [post-processing](#post-processing-options) tasks. License [depends on the build](https://www.ffmpeg.org/legal.html)
-* [**mutagen**](https://github.com/quodlibet/mutagen)\* - For embedding thumbnail in certain formats. Licensed under [GPLv2+](https://github.com/quodlibet/mutagen/blob/master/COPYING)
-* [**pycryptodomex**](https://github.com/Legrandin/pycryptodome)\* - For decrypting AES-128 HLS streams and various other data. Licensed under [BSD-2-Clause](https://github.com/Legrandin/pycryptodome/blob/master/LICENSE.rst)
-* [**websockets**](https://github.com/aaugustin/websockets)\* - For downloading over websocket. Licensed under [BSD-3-Clause](https://github.com/aaugustin/websockets/blob/main/LICENSE)
-* [**secretstorage**](https://github.com/mitya57/secretstorage)\* - For accessing the Gnome keyring while decrypting cookies of Chromium-based browsers on Linux. Licensed under [BSD-3-Clause](https://github.com/mitya57/secretstorage/blob/master/LICENSE)
-* [**brotli**](https://github.com/google/brotli)\* or [**brotlicffi**](https://github.com/python-hyper/brotlicffi) - [Brotli](https://en.wikipedia.org/wiki/Brotli) content encoding support. Both licensed under MIT <sup>[1](https://github.com/google/brotli/blob/master/LICENSE) [2](https://github.com/python-hyper/brotlicffi/blob/master/LICENSE) </sup>
+
+ <!-- TODO: ffmpeg has merged this patch. Remove this note once there is new release -->
+ **Note**: There are some regressions in newer ffmpeg versions that causes various issues when used alongside yt-dlp. Since ffmpeg is such an important dependency, we provide [custom builds](https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-static-auto-builds) with patches for these issues at [yt-dlp/FFmpeg-Builds](https://github.com/yt-dlp/FFmpeg-Builds). See [the readme](https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for details on the specific issues solved by these builds
+
+### Networking
* [**certifi**](https://github.com/certifi/python-certifi)\* - Provides Mozilla's root certificate bundle. Licensed under [MPLv2](https://github.com/certifi/python-certifi/blob/master/LICENSE)
-* [**AtomicParsley**](https://github.com/wez/atomicparsley) - For embedding thumbnail in mp4/m4a if mutagen/ffmpeg cannot. Licensed under [GPLv2+](https://github.com/wez/atomicparsley/blob/master/COPYING)
-* [**rtmpdump**](http://rtmpdump.mplayerhq.hu) - For downloading `rtmp` streams. ffmpeg will be used as a fallback. Licensed under [GPLv2+](http://rtmpdump.mplayerhq.hu)
-* [**mplayer**](http://mplayerhq.hu/design7/info.html) or [**mpv**](https://mpv.io) - For downloading `rstp` streams. ffmpeg will be used as a fallback. Licensed under [GPLv2+](https://github.com/mpv-player/mpv/blob/master/Copyright)
+* [**brotli**](https://github.com/google/brotli)\* or [**brotlicffi**](https://github.com/python-hyper/brotlicffi) - [Brotli](https://en.wikipedia.org/wiki/Brotli) content encoding support. Both licensed under MIT <sup>[1](https://github.com/google/brotli/blob/master/LICENSE) [2](https://github.com/python-hyper/brotlicffi/blob/master/LICENSE) </sup>
+* [**websockets**](https://github.com/aaugustin/websockets)\* - For downloading over websocket. Licensed under [BSD-3-Clause](https://github.com/aaugustin/websockets/blob/main/LICENSE)
+
+### Metadata
+
+* [**mutagen**](https://github.com/quodlibet/mutagen)\* - For `--embed-thumbnail` in certain formats. Licensed under [GPLv2+](https://github.com/quodlibet/mutagen/blob/master/COPYING)
+* [**AtomicParsley**](https://github.com/wez/atomicparsley) - For `--embed-thumbnail` in `mp4`/`m4a` files when `mutagen`/`ffmpeg` cannot. Licensed under [GPLv2+](https://github.com/wez/atomicparsley/blob/master/COPYING)
+* [**xattr**](https://github.com/xattr/xattr), [**pyxattr**](https://github.com/iustin/pyxattr) or [**setfattr**](http://savannah.nongnu.org/projects/attr) - For writing xattr metadata (`--xattr`) on **Linux**. Licensed under [MIT](https://github.com/xattr/xattr/blob/master/LICENSE.txt), [LGPL2.1](https://github.com/iustin/pyxattr/blob/master/COPYING) and [GPLv2+](http://git.savannah.nongnu.org/cgit/attr.git/tree/doc/COPYING) respectively
+
+### Misc
+
+* [**pycryptodomex**](https://github.com/Legrandin/pycryptodome)\* - For decrypting AES-128 HLS streams and various other data. Licensed under [BSD-2-Clause](https://github.com/Legrandin/pycryptodome/blob/master/LICENSE.rst)
* [**phantomjs**](https://github.com/ariya/phantomjs) - Used in extractors where javascript needs to be run. Licensed under [BSD-3-Clause](https://github.com/ariya/phantomjs/blob/master/LICENSE.BSD)
-* [**sponskrub**](https://github.com/faissaloo/SponSkrub) - For using the now **deprecated** [sponskrub options](#sponskrub-options). Licensed under [GPLv3+](https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
+* [**secretstorage**](https://github.com/mitya57/secretstorage) - For `--cookies-from-browser` to access the **Gnome** keyring while decrypting cookies of **Chromium**-based browsers on **Linux**. Licensed under [BSD-3-Clause](https://github.com/mitya57/secretstorage/blob/master/LICENSE)
* Any external downloader that you want to use with `--downloader`
+#### Deprecated
+
+* [**avconv** and **avprobe**](https://www.libav.org) - Now **deprecated** alternative to ffmpeg. License [depends on the build](https://libav.org/legal)
+* [**sponskrub**](https://github.com/faissaloo/SponSkrub) - For using the now **deprecated** [sponskrub options](#sponskrub-options). Licensed under [GPLv3+](https://github.com/faissaloo/SponSkrub/blob/master/LICENCE.md)
+* [**rtmpdump**](http://rtmpdump.mplayerhq.hu) - For downloading `rtmp` streams. ffmpeg can be used instead with `--downloader ffmpeg`. Licensed under [GPLv2+](http://rtmpdump.mplayerhq.hu)
+* [**mplayer**](http://mplayerhq.hu/design7/info.html) or [**mpv**](https://mpv.io) - For downloading `rstp`/`mms` streams. ffmpeg can be used instead with `--downloader ffmpeg`. Licensed under [GPLv2+](https://github.com/mpv-player/mpv/blob/master/Copyright)
+
To use or redistribute the dependencies, you must agree to their respective licensing terms.
-The Windows and MacOS standalone release binaries are already built with the python interpreter and all optional python packages (marked with \*) included.
+The standalone release binaries are built with the Python interpreter and the packages marked with **\*** included.
-<!-- TODO: ffmpeg has merged this patch. Remove this note once there is new release -->
-**Note**: There are some regressions in newer ffmpeg versions that causes various issues when used alongside yt-dlp. Since ffmpeg is such an important dependency, we provide [custom builds](https://github.com/yt-dlp/FFmpeg-Builds#ffmpeg-static-auto-builds) with patches for these issues at [yt-dlp/FFmpeg-Builds](https://github.com/yt-dlp/FFmpeg-Builds). See [the readme](https://github.com/yt-dlp/FFmpeg-Builds#patches-applied) for details on the specific issues solved by these builds
+If you do not have the necessary dependencies for a task you are attempting, yt-dlp will warn you. All the currently available dependencies are visible at the top of the `--verbose` output
## COMPILE
-**For Windows**:
-To build the Windows executable, you must have pyinstaller (and any of yt-dlp's optional dependencies if needed). Once you have all the necessary dependencies installed, (optionally) build lazy extractors using `devscripts/make_lazy_extractors.py`, and then just run `pyinst.py`. The executable will be built for the same architecture (32/64 bit) as the python used to build it.
+### Standalone PyInstaller Builds
+To build the Windows/MacOS executable, you must have Python and `pyinstaller` (plus any of yt-dlp's [optional dependencies](#dependencies) if needed). Once you have all the necessary dependencies installed, simply run `pyinst.py`. The executable will be built for the same architecture (32/64 bit) as the Python used.
- py -m pip install -U pyinstaller -r requirements.txt
- py devscripts/make_lazy_extractors.py
- py pyinst.py
+ python3 -m pip install -U pyinstaller -r requirements.txt
+ python3 devscripts/make_lazy_extractors.py
+ python3 pyinst.py
+
+On some systems, you may need to use `py` or `python` instead of `python3`.
+
+Note that pyinstaller [does not support](https://github.com/pyinstaller/pyinstaller#requirements-and-tested-platforms) Python installed from the Windows store without using a virtual environment.
+
+**Important**: Running `pyinstaller` directly **without** using `pyinst.py` is **not** officially supported. This may or may not work correctly.
-Note that pyinstaller [does not support](https://github.com/pyinstaller/pyinstaller#requirements-and-tested-platforms) Python installed from the Windows store without using a virtual environment
+### Platform-independent Binary (UNIX)
+You will need the build tools `python` (3.6+), `zip`, `make` (GNU), `pandoc`\* and `pytest`\*.
-**For Unix**:
-You will need the required build tools: `python`, `make` (GNU), `pandoc`, `zip`, `pytest`
-Then simply run `make`. You can also run `make yt-dlp` instead to compile only the binary without updating any of the additional files
+After installing these, simply run `make`.
-**Note**: In either platform, `devscripts/update-version.py` can be used to automatically update the version number
+You can also run `make yt-dlp` instead to compile only the binary without updating any of the additional files. (The dependencies marked with **\*** are not needed for this)
-You can also fork the project on github and run your fork's [build workflow](.github/workflows/build.yml) to automatically build a release
+### Standalone Py2Exe Builds (Windows)
+
+While we provide the option to build with [py2exe](https://www.py2exe.org), it is recommended to build [using PyInstaller](#standalone-pyinstaller-builds) instead since the py2exe builds **cannot contain `pycryptodomex`/`certifi` and needs VC++14** on the target computer to run.
+
+If you wish to build it anyway, install Python and py2exe, and then simply run `setup.py py2exe`
+
+ py -m pip install -U py2exe -r requirements.txt
+ py devscripts/make_lazy_extractors.py
+ py setup.py py2exe
+
+### Related scripts
+
+* **`devscripts/update-version.py`** - Update the version number based on current timestamp
+* **`devscripts/make_lazy_extractors.py`** - Create lazy extractors. Running this before building the binaries (any variant) will improve their startup performance. Set the environment variable `YTDLP_NO_LAZY_EXTRACTORS=1` if you wish to forcefully disable lazy extractor loading.
+
+You can also fork the project on github and run your fork's [build workflow](.github/workflows/build.yml) to automatically build a full release
# USAGE AND OPTIONS
<!-- Auto generated -->
## General Options:
- -h, --help Print this help text and exit
- --version Print program version and exit
- -U, --update Update this program to latest version. Make
- sure that you have sufficient permissions
- (run with sudo if needed)
- -i, --ignore-errors Ignore download and postprocessing errors.
- The download will be considered successful
- even if the postprocessing fails
- --no-abort-on-error Continue with next video on download
- errors; e.g. to skip unavailable videos in
- a playlist (default)
- --abort-on-error Abort downloading of further videos if an
- error occurs (Alias: --no-ignore-errors)
- --dump-user-agent Display the current user-agent and exit
- --list-extractors List all supported extractors and exit
- --extractor-descriptions Output descriptions of all supported
- extractors and exit
- --force-generic-extractor Force extraction to use the generic
- extractor
- --default-search PREFIX Use this prefix for unqualified URLs. For
- example "gvsearch2:" downloads two videos
- from google videos for the search term
- "large apple". Use the value "auto" to let
- yt-dlp guess ("auto_warning" to emit a
- warning when guessing). "error" just throws
- an error. The default value "fixup_error"
- repairs broken URLs, but emits an error if
- this is not possible instead of searching
- --ignore-config Don't load any more configuration files
- except those given by --config-locations.
- For backward compatibility, if this option
- is found inside the system configuration
- file, the user configuration is not loaded.
- (Alias: --no-config)
- --no-config-locations Do not load any custom configuration files
- (default). When given inside a
- configuration file, ignore all previous
- --config-locations defined in the current
- file
- --config-locations PATH Location of the main configuration file;
- either the path to the config or its
- containing directory. Can be used multiple
- times and inside other configuration files
- --flat-playlist Do not extract the videos of a playlist,
- only list them
- --no-flat-playlist Extract the videos of a playlist
- --live-from-start Download livestreams from the start.
- Currently only supported for YouTube
- (Experimental)
- --no-live-from-start Download livestreams from the current time
- (default)
- --wait-for-video MIN[-MAX] Wait for scheduled streams to become
- available. Pass the minimum number of
- seconds (or range) to wait between retries
- --no-wait-for-video Do not wait for scheduled streams (default)
- --mark-watched Mark videos watched (even with --simulate)
- --no-mark-watched Do not mark videos watched (default)
- --no-colors Do not emit color codes in output
- --compat-options OPTS Options that can help keep compatibility
- with youtube-dl or youtube-dlc
- configurations by reverting some of the
- changes made in yt-dlp. See "Differences in
- default behavior" for details
+ -h, --help Print this help text and exit
+ --version Print program version and exit
+ -U, --update Update this program to latest version
+ --no-update Do not update (default)
+ -i, --ignore-errors Ignore download and postprocessing errors.
+ The download will be considered successful
+ even if the postprocessing fails
+ --no-abort-on-error Continue with next video on download errors;
+ e.g. to skip unavailable videos in a
+ playlist (default)
+ --abort-on-error Abort downloading of further videos if an
+ error occurs (Alias: --no-ignore-errors)
+ --dump-user-agent Display the current user-agent and exit
+ --list-extractors List all supported extractors and exit
+ --extractor-descriptions Output descriptions of all supported
+ extractors and exit
+ --force-generic-extractor Force extraction to use the generic extractor
+ --default-search PREFIX Use this prefix for unqualified URLs. Eg:
+ "gvsearch2:python" downloads two videos from
+ google videos for the search term "python".
+ Use the value "auto" to let yt-dlp guess
+ ("auto_warning" to emit a warning when
+ guessing). "error" just throws an error. The
+ default value "fixup_error" repairs broken
+ URLs, but emits an error if this is not
+ possible instead of searching
+ --ignore-config Don't load any more configuration files
+ except those given by --config-locations.
+ For backward compatibility, if this option
+ is found inside the system configuration
+ file, the user configuration is not loaded.
+ (Alias: --no-config)
+ --no-config-locations Do not load any custom configuration files
+ (default). When given inside a configuration
+ file, ignore all previous --config-locations
+ defined in the current file
+ --config-locations PATH Location of the main configuration file;
+ either the path to the config or its
+ containing directory ("-" for stdin). Can be
+ used multiple times and inside other
+ configuration files
+ --flat-playlist Do not extract the videos of a playlist,
+ only list them
+ --no-flat-playlist Extract the videos of a playlist
+ --live-from-start Download livestreams from the start.
+ Currently only supported for YouTube
+ (Experimental)
+ --no-live-from-start Download livestreams from the current time
+ (default)
+ --wait-for-video MIN[-MAX] Wait for scheduled streams to become
+ available. Pass the minimum number of
+ seconds (or range) to wait between retries
+ --no-wait-for-video Do not wait for scheduled streams (default)
+ --mark-watched Mark videos watched (even with --simulate)
+ --no-mark-watched Do not mark videos watched (default)
+ --no-colors Do not emit color codes in output (Alias:
+ --no-colours)
+ --compat-options OPTS Options that can help keep compatibility
+ with youtube-dl or youtube-dlc
+ configurations by reverting some of the
+ changes made in yt-dlp. See "Differences in
+ default behavior" for details
+ --alias ALIASES OPTIONS Create aliases for an option string. Unless
+ an alias starts with a dash "-", it is
+ prefixed with "--". Arguments are parsed
+ according to the Python string formatting
+ mini-language. Eg: --alias get-audio,-X
+ "-S=aext:{0},abr -x --audio-format {0}"
+ creates options "--get-audio" and "-X" that
+ takes an argument (ARG0) and expands to
+ "-S=aext:ARG0,abr -x --audio-format ARG0".
+ All defined aliases are listed in the --help
+ output. Alias options can trigger more
+ aliases; so be careful to avoid defining
+ recursive options. As a safety measure, each
+ alias may be triggered a maximum of 100
+ times. This option can be used multiple times
## Network Options:
- --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy.
- To enable SOCKS proxy, specify a proper
- scheme. For example
- socks5://user:pass@127.0.0.1:1080/. Pass in
- an empty string (--proxy "") for direct
- connection
- --socket-timeout SECONDS Time to wait before giving up, in seconds
- --source-address IP Client-side IP address to bind to
- -4, --force-ipv4 Make all connections via IPv4
- -6, --force-ipv6 Make all connections via IPv6
+ --proxy URL Use the specified HTTP/HTTPS/SOCKS proxy. To
+ enable SOCKS proxy, specify a proper scheme.
+ Eg: socks5://user:pass@127.0.0.1:1080/. Pass
+ in an empty string (--proxy "") for direct
+ connection
+ --socket-timeout SECONDS Time to wait before giving up, in seconds
+ --source-address IP Client-side IP address to bind to
+ -4, --force-ipv4 Make all connections via IPv4
+ -6, --force-ipv6 Make all connections via IPv6
## Geo-restriction:
- --geo-verification-proxy URL Use this proxy to verify the IP address for
- some geo-restricted sites. The default
- proxy specified by --proxy (or none, if the
- option is not present) is used for the
- actual downloading
- --geo-bypass Bypass geographic restriction via faking
- X-Forwarded-For HTTP header (default)
- --no-geo-bypass Do not bypass geographic restriction via
- faking X-Forwarded-For HTTP header
- --geo-bypass-country CODE Force bypass geographic restriction with
- explicitly provided two-letter ISO 3166-2
- country code
- --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
- explicitly provided IP block in CIDR
- notation
+ --geo-verification-proxy URL Use this proxy to verify the IP address for
+ some geo-restricted sites. The default proxy
+ specified by --proxy (or none, if the option
+ is not present) is used for the actual
+ downloading
+ --geo-bypass Bypass geographic restriction via faking
+ X-Forwarded-For HTTP header (default)
+ --no-geo-bypass Do not bypass geographic restriction via
+ faking X-Forwarded-For HTTP header
+ --geo-bypass-country CODE Force bypass geographic restriction with
+ explicitly provided two-letter ISO 3166-2
+ country code
+ --geo-bypass-ip-block IP_BLOCK Force bypass geographic restriction with
+ explicitly provided IP block in CIDR notation
## Video Selection:
- --playlist-start NUMBER Playlist video to start at (default is 1)
- --playlist-end NUMBER Playlist video to end at (default is last)
- --playlist-items ITEM_SPEC Playlist video items to download. Specify
- indices of the videos in the playlist
- separated by commas like: "--playlist-items
- 1,2,5,8" if you want to download videos
- indexed 1, 2, 5, 8 in the playlist. You can
- specify range: "--playlist-items
- 1-3,7,10-13", it will download the videos
- at index 1, 2, 3, 7, 10, 11, 12 and 13
- --min-filesize SIZE Do not download any videos smaller than
- SIZE (e.g. 50k or 44.6m)
- --max-filesize SIZE Do not download any videos larger than SIZE
- (e.g. 50k or 44.6m)
- --date DATE Download only videos uploaded on this date.
- The date can be "YYYYMMDD" or in the format
- "(now|today)[+-][0-9](day|week|month|year)(s)?"
- --datebefore DATE Download only videos uploaded on or before
- this date. The date formats accepted is the
- same as --date
- --dateafter DATE Download only videos uploaded on or after
- this date. The date formats accepted is the
- same as --date
- --match-filters FILTER Generic video filter. Any field (see
- "OUTPUT TEMPLATE") can be compared with a
- number or a string using the operators
- defined in "Filtering formats". You can
- also simply specify a field to match if the
- field is present, use "!field" to check if
- the field is not present, and "&" to check
- multiple conditions. Use a "\" to escape
- "&" or quotes if needed. If used multiple
- times, the filter matches if atleast one of
- the conditions are met. Eg: --match-filter
- !is_live --match-filter "like_count>?100 &
- description~='(?i)\bcats \& dogs\b'"
- matches only videos that are not live OR
- those that have a like count more than 100
- (or the like field is not available) and
- also has a description that contains the
- phrase "cats & dogs" (ignoring case). Use
- "--match-filter -" to interactively ask
- whether to download each video
- --no-match-filter Do not use generic video filter (default)
- --no-playlist Download only the video, if the URL refers
- to a video and a playlist
- --yes-playlist Download the playlist, if the URL refers to
- a video and a playlist
- --age-limit YEARS Download only videos suitable for the given
- age
- --download-archive FILE Download only videos not listed in the
- archive file. Record the IDs of all
- downloaded videos in it
- --no-download-archive Do not use archive file (default)
- --max-downloads NUMBER Abort after downloading NUMBER files
- --break-on-existing Stop the download process when encountering
- a file that is in the archive
- --break-on-reject Stop the download process when encountering
- a file that has been filtered out
- --break-per-input Make --break-on-existing and --break-on-
- reject act only on the current input URL
- --no-break-per-input --break-on-existing and --break-on-reject
- terminates the entire download queue
- --skip-playlist-after-errors N Number of allowed failures until the rest
- of the playlist is skipped
+ -I, --playlist-items ITEM_SPEC Comma separated playlist_index of the videos
+ to download. You can specify a range using
+ "[START]:[STOP][:STEP]". For backward
+ compatibility, START-STOP is also supported.
+ Use negative indices to count from the right
+ and negative STEP to download in reverse
+ order. Eg: "-I 1:3,7,-5::2" used on a
+ playlist of size 15 will download the videos
+ at index 1,2,3,7,11,13,15
+ --min-filesize SIZE Do not download any videos smaller than SIZE
+ (e.g. 50k or 44.6m)
+ --max-filesize SIZE Do not download any videos larger than SIZE
+ (e.g. 50k or 44.6m)
+ --date DATE Download only videos uploaded on this date.
+ The date can be "YYYYMMDD" or in the format
+ [now|today|yesterday][-N[day|week|month|year]].
+ Eg: --date today-2weeks
+ --datebefore DATE Download only videos uploaded on or before
+ this date. The date formats accepted is the
+ same as --date
+ --dateafter DATE Download only videos uploaded on or after
+ this date. The date formats accepted is the
+ same as --date
+ --match-filters FILTER Generic video filter. Any "OUTPUT TEMPLATE"
+ field can be compared with a number or a
+ string using the operators defined in
+ "Filtering formats". You can also simply
+ specify a field to match if the field is
+ present, use "!field" to check if the field
+ is not present, and "&" to check multiple
+ conditions. Use a "\" to escape "&" or
+ quotes if needed. If used multiple times,
+ the filter matches if atleast one of the
+ conditions are met. Eg: --match-filter
+ !is_live --match-filter "like_count>?100 &
+ description~='(?i)\bcats \& dogs\b'" matches
+ only videos that are not live OR those that
+ have a like count more than 100 (or the like
+ field is not available) and also has a
+ description that contains the phrase "cats &
+ dogs" (caseless). Use "--match-filter -" to
+ interactively ask whether to download each
+ video
+ --no-match-filter Do not use generic video filter (default)
+ --no-playlist Download only the video, if the URL refers
+ to a video and a playlist
+ --yes-playlist Download the playlist, if the URL refers to
+ a video and a playlist
+ --age-limit YEARS Download only videos suitable for the given
+ age
+ --download-archive FILE Download only videos not listed in the
+ archive file. Record the IDs of all
+ downloaded videos in it
+ --no-download-archive Do not use archive file (default)
+ --max-downloads NUMBER Abort after downloading NUMBER files
+ --break-on-existing Stop the download process when encountering
+ a file that is in the archive
+ --break-on-reject Stop the download process when encountering
+ a file that has been filtered out
+ --break-per-input Make --break-on-existing, --break-on-reject
+ and --max-downloads act only on the current
+ input URL
+ --no-break-per-input --break-on-existing and similar options
+ terminates the entire download queue
+ --skip-playlist-after-errors N Number of allowed failures until the rest of
+ the playlist is skipped
## Download Options:
- -N, --concurrent-fragments N Number of fragments of a dash/hlsnative
- video that should be downloaded
- concurrently (default is 1)
- -r, --limit-rate RATE Maximum download rate in bytes per second
- (e.g. 50K or 4.2M)
- --throttled-rate RATE Minimum download rate in bytes per second
- below which throttling is assumed and the
- video data is re-extracted (e.g. 100K)
- -R, --retries RETRIES Number of retries (default is 10), or
- "infinite"
- --file-access-retries RETRIES Number of times to retry on file access
- error (default is 3), or "infinite"
- --fragment-retries RETRIES Number of retries for a fragment (default
- is 10), or "infinite" (DASH, hlsnative and
- ISM)
- --skip-unavailable-fragments Skip unavailable fragments for DASH,
- hlsnative and ISM (default)
- (Alias: --no-abort-on-unavailable-fragment)
- --abort-on-unavailable-fragment Abort downloading if a fragment is unavailable
- (Alias: --no-skip-unavailable-fragments)
- --keep-fragments Keep downloaded fragments on disk after
- downloading is finished
- --no-keep-fragments Delete downloaded fragments after
- downloading is finished (default)
- --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
- (default is 1024)
- --resize-buffer The buffer size is automatically resized
- from an initial value of --buffer-size
- (default)
- --no-resize-buffer Do not automatically adjust the buffer size
- --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
- downloading (e.g. 10485760 or 10M) (default
- is disabled). May be useful for bypassing
- bandwidth throttling imposed by a webserver
- (experimental)
- --playlist-reverse Download playlist videos in reverse order
- --no-playlist-reverse Download playlist videos in default order
- (default)
- --playlist-random Download playlist videos in random order
- --xattr-set-filesize Set file xattribute ytdl.filesize with
- expected file size
- --hls-use-mpegts Use the mpegts container for HLS videos;
- allowing some players to play the video
- while downloading, and reducing the chance
- of file corruption if download is
- interrupted. This is enabled by default for
- live streams
- --no-hls-use-mpegts Do not use the mpegts container for HLS
- videos. This is default when not
- downloading live streams
- --downloader [PROTO:]NAME Name or path of the external downloader to
- use (optionally) prefixed by the protocols
- (http, ftp, m3u8, dash, rstp, rtmp, mms) to
- use it for. Currently supports native,
- aria2c, avconv, axel, curl, ffmpeg, httpie,
- wget (Recommended: aria2c). You can use
- this option multiple times to set different
- downloaders for different protocols. For
- example, --downloader aria2c --downloader
- "dash,m3u8:native" will use aria2c for
- http/ftp downloads, and the native
- downloader for dash/m3u8 downloads (Alias:
- --external-downloader)
- --downloader-args NAME:ARGS Give these arguments to the external
- downloader. Specify the downloader name and
- the arguments separated by a colon ":". For
- ffmpeg, arguments can be passed to
- different positions using the same syntax
- as --postprocessor-args. You can use this
- option multiple times to give different
- arguments to different downloaders (Alias:
- --external-downloader-args)
+ -N, --concurrent-fragments N Number of fragments of a dash/hlsnative
+ video that should be downloaded concurrently
+ (default is 1)
+ -r, --limit-rate RATE Maximum download rate in bytes per second
+ (e.g. 50K or 4.2M)
+ --throttled-rate RATE Minimum download rate in bytes per second
+ below which throttling is assumed and the
+ video data is re-extracted (e.g. 100K)
+ -R, --retries RETRIES Number of retries (default is 10), or
+ "infinite"
+ --file-access-retries RETRIES Number of times to retry on file access
+ error (default is 3), or "infinite"
+ --fragment-retries RETRIES Number of retries for a fragment (default is
+ 10), or "infinite" (DASH, hlsnative and ISM)
+ --retry-sleep [TYPE:]EXPR An expression for the time to sleep between
+ retries in seconds (optionally) prefixed by
+ the type of retry (file_access, fragment,
+ http (default)) to apply the sleep to. EXPR
+ can be a number, linear=START[:END[:STEP=1]]
+ or exp=START[:END[:BASE=2]]. This option can
+ be used multiple times to set the sleep for
+ the different retry types. Eg: --retry-sleep
+ linear=1::2 --retry-sleep fragment:exp=1:20
+ --skip-unavailable-fragments Skip unavailable fragments for DASH,
+ hlsnative and ISM downloads (default)
+ (Alias: --no-abort-on-unavailable-fragment)
+ --abort-on-unavailable-fragment
+ Abort download if a fragment is unavailable
+ (Alias: --no-skip-unavailable-fragments)
+ --keep-fragments Keep downloaded fragments on disk after
+ downloading is finished
+ --no-keep-fragments Delete downloaded fragments after
+ downloading is finished (default)
+ --buffer-size SIZE Size of download buffer (e.g. 1024 or 16K)
+ (default is 1024)
+ --resize-buffer The buffer size is automatically resized
+ from an initial value of --buffer-size
+ (default)
+ --no-resize-buffer Do not automatically adjust the buffer size
+ --http-chunk-size SIZE Size of a chunk for chunk-based HTTP
+ downloading (e.g. 10485760 or 10M) (default
+ is disabled). May be useful for bypassing
+ bandwidth throttling imposed by a webserver
+ (experimental)
+ --playlist-random Download playlist videos in random order
+ --lazy-playlist Process entries in the playlist as they are
+ received. This disables n_entries,
+ --playlist-random and --playlist-reverse
+ --no-lazy-playlist Process videos in the playlist only after
+ the entire playlist is parsed (default)
+ --xattr-set-filesize Set file xattribute ytdl.filesize with
+ expected file size
+ --hls-use-mpegts Use the mpegts container for HLS videos;
+ allowing some players to play the video
+ while downloading, and reducing the chance
+ of file corruption if download is
+ interrupted. This is enabled by default for
+ live streams
+ --no-hls-use-mpegts Do not use the mpegts container for HLS
+ videos. This is default when not downloading
+ live streams
+ --download-sections REGEX Download only chapters whose title matches
+ the given regular expression. Time ranges
+ prefixed by a "*" can also be used in place
+ of chapters to download the specified range.
+ Eg: --download-sections "*10:15-15:00"
+ --download-sections "intro". Needs ffmpeg.
+ This option can be used multiple times to
+ download multiple sections
+ --downloader [PROTO:]NAME Name or path of the external downloader to
+ use (optionally) prefixed by the protocols
+ (http, ftp, m3u8, dash, rstp, rtmp, mms) to
+ use it for. Currently supports native,
+ aria2c, avconv, axel, curl, ffmpeg, httpie,
+ wget. You can use this option multiple times
+ to set different downloaders for different
+ protocols. For example, --downloader aria2c
+ --downloader "dash,m3u8:native" will use
+ aria2c for http/ftp downloads, and the
+ native downloader for dash/m3u8 downloads
+ (Alias: --external-downloader)
+ --downloader-args NAME:ARGS Give these arguments to the external
+ downloader. Specify the downloader name and
+ the arguments separated by a colon ":". For
+ ffmpeg, arguments can be passed to different
+ positions using the same syntax as
+ --postprocessor-args. You can use this
+ option multiple times to give different
+ arguments to different downloaders (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
- --no-batch-file Do not read URLs from batch file (default)
- -P, --paths [TYPES:]PATH The paths where the files should be
- downloaded. Specify the type of file and
- the path separated by a colon ":". All the
- same TYPES as --output are supported.
- Additionally, you can also provide "home"
- (default) 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. This option is ignored if
- --output is an absolute path
- -o, --output [TYPES:]TEMPLATE Output filename template; see "OUTPUT
- TEMPLATE" for details
- --output-na-placeholder TEXT Placeholder value for unavailable meta
- fields in output filename template
- (default: "NA")
- --restrict-filenames Restrict filenames to only ASCII
- characters, and avoid "&" and spaces in
- filenames
- --no-restrict-filenames Allow Unicode characters, "&" and spaces in
- filenames (default)
- --windows-filenames Force filenames to be Windows-compatible
- --no-windows-filenames Make filenames Windows-compatible only if
- using Windows (default)
- --trim-filenames LENGTH Limit the filename length (excluding
- extension) to the specified number of
- characters
- -w, --no-overwrites Do not overwrite any files
- --force-overwrites Overwrite all video and metadata files.
- This option includes --no-continue
- --no-force-overwrites Do not overwrite the video, but overwrite
- related files (default)
- -c, --continue Resume partially downloaded files/fragments
- (default)
- --no-continue Do not resume partially downloaded
- fragments. If the file is not fragmented,
- restart download of the entire file
- --part Use .part files instead of writing directly
- into output file (default)
- --no-part Do not use .part files - write directly
- into output file
- --mtime Use the Last-modified header to set the
- file modification time (default)
- --no-mtime Do not use the Last-modified header to set
- the file modification time
- --write-description Write video description to a .description
- file
- --no-write-description Do not write video description (default)
- --write-info-json Write video metadata to a .info.json file
- (this may contain personal information)
- --no-write-info-json Do not write video metadata (default)
- --write-playlist-metafiles Write playlist metadata in addition to the
- video metadata when using --write-info-json,
- --write-description etc. (default)
- --no-write-playlist-metafiles Do not write playlist metadata when using
- --write-info-json, --write-description etc.
- --clean-info-json Remove some private fields such as
- filenames from the infojson. Note that it
- could still contain some personal
- information (default)
- --no-clean-info-json Write all fields to the infojson
- --write-comments Retrieve video comments to be placed in the
- infojson. The comments are fetched even
- without this option if the extraction is
- known to be quick (Alias: --get-comments)
- --no-write-comments Do not retrieve video comments unless the
- extraction is known to be quick (Alias:
- --no-get-comments)
- --load-info-json FILE JSON file containing the video information
- (created with the "--write-info-json"
- option)
- --cookies FILE Netscape formatted file to read cookies
- from and dump cookie jar in
- --no-cookies Do not read/dump cookies from/to file
- (default)
+ -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
+ --no-batch-file Do not read URLs from batch file (default)
+ -P, --paths [TYPES:]PATH The paths where the files should be
+ downloaded. Specify the type of file and the
+ path separated by a colon ":". All the same
+ TYPES as --output are supported.
+ Additionally, you can also provide "home"
+ (default) 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.
+ This option is ignored if --output is an
+ absolute path
+ -o, --output [TYPES:]TEMPLATE Output filename template; see "OUTPUT
+ TEMPLATE" for details
+ --output-na-placeholder TEXT Placeholder for unavailable fields in
+ "OUTPUT TEMPLATE" (default: "NA")
+ --restrict-filenames Restrict filenames to only ASCII characters,
+ and avoid "&" and spaces in filenames
+ --no-restrict-filenames Allow Unicode characters, "&" and spaces in
+ filenames (default)
+ --windows-filenames Force filenames to be Windows-compatible
+ --no-windows-filenames Make filenames Windows-compatible only if
+ using Windows (default)
+ --trim-filenames LENGTH Limit the filename length (excluding
+ extension) to the specified number of
+ characters
+ -w, --no-overwrites Do not overwrite any files
+ --force-overwrites Overwrite all video and metadata files. This
+ option includes --no-continue
+ --no-force-overwrites Do not overwrite the video, but overwrite
+ related files (default)
+ -c, --continue Resume partially downloaded files/fragments
+ (default)
+ --no-continue Do not resume partially downloaded
+ fragments. If the file is not fragmented,
+ restart download of the entire file
+ --part Use .part files instead of writing directly
+ into output file (default)
+ --no-part Do not use .part files - write directly into
+ output file
+ --mtime Use the Last-modified header to set the file
+ modification time (default)
+ --no-mtime Do not use the Last-modified header to set
+ the file modification time
+ --write-description Write video description to a .description file
+ --no-write-description Do not write video description (default)
+ --write-info-json Write video metadata to a .info.json file
+ (this may contain personal information)
+ --no-write-info-json Do not write video metadata (default)
+ --write-playlist-metafiles Write playlist metadata in addition to the
+ video metadata when using --write-info-json,
+ --write-description etc. (default)
+ --no-write-playlist-metafiles Do not write playlist metadata when using
+ --write-info-json, --write-description etc.
+ --clean-info-json Remove some private fields such as filenames
+ from the infojson. Note that it could still
+ contain some personal information (default)
+ --no-clean-info-json Write all fields to the infojson
+ --write-comments Retrieve video comments to be placed in the
+ infojson. The comments are fetched even
+ without this option if the extraction is
+ known to be quick (Alias: --get-comments)
+ --no-write-comments Do not retrieve video comments unless the
+ extraction is known to be quick (Alias:
+ --no-get-comments)
+ --load-info-json FILE JSON file containing the video information
+ (created with the "--write-info-json" option)
+ --cookies FILE Netscape formatted file to read cookies from
+ and dump cookie jar in
+ --no-cookies Do not read/dump cookies from/to file
+ (default)
--cookies-from-browser BROWSER[+KEYRING][:PROFILE]
- The name of the browser and (optionally)
- the name/path of the profile to load
- cookies from, separated by a ":". Currently
- supported browsers are: brave, chrome,
- chromium, edge, firefox, opera, safari,
- vivaldi. By default, the most recently
- accessed profile is used. The keyring used
- for decrypting Chromium cookies on Linux
- can be (optionally) specified after the
- browser name separated by a "+". Currently
- supported keyrings are: basictext,
- gnomekeyring, kwallet
- --no-cookies-from-browser Do not load cookies from browser (default)
- --cache-dir DIR Location in the filesystem where youtube-dl
- can store some downloaded information (such
- as client ids and signatures) permanently.
- By default $XDG_CACHE_HOME/yt-dlp or
- ~/.cache/yt-dlp
- --no-cache-dir Disable filesystem caching
- --rm-cache-dir Delete all filesystem cache files
+ The name of the browser and (optionally) the
+ name/path of the profile to load cookies
+ from, separated by a ":". Currently
+ supported browsers are: brave, chrome,
+ chromium, edge, firefox, opera, safari,
+ vivaldi. By default, the most recently
+ accessed profile is used. The keyring used
+ for decrypting Chromium cookies on Linux can
+ be (optionally) specified after the browser
+ name separated by a "+". Currently supported
+ keyrings are: basictext, gnomekeyring, kwallet
+ --no-cookies-from-browser Do not load cookies from browser (default)
+ --cache-dir DIR Location in the filesystem where youtube-dl
+ can store some downloaded information (such
+ as client ids and signatures) permanently.
+ By default $XDG_CACHE_HOME/yt-dlp or
+ ~/.cache/yt-dlp
+ --no-cache-dir Disable filesystem caching
+ --rm-cache-dir Delete all filesystem cache files
## Thumbnail Options:
- --write-thumbnail Write thumbnail image to disk
- --no-write-thumbnail Do not write thumbnail image to disk
- (default)
- --write-all-thumbnails Write all thumbnail image formats to disk
- --list-thumbnails List available thumbnails of each video.
- Simulate unless --no-simulate is used
+ --write-thumbnail Write thumbnail image to disk
+ --no-write-thumbnail Do not write thumbnail image to disk (default)
+ --write-all-thumbnails Write all thumbnail image formats to disk
+ --list-thumbnails List available thumbnails of each video.
+ Simulate unless --no-simulate is used
## Internet Shortcut Options:
- --write-link Write an internet shortcut file, depending
- on the current platform (.url, .webloc or
- .desktop). The URL may be cached by the OS
- --write-url-link Write a .url Windows internet shortcut. The
- OS caches the URL based on the file path
- --write-webloc-link Write a .webloc macOS internet shortcut
- --write-desktop-link Write a .desktop Linux internet shortcut
+ --write-link Write an internet shortcut file, depending
+ on the current platform (.url, .webloc or
+ .desktop). The URL may be cached by the OS
+ --write-url-link Write a .url Windows internet shortcut. The
+ OS caches the URL based on the file path
+ --write-webloc-link Write a .webloc macOS internet shortcut
+ --write-desktop-link Write a .desktop Linux internet shortcut
## Verbosity and Simulation Options:
- -q, --quiet Activate quiet mode. If used with
- --verbose, print the log to stderr
- --no-warnings Ignore warnings
- -s, --simulate Do not download the video and do not write
- anything to disk
- --no-simulate Download the video even if printing/listing
- options are used
- --ignore-no-formats-error Ignore "No video formats" error. Useful for
- extracting metadata even if the videos are
- not actually available for download
- (experimental)
- --no-ignore-no-formats-error Throw error when no downloadable video
- formats are found (default)
- --skip-download Do not download the video but write all
- related files (Alias: --no-download)
- -O, --print [WHEN:]TEMPLATE Field name or output template to print to
- screen, optionally prefixed with when to
- print it, separated by a ":". Supported
- values of "WHEN" are the same as that of
- --use-postprocessor, and "video" (default).
- Implies --quiet. Implies --simulate unless
- --no-simulate or later stages of WHEN are
- used. This option can be used multiple
- times
+ -q, --quiet Activate quiet mode. If used with --verbose,
+ print the log to stderr
+ --no-warnings Ignore warnings
+ -s, --simulate Do not download the video and do not write
+ anything to disk
+ --no-simulate Download the video even if printing/listing
+ options are used
+ --ignore-no-formats-error Ignore "No video formats" error. Useful for
+ extracting metadata even if the videos are
+ not actually available for download
+ (experimental)
+ --no-ignore-no-formats-error Throw error when no downloadable video
+ formats are found (default)
+ --skip-download Do not download the video but write all
+ related files (Alias: --no-download)
+ -O, --print [WHEN:]TEMPLATE Field name or output template to print to
+ screen, optionally prefixed with when to
+ print it, separated by a ":". Supported
+ values of "WHEN" are the same as that of
+ --use-postprocessor, and "video" (default).
+ Implies --quiet. Implies --simulate unless
+ --no-simulate or later stages of WHEN are
+ used. This option can be used multiple times
--print-to-file [WHEN:]TEMPLATE FILE
- Append given template to the file. The
- values of WHEN and TEMPLATE are same as
- that of --print. FILE uses the same syntax
- as the output template. This option can be
- used multiple times
- -j, --dump-json Quiet, but print JSON information for each
- video. Simulate unless --no-simulate is
- used. See "OUTPUT TEMPLATE" for a
- description of available keys
- -J, --dump-single-json Quiet, but print JSON information for each
- url or infojson passed. Simulate unless
- --no-simulate is used. If the URL refers to
- a playlist, the whole playlist information
- is dumped in a single line
- --force-write-archive Force download archive entries to be
- written as far as no errors occur, even if
- -s or another simulation option is used
- (Alias: --force-download-archive)
- --newline Output progress bar as new lines
- --no-progress Do not print progress bar
- --progress Show progress bar, even if in quiet mode
- --console-title Display progress in console titlebar
+ Append given template to the file. The
+ values of WHEN and TEMPLATE are same as that
+ of --print. FILE uses the same syntax as the
+ output template. This option can be used
+ multiple times
+ -j, --dump-json Quiet, but print JSON information for each
+ video. Simulate unless --no-simulate is
+ used. See "OUTPUT TEMPLATE" for a
+ description of available keys
+ -J, --dump-single-json Quiet, but print JSON information for each
+ url or infojson passed. Simulate unless
+ --no-simulate is used. If the URL refers to
+ a playlist, the whole playlist information
+ is dumped in a single line
+ --force-write-archive Force download archive entries to be written
+ as far as no errors occur, even if -s or
+ another simulation option is used (Alias:
+ --force-download-archive)
+ --newline Output progress bar as new lines
+ --no-progress Do not print progress bar
+ --progress Show progress bar, even if in quiet mode
+ --console-title Display progress in console titlebar
--progress-template [TYPES:]TEMPLATE
- Template for progress outputs, optionally
- prefixed with one of "download:" (default),
- "download-title:" (the console title),
- "postprocess:", or "postprocess-title:".
- The video's fields are accessible under the
- "info" key and the progress attributes are
- accessible under "progress" key. E.g.:
- --console-title --progress-template
- "download-title:%(info.id)s-%(progress.eta)s"
- -v, --verbose Print various debugging information
- --dump-pages Print downloaded pages encoded using base64
- to debug problems (very verbose)
- --write-pages Write downloaded intermediary pages to
- files in the current directory to debug
- problems
- --print-traffic Display sent and read HTTP traffic
+ Template for progress outputs, optionally
+ prefixed with one of "download:" (default),
+ "download-title:" (the console title),
+ "postprocess:", or "postprocess-title:".
+ The video's fields are accessible under the
+ "info" key and the progress attributes are
+ accessible under "progress" key. E.g.:
+ --console-title --progress-template
+ "download-title:%(info.id)s-%(progress.eta)s"
+ -v, --verbose Print various debugging information
+ --dump-pages Print downloaded pages encoded using base64
+ to debug problems (very verbose)
+ --write-pages Write downloaded intermediary pages to files
+ in the current directory to debug problems
+ --print-traffic Display sent and read HTTP traffic
## Workarounds:
- --encoding ENCODING Force the specified encoding (experimental)
- --legacy-server-connect Explicitly allow HTTPS connection to
- servers that do not support RFC 5746 secure
- renegotiation
- --no-check-certificates Suppress HTTPS certificate validation
- --prefer-insecure Use an unencrypted connection to retrieve
- information about the video (Currently
- supported only for YouTube)
- --add-header FIELD:VALUE Specify a custom HTTP header and its value,
- separated by a colon ":". You can use this
- option multiple times
- --bidi-workaround Work around terminals that lack
- bidirectional text support. Requires bidiv
- or fribidi executable in PATH
- --sleep-requests SECONDS Number of seconds to sleep between requests
- during data extraction
- --sleep-interval SECONDS Number of seconds to sleep before each
- download. This is the minimum time to sleep
- when used along with --max-sleep-interval
- (Alias: --min-sleep-interval)
- --max-sleep-interval SECONDS Maximum number of seconds to sleep. Can
- only be used along with --min-sleep-interval
- --sleep-subtitles SECONDS Number of seconds to sleep before each
- subtitle download
+ --encoding ENCODING Force the specified encoding (experimental)
+ --legacy-server-connect Explicitly allow HTTPS connection to servers
+ that do not support RFC 5746 secure
+ renegotiation
+ --no-check-certificates Suppress HTTPS certificate validation
+ --prefer-insecure Use an unencrypted connection to retrieve
+ information about the video (Currently
+ supported only for YouTube)
+ --add-header FIELD:VALUE Specify a custom HTTP header and its value,
+ separated by a colon ":". You can use this
+ option multiple times
+ --bidi-workaround Work around terminals that lack
+ bidirectional text support. Requires bidiv
+ or fribidi executable in PATH
+ --sleep-requests SECONDS Number of seconds to sleep between requests
+ during data extraction
+ --sleep-interval SECONDS Number of seconds to sleep before each
+ download. This is the minimum time to sleep
+ when used along with --max-sleep-interval
+ (Alias: --min-sleep-interval)
+ --max-sleep-interval SECONDS Maximum number of seconds to sleep. Can only
+ be used along with --min-sleep-interval
+ --sleep-subtitles SECONDS Number of seconds to sleep before each
+ subtitle download
## Video Format Options:
- -f, --format FORMAT Video format code, see "FORMAT SELECTION"
- for more details
- -S, --format-sort SORTORDER Sort the formats by the fields given, see
- "Sorting Formats" for more details
- --S-force, --format-sort-force Force user specified sort order to have
- precedence over all fields, see "Sorting
- Formats" for more details
- --no-format-sort-force Some fields have precedence over the user
- specified sort order (default), see
- "Sorting Formats" for more details
- --video-multistreams Allow multiple video streams to be merged
- into a single file
- --no-video-multistreams Only one video stream is downloaded for
- each output file (default)
- --audio-multistreams Allow multiple audio streams to be merged
- into a single file
- --no-audio-multistreams Only one audio stream is downloaded for
- each output file (default)
- --prefer-free-formats Prefer video formats with free containers
- over non-free ones of same quality. Use
- with "-S ext" to strictly prefer free
- containers irrespective of quality
- --no-prefer-free-formats Don't give any special preference to free
- containers (default)
- --check-formats Make sure formats are selected only from
- those that are actually downloadable
- --check-all-formats Check all formats for whether they are
- actually downloadable
- --no-check-formats Do not check that the formats are actually
- downloadable
- -F, --list-formats List available formats of each video.
- Simulate unless --no-simulate is used
- --merge-output-format FORMAT If a merge is required (e.g.
- bestvideo+bestaudio), output to given
- container format. One of mkv, mp4, ogg,
- webm, flv. Ignored if no merge is required
+ -f, --format FORMAT Video format code, see "FORMAT SELECTION"
+ for more details
+ -S, --format-sort SORTORDER Sort the formats by the fields given, see
+ "Sorting Formats" for more details
+ --format-sort-force Force user specified sort order to have
+ precedence over all fields, see "Sorting
+ Formats" for more details (Alias: --S-force)
+ --no-format-sort-force Some fields have precedence over the user
+ specified sort order (default)
+ --video-multistreams Allow multiple video streams to be merged
+ into a single file
+ --no-video-multistreams Only one video stream is downloaded for each
+ output file (default)
+ --audio-multistreams Allow multiple audio streams to be merged
+ into a single file
+ --no-audio-multistreams Only one audio stream is downloaded for each
+ output file (default)
+ --prefer-free-formats Prefer video formats with free containers
+ over non-free ones of same quality. Use with
+ "-S ext" to strictly prefer free containers
+ irrespective of quality
+ --no-prefer-free-formats Don't give any special preference to free
+ containers (default)
+ --check-formats Make sure formats are selected only from
+ those that are actually downloadable
+ --check-all-formats Check all formats for whether they are
+ actually downloadable
+ --no-check-formats Do not check that the formats are actually
+ downloadable
+ -F, --list-formats List available formats of each video.
+ Simulate unless --no-simulate is used
+ --merge-output-format FORMAT If a merge is required (e.g.
+ bestvideo+bestaudio), output to given
+ container format. One of mkv, mp4, ogg,
+ webm, flv. Ignored if no merge is required
## Subtitle Options:
- --write-subs Write subtitle file
- --no-write-subs Do not write subtitle file (default)
- --write-auto-subs Write automatically generated subtitle file
- (Alias: --write-automatic-subs)
- --no-write-auto-subs Do not write auto-generated subtitles
- (default) (Alias: --no-write-automatic-subs)
- --list-subs List available subtitles of each video.
- Simulate unless --no-simulate is used
- --sub-format FORMAT Subtitle format, accepts formats
- preference, for example: "srt" or
- "ass/srt/best"
- --sub-langs LANGS Languages of the subtitles to download (can
- be regex) or "all" separated by commas.
- (Eg: --sub-langs "en.*,ja") You can prefix
- the language code with a "-" to exempt it
- from the requested languages. (Eg:
- --sub-langs all,-live_chat) Use --list-subs
- for a list of available language tags
+ --write-subs Write subtitle file
+ --no-write-subs Do not write subtitle file (default)
+ --write-auto-subs Write automatically generated subtitle file
+ (Alias: --write-automatic-subs)
+ --no-write-auto-subs Do not write auto-generated subtitles
+ (default) (Alias: --no-write-automatic-subs)
+ --list-subs List available subtitles of each video.
+ Simulate unless --no-simulate is used
+ --sub-format FORMAT Subtitle format; accepts formats preference,
+ Eg: "srt" or "ass/srt/best"
+ --sub-langs LANGS Languages of the subtitles to download (can
+ be regex) or "all" separated by commas. (Eg:
+ --sub-langs "en.*,ja") You can prefix the
+ language code with a "-" to exclude it from
+ the requested languages. (Eg: --sub-langs
+ all,-live_chat) Use --list-subs for a list
+ of available language tags
## Authentication Options:
- -u, --username USERNAME Login with this account ID
- -p, --password PASSWORD Account password. If this option is left
- out, yt-dlp will ask interactively
- -2, --twofactor TWOFACTOR Two-factor authentication code
- -n, --netrc Use .netrc authentication data
- --netrc-location PATH Location of .netrc authentication data;
- either the path or its containing
- directory. Defaults to ~/.netrc
- --video-password PASSWORD Video password (vimeo, youku)
- --ap-mso MSO Adobe Pass multiple-system operator (TV
- provider) identifier, use --ap-list-mso for
- a list of available MSOs
- --ap-username USERNAME Multiple-system operator account login
- --ap-password PASSWORD Multiple-system operator account password.
- If this option is left out, yt-dlp will ask
- interactively
- --ap-list-mso List all supported multiple-system
- operators
+ -u, --username USERNAME Login with this account ID
+ -p, --password PASSWORD Account password. If this option is left
+ out, yt-dlp will ask interactively
+ -2, --twofactor TWOFACTOR Two-factor authentication code
+ -n, --netrc Use .netrc authentication data
+ --netrc-location PATH Location of .netrc authentication data;
+ either the path or its containing directory.
+ Defaults to ~/.netrc
+ --video-password PASSWORD Video password (vimeo, youku)
+ --ap-mso MSO Adobe Pass multiple-system operator (TV
+ provider) identifier, use --ap-list-mso for
+ a list of available MSOs
+ --ap-username USERNAME Multiple-system operator account login
+ --ap-password PASSWORD Multiple-system operator account password.
+ If this option is left out, yt-dlp will ask
+ interactively
+ --ap-list-mso List all supported multiple-system operators
+ --client-certificate CERTFILE Path to client certificate file in PEM
+ format. May include the private key
+ --client-certificate-key KEYFILE
+ Path to private key file for client
+ certificate
+ --client-certificate-password PASSWORD
+ Password for client certificate private key,
+ if encrypted. If not provided, and the key
+ is encrypted, yt-dlp will ask interactively
## Post-Processing Options:
- -x, --extract-audio Convert video files to audio-only files
- (requires ffmpeg and ffprobe)
- --audio-format FORMAT Specify audio format to convert the audio
- to when -x is used. Currently supported
- formats are: best (default) or one of aac,
- flac, mp3, m4a, opus, vorbis, wav, alac
- --audio-quality QUALITY Specify ffmpeg audio quality to use when
- converting the audio with -x. Insert a
- value between 0 (best) and 10 (worst) for
- VBR or a specific bitrate like 128K
- (default 5)
- --remux-video FORMAT Remux the video into another container if
- necessary (currently supported: mp4, mkv,
- flv, webm, mov, avi, mka, ogg, aac, flac,
- mp3, m4a, opus, vorbis, wav, alac). If
- target container does not support the
- video/audio codec, remuxing will fail. You
- can specify multiple rules; Eg.
- "aac>m4a/mov>mp4/mkv" will remux aac to
- m4a, mov to mp4 and anything else to mkv.
- --recode-video FORMAT Re-encode the video into another format if
- re-encoding is necessary. The syntax and
- supported formats are the same as --remux-video
- --postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
- Specify the postprocessor/executable name
- and the arguments separated by a colon ":"
- to give the argument to the specified
- postprocessor/executable. Supported PP are:
- Merger, ModifyChapters, SplitChapters,
- ExtractAudio, VideoRemuxer, VideoConvertor,
- Metadata, EmbedSubtitle, EmbedThumbnail,
- SubtitlesConvertor, ThumbnailsConvertor,
- FixupStretched, FixupM4a, FixupM3u8,
- FixupTimestamp and FixupDuration. The
- supported executables are: AtomicParsley,
- FFmpeg and FFprobe. You can also specify
- "PP+EXE:ARGS" to give the arguments to the
- specified executable only when being used
- by the specified postprocessor.
- Additionally, for ffmpeg/ffprobe, "_i"/"_o"
- can be appended to the prefix optionally
- followed by a number to pass the argument
- before the specified input/output file. Eg:
- --ppa "Merger+ffmpeg_i1:-v quiet". You can
- use this option multiple times to give
- different arguments to different
- postprocessors. (Alias: --ppa)
- -k, --keep-video Keep the intermediate video file on disk
- after post-processing
- --no-keep-video Delete the intermediate video file after
- post-processing (default)
- --post-overwrites Overwrite post-processed files (default)
- --no-post-overwrites Do not overwrite post-processed files
- --embed-subs Embed subtitles in the video (only for mp4,
- webm and mkv videos)
- --no-embed-subs Do not embed subtitles (default)
- --embed-thumbnail Embed thumbnail in the video as cover art
- --no-embed-thumbnail Do not embed thumbnail (default)
- --embed-metadata Embed metadata to the video file. Also
- embeds chapters/infojson if present unless
- --no-embed-chapters/--no-embed-info-json
- are used (Alias: --add-metadata)
- --no-embed-metadata Do not add metadata to file (default)
- (Alias: --no-add-metadata)
- --embed-chapters Add chapter markers to the video file
- (Alias: --add-chapters)
- --no-embed-chapters Do not add chapter markers (default)
- (Alias: --no-add-chapters)
- --embed-info-json Embed the infojson as an attachment to
- mkv/mka video files
- --no-embed-info-json Do not embed the infojson as an attachment
- to the video file
- --parse-metadata FROM:TO Parse additional metadata like title/artist
- from other fields; see "MODIFYING METADATA"
- for details
+ -x, --extract-audio Convert video files to audio-only files
+ (requires ffmpeg and ffprobe)
+ --audio-format FORMAT Format to convert the audio to when -x is
+ used. (currently supported: best (default),
+ mp3, aac, m4a, opus, vorbis, flac, alac,
+ wav). You can specify multiple rules using
+ similar syntax as --remux-video
+ --audio-quality QUALITY Specify ffmpeg audio quality to use when
+ converting the audio with -x. Insert a value
+ between 0 (best) and 10 (worst) for VBR or a
+ specific bitrate like 128K (default 5)
+ --remux-video FORMAT Remux the video into another container if
+ necessary (currently supported: mp4, mkv,
+ flv, webm, mov, avi, mka, ogg, mp3, aac,
+ m4a, opus, vorbis, flac, alac, wav). If
+ target container does not support the
+ video/audio codec, remuxing will fail. You
+ can specify multiple rules; Eg.
+ "aac>m4a/mov>mp4/mkv" will remux aac to m4a,
+ mov to mp4 and anything else to mkv
+ --recode-video FORMAT Re-encode the video into another format if
+ necessary. The syntax and supported formats
+ are the same as --remux-video
+ --postprocessor-args NAME:ARGS Give these arguments to the postprocessors.
+ Specify the postprocessor/executable name
+ and the arguments separated by a colon ":"
+ to give the argument to the specified
+ postprocessor/executable. Supported PP are:
+ Merger, ModifyChapters, SplitChapters,
+ ExtractAudio, VideoRemuxer, VideoConvertor,
+ Metadata, EmbedSubtitle, EmbedThumbnail,
+ SubtitlesConvertor, ThumbnailsConvertor,
+ FixupStretched, FixupM4a, FixupM3u8,
+ FixupTimestamp and FixupDuration. The
+ supported executables are: AtomicParsley,
+ FFmpeg and FFprobe. You can also specify
+ "PP+EXE:ARGS" to give the arguments to the
+ specified executable only when being used by
+ the specified postprocessor. Additionally,
+ for ffmpeg/ffprobe, "_i"/"_o" can be
+ appended to the prefix optionally followed
+ by a number to pass the argument before the
+ specified input/output file. Eg: --ppa
+ "Merger+ffmpeg_i1:-v quiet". You can use
+ this option multiple times to give different
+ arguments to different postprocessors.
+ (Alias: --ppa)
+ -k, --keep-video Keep the intermediate video file on disk
+ after post-processing
+ --no-keep-video Delete the intermediate video file after
+ post-processing (default)
+ --post-overwrites Overwrite post-processed files (default)
+ --no-post-overwrites Do not overwrite post-processed files
+ --embed-subs Embed subtitles in the video (only for mp4,
+ webm and mkv videos)
+ --no-embed-subs Do not embed subtitles (default)
+ --embed-thumbnail Embed thumbnail in the video as cover art
+ --no-embed-thumbnail Do not embed thumbnail (default)
+ --embed-metadata Embed metadata to the video file. Also
+ embeds chapters/infojson if present unless
+ --no-embed-chapters/--no-embed-info-json are
+ used (Alias: --add-metadata)
+ --no-embed-metadata Do not add metadata to file (default)
+ (Alias: --no-add-metadata)
+ --embed-chapters Add chapter markers to the video file
+ (Alias: --add-chapters)
+ --no-embed-chapters Do not add chapter markers (default) (Alias:
+ --no-add-chapters)
+ --embed-info-json Embed the infojson as an attachment to
+ mkv/mka video files
+ --no-embed-info-json Do not embed the infojson as an attachment
+ to the video file
+ --parse-metadata FROM:TO Parse additional metadata like title/artist
+ from other fields; see "MODIFYING METADATA"
+ for details
--replace-in-metadata FIELDS REGEX REPLACE
- Replace text in a metadata field using the
- given regex. This option can be used
- multiple times
- --xattrs Write metadata to the video file's xattrs
- (using dublin core and xdg standards)
- --concat-playlist POLICY Concatenate videos in a playlist. One of
- "never", "always", or "multi_video"
- (default; only when the videos form a
- single show). All the video files must have
- same codecs and number of streams to be
- concatable. The "pl_video:" prefix can be
- used with "--paths" and "--output" to set
- the output filename for the concatenated
- files. See "OUTPUT TEMPLATE" for details
- --fixup POLICY Automatically correct known faults of the
- file. One of never (do nothing), warn (only
- emit a warning), detect_or_warn (the
- default; fix file if we can, warn
- otherwise), force (try fixing even if file
- already exists)
- --ffmpeg-location PATH Location of the ffmpeg binary; either the
- path to the binary or its containing
- directory
- --exec [WHEN:]CMD Execute a command, optionally prefixed with
- when to execute it (after_move if
- unspecified), separated by a ":". Supported
- values of "WHEN" are the same as that of
- --use-postprocessor. Same syntax as the
- output template can be used to pass any
- field as arguments to the command. After
- download, an additional field "filepath"
- that contains the final path of the
- downloaded file is also available, and if
- no fields are passed, %(filepath)q is
- appended to the end of the command. This
- option can be used multiple times
- --no-exec Remove any previously defined --exec
- --convert-subs FORMAT Convert the subtitles to another format
- (currently supported: srt, vtt, ass, lrc)
- (Alias: --convert-subtitles)
- --convert-thumbnails FORMAT Convert the thumbnails to another format
- (currently supported: jpg, png, webp)
- --split-chapters Split video into multiple files based on
- internal chapters. The "chapter:" prefix
- can be used with "--paths" and "--output"
- to set the output filename for the split
- files. See "OUTPUT TEMPLATE" for details
- --no-split-chapters Do not split video based on chapters
- (default)
- --remove-chapters REGEX Remove chapters whose title matches the
- given regular expression. Time ranges
- prefixed by a "*" can also be used in place
- of chapters to remove the specified range.
- Eg: --remove-chapters "*10:15-15:00"
- --remove-chapters "intro". This option can
- be used multiple times
- --no-remove-chapters Do not remove any chapters from the file
- (default)
- --force-keyframes-at-cuts Force keyframes around the chapters before
- removing/splitting them. Requires a
- re-encode and thus is very slow, but the
- resulting video may have fewer artifacts
- around the cuts
- --no-force-keyframes-at-cuts Do not force keyframes around the chapters
- when cutting/splitting (default)
- --use-postprocessor NAME[:ARGS] The (case sensitive) name of plugin
- postprocessors to be enabled, and
- (optionally) arguments to be passed to it,
- separated by a colon ":". ARGS are a
- semicolon ";" delimited list of NAME=VALUE.
- The "when" argument determines when the
- postprocessor is invoked. It can be one of
- "pre_process" (after video extraction),
- "after_filter" (after video passes filter),
- "before_dl" (before each video download),
- "post_process" (after each video download;
- default), "after_move" (after moving video
- file to it's final locations),
- "after_video" (after downloading and
- processing all formats of a video), or
- "playlist" (at end of playlist). This
- option can be used multiple times to add
- different postprocessors
+ Replace text in a metadata field using the
+ given regex. This option can be used
+ multiple times
+ --xattrs Write metadata to the video file's xattrs
+ (using dublin core and xdg standards)
+ --concat-playlist POLICY Concatenate videos in a playlist. One of
+ "never", "always", or "multi_video"
+ (default; only when the videos form a single
+ show). All the video files must have same
+ codecs and number of streams to be
+ concatable. The "pl_video:" prefix can be
+ used with "--paths" and "--output" to set
+ the output filename for the concatenated
+ files. See "OUTPUT TEMPLATE" for details
+ --fixup POLICY Automatically correct known faults of the
+ file. One of never (do nothing), warn (only
+ emit a warning), detect_or_warn (the
+ default; fix file if we can, warn
+ otherwise), force (try fixing even if file
+ already exists)
+ --ffmpeg-location PATH Location of the ffmpeg binary; either the
+ path to the binary or its containing directory
+ --exec [WHEN:]CMD Execute a command, optionally prefixed with
+ when to execute it (after_move if
+ unspecified), separated by a ":". Supported
+ values of "WHEN" are the same as that of
+ --use-postprocessor. Same syntax as the
+ output template can be used to pass any
+ field as arguments to the command. After
+ download, an additional field "filepath"
+ that contains the final path of the
+ downloaded file is also available, and if no
+ fields are passed, %(filepath)q is appended
+ to the end of the command. This option can
+ be used multiple times
+ --no-exec Remove any previously defined --exec
+ --convert-subs FORMAT Convert the subtitles to another format
+ (currently supported: srt, vtt, ass, lrc)
+ (Alias: --convert-subtitles)
+ --convert-thumbnails FORMAT Convert the thumbnails to another format
+ (currently supported: jpg, png, webp). You
+ can specify multiple rules using similar
+ syntax as --remux-video
+ --split-chapters Split video into multiple files based on
+ internal chapters. The "chapter:" prefix can
+ be used with "--paths" and "--output" to set
+ the output filename for the split files. See
+ "OUTPUT TEMPLATE" for details
+ --no-split-chapters Do not split video based on chapters (default)
+ --remove-chapters REGEX Remove chapters whose title matches the
+ given regular expression. The syntax is the
+ same as --download-sections. This option can
+ be used multiple times
+ --no-remove-chapters Do not remove any chapters from the file
+ (default)
+ --force-keyframes-at-cuts Force keyframes at cuts when
+ downloading/splitting/removing sections.
+ This is slow due to needing a re-encode, but
+ the resulting video may have fewer artifacts
+ around the cuts
+ --no-force-keyframes-at-cuts Do not force keyframes around the chapters
+ when cutting/splitting (default)
+ --use-postprocessor NAME[:ARGS]
+ The (case sensitive) name of plugin
+ postprocessors to be enabled, and
+ (optionally) arguments to be passed to it,
+ separated by a colon ":". ARGS are a
+ semicolon ";" delimited list of NAME=VALUE.
+ The "when" argument determines when the
+ postprocessor is invoked. It can be one of
+ "pre_process" (after video extraction),
+ "after_filter" (after video passes filter),
+ "before_dl" (before each video download),
+ "post_process" (after each video download;
+ default), "after_move" (after moving video
+ file to it's final locations), "after_video"
+ (after downloading and processing all
+ formats of a video), or "playlist" (at end
+ of playlist). This option can be used
+ multiple times to add different postprocessors
## SponsorBlock Options:
Make chapter entries for, or remove various segments (sponsor,
introductions, etc.) from downloaded YouTube videos using the
[SponsorBlock API](https://sponsor.ajay.app)
- --sponsorblock-mark CATS SponsorBlock categories to create chapters
- for, separated by commas. Available
- categories are all, default(=all), sponsor,
- intro, outro, selfpromo, preview, filler,
- interaction, music_offtopic, poi_highlight.
- You can prefix the category with a "-" to
- exempt it. See [1] for description of the
- categories. Eg: --sponsorblock-mark all,-preview
- [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
- --sponsorblock-remove CATS SponsorBlock categories to be removed from
- the video file, separated by commas. If a
- category is present in both mark and
- remove, remove takes precedence. The syntax
- and available categories are the same as
- for --sponsorblock-mark except that
- "default" refers to "all,-filler" and
- poi_highlight is not available
+ --sponsorblock-mark CATS SponsorBlock categories to create chapters
+ for, separated by commas. Available
+ categories are sponsor, intro, outro,
+ selfpromo, preview, filler, interaction,
+ music_offtopic, poi_highlight, all and
+ default (=all). You can prefix the category
+ with a "-" to exclude it. See [1] for
+ description of the categories. Eg:
+ --sponsorblock-mark all,-preview
+ [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
+ --sponsorblock-remove CATS SponsorBlock categories to be removed from
+ the video file, separated by commas. If a
+ category is present in both mark and remove,
+ remove takes precedence. The syntax and
+ available categories are the same as for
+ --sponsorblock-mark except that "default"
+ refers to "all,-filler" and poi_highlight is
+ not available
--sponsorblock-chapter-title TEMPLATE
- The title template for SponsorBlock
- chapters created by --sponsorblock-mark.
- The same syntax as the output template is
- used, but the only available fields are
- start_time, end_time, category, categories,
- name, category_names. Defaults to
- "[SponsorBlock]: %(category_names)l"
- --no-sponsorblock Disable both --sponsorblock-mark and
- --sponsorblock-remove
- --sponsorblock-api URL SponsorBlock API location, defaults to
- https://sponsor.ajay.app
+ An output template for the title of the
+ SponsorBlock chapters created by
+ --sponsorblock-mark. The only available
+ fields are start_time, end_time, category,
+ categories, name, category_names. Defaults
+ to "[SponsorBlock]: %(category_names)l"
+ --no-sponsorblock Disable both --sponsorblock-mark and
+ --sponsorblock-remove
+ --sponsorblock-api URL SponsorBlock API location, defaults to
+ https://sponsor.ajay.app
## Extractor Options:
- --extractor-retries RETRIES Number of retries for known extractor
- errors (default is 3), or "infinite"
- --allow-dynamic-mpd Process dynamic DASH manifests (default)
- (Alias: --no-ignore-dynamic-mpd)
- --ignore-dynamic-mpd Do not process dynamic DASH manifests
- (Alias: --no-allow-dynamic-mpd)
- --hls-split-discontinuity Split HLS playlists to different formats at
- discontinuities such as ad breaks
- --no-hls-split-discontinuity Do not split HLS playlists to different
- formats at discontinuities such as ad
- breaks (default)
- --extractor-args KEY:ARGS Pass these arguments to the extractor. See
- "EXTRACTOR ARGUMENTS" for details. You can
- use this option multiple times to give
- arguments for different extractors
+ --extractor-retries RETRIES Number of retries for known extractor errors
+ (default is 3), or "infinite"
+ --allow-dynamic-mpd Process dynamic DASH manifests (default)
+ (Alias: --no-ignore-dynamic-mpd)
+ --ignore-dynamic-mpd Do not process dynamic DASH manifests
+ (Alias: --no-allow-dynamic-mpd)
+ --hls-split-discontinuity Split HLS playlists to different formats at
+ discontinuities such as ad breaks
+ --no-hls-split-discontinuity Do not split HLS playlists to different
+ formats at discontinuities such as ad breaks
+ (default)
+ --extractor-args KEY:ARGS Pass these arguments to the extractor. See
+ "EXTRACTOR ARGUMENTS" for details. You can
+ use this option multiple times to give
+ arguments for different extractors
# CONFIGURATION
1. **Default**: A literal default value can be specified for when the field is empty using a `|` separator. This overrides `--output-na-template`. Eg: `%(uploader|Unknown)s`
-1. **More Conversions**: In addition to the normal format types `diouxXeEfFgGcrs`, `B`, `j`, `l`, `q`, `D`, `S` can be used for converting to **B**ytes, **j**son (flag `#` for pretty-printing), a comma separated **l**ist (flag `#` for `\n` newline-separated), a string **q**uoted for the terminal (flag `#` to split a list into different arguments), to add **D**ecimal suffixes (Eg: 10M) (flag `#` to use 1024 as factor), and to **S**anitize as filename (flag `#` for restricted), respectively
+1. **More Conversions**: In addition to the normal format types `diouxXeEfFgGcrs`, yt-dlp additionally supports converting to `B` = **B**ytes, `j` = **j**son (flag `#` for pretty-printing), `h` = HTML escaping, `l` = a comma separated **l**ist (flag `#` for `\n` newline-separated), `q` = a string **q**uoted for the terminal (flag `#` to split a list into different arguments), `D` = add **D**ecimal suffixes (Eg: 10M) (flag `#` to use 1024 as factor), and `S` = **S**anitize as filename (flag `#` for restricted)
1. **Unicode normalization**: The format type `U` can be used for NFC [unicode normalization](https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize). The alternate form flag (`#`) changes the normalization to NFD and the conversion flag `+` can be used for NFKC/NFKD compatibility equivalence normalization. Eg: `%(title)+.100U` is NFKC
- `vbr` (numeric): Average video bitrate in KBit/s
- `fps` (numeric): Frame rate
- `dynamic_range` (string): The dynamic range of the video
+ - `stretched_ratio` (float): `width:height` of the video's pixels, if not square
- `vcodec` (string): Name of the video codec in use
- `container` (string): Name of the container format
- `filesize` (numeric): The number of bytes, if known in advance
- `disc_number` (numeric): Number of the disc or other physical medium the track belongs to
- `release_year` (numeric): Year (YYYY) when the album was released
-Available for `chapter:` prefix when using `--split-chapters` for videos with internal chapters:
+Available only when using `--download-sections` and for `chapter:` prefix when using `--split-chapters` for videos with internal chapters:
- `section_title` (string): Title of the chapter
- `section_number` (numeric): Number of the chapter within the file
# handling multiple lines correctly
$ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --add-metadata
+# Do not set any "synopsis" in the video metadata
+$ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"
+
# Remove "formats" field from the infojson by setting it to an empty string
$ yt-dlp --parse-metadata ":(?P<formats>)" -j
The following extractors use this feature:
#### youtube
-* `skip`: One or more of `hls`, `dash` or `translated_subs` to skip extraction of the m3u8 manifests, dash manifests and auto-translated subtitles respectively
-* `player_client`: Clients to extract video data from. The main clients are `web`, `android` and `ios` with variants `_music`, `_embedded`, `_embedscreen`, `_creator` (Eg: `web_embedded`); and `mweb` and `tv_embedded` (agegate bypass) with no variants. By default, `android,web` is used, but tv_embedded and creator variants are added as required for age-gated videos. Similarly the music variants are added for `music.youtube.com` urls. You can use `all` to use all the clients, and `default` for the default clients.
+* `skip`: One or more of `hls`, `dash` or `translated_subs` to skip extraction of the m3u8 manifests, dash manifests and [auto-translated subtitles](https://github.com/yt-dlp/yt-dlp/issues/4090#issuecomment-1158102032) respectively
+* `player_client`: Clients to extract video data from. The main clients are `web`, `android` and `ios` with variants `_music`, `_embedded`, `_embedscreen`, `_creator` (Eg: `web_embedded`); and `mweb` and `tv_embedded` (agegate bypass) with no variants. By default, `android,web` is used, but `tv_embedded` and `creator` variants are added as required for age-gated videos. Similarly the music variants are added for `music.youtube.com` urls. You can use `all` to use all the clients, and `default` for the default clients.
* `player_skip`: Skip some network requests that are generally needed for robust extraction. One or more of `configs` (skip client configs), `webpage` (skip initial webpage), `js` (skip js player). While these options can help reduce the number of requests needed or avoid some rate-limiting, they could cause some issues. See [#860](https://github.com/yt-dlp/yt-dlp/pull/860) for more details
* `include_live_dash`: Include live dash formats even without `--live-from-start` (These formats don't download properly)
* `comment_sort`: `top` or `new` (default) - choose comment sorting mode (on YouTube's side)
* `max_comments`: Limit the amount of comments to gather. Comma-separated list of integers representing `max-comments,max-parents,max-replies,max-replies-per-thread`. Default is `all,all,all,all`
* E.g. `all,all,1000,10` will get a maximum of 1000 replies total, with up to 10 replies per thread. `1000,all,100` will get a maximum of 1000 comments, with a maximum of 100 replies total
+* `innertube_host`: Innertube API host to use for all API requests
+ * e.g. `studio.youtube.com`, `youtubei.googleapis.com`
+ * Note: Cookies exported from `www.youtube.com` will not work with hosts other than `*.youtube.com`
+* `innertube_key`: Innertube API key to use for all API requests
#### youtubetab (YouTube playlists, channels, feeds, etc.)
* `skip`: One or more of `webpage` (skip initial webpage download), `authcheck` (allow the download of playlists requiring authentication when no initial webpage is downloaded. This may cause unwanted behavior, see [#1122](https://github.com/yt-dlp/yt-dlp/pull/1122) for more details)
ydl.download(URLS)
```
-Most likely, you'll want to use various options. For a list of options available, have a look at [`yt_dlp/YoutubeDL.py`](yt_dlp/YoutubeDL.py#L181).
+Most likely, you'll want to use various options. For a list of options available, have a look at [`yt_dlp/YoutubeDL.py`](yt_dlp/YoutubeDL.py#L180).
**Tip**: If you are porting your code from youtube-dl to yt-dlp, one important point to look out for is that we do not guarantee the return value of `YoutubeDL.extract_info` to be json serializable, or even be a dictionary. It will be dictionary-like, but if you want to ensure it is a serializable dictionary, pass it through `YoutubeDL.sanitize_info` as shown in the [example below](#extracting-information)
URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
ydl_opts = {
- 'format': 'm4a/bestaudio/best'
+ 'format': 'm4a/bestaudio/best',
# ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
'postprocessors': [{ # Extract audio using ffmpeg
'key': 'FFmpegExtractAudio',
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
error_code = ydl.download(URLS)
```
+
+#### Filter videos
+
+```python
+import yt_dlp
+
+URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
+
+def longer_than_a_minute(info, *, incomplete):
+ """Download only videos longer than a minute (or with unknown duration)"""
+ duration = info.get('duration')
+ if duration and duration < 60:
+ return 'The video is too short'
+
+ydl_opts = {
+ 'match_filter': longer_than_a_minute,
+}
+
+with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+ error_code = ydl.download(URLS)
+```
+
#### Adding logger and progress hook
```python
with yt_dlp.YoutubeDL() as ydl:
- ydl.add_post_processor(MyCustomPP())
+ # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
+ ydl.add_post_processor(MyCustomPP(), when='pre_process')
ydl.download(URLS)
```
--max-views COUNT --match-filter "view_count <=? COUNT"
--user-agent UA --add-header "User-Agent:UA"
--referer URL --add-header "Referer:URL"
+ --playlist-start NUMBER -I NUMBER:
+ --playlist-end NUMBER -I :NUMBER
+ --playlist-reverse -I ::-1
+ --no-playlist-reverse Default
#### Not recommended
These options are not intended to be used by the end-user
--test Download only part of video for testing extractors
+ --load-pages Load pages dumped by --write-pages
--youtube-print-sig-code For testing youtube signatures
--allow-unplayable-formats List unplayable formats also
--no-allow-unplayable-formats Default
projects / yt-dlp.git / blobdiff