diff --git a/.github/ISSUE_TEMPLATE/1_broken_site.yml b/.github/ISSUE_TEMPLATE/1_broken_site.yml
index af0320569c..cdbb867603 100644
--- a/.github/ISSUE_TEMPLATE/1_broken_site.yml
+++ b/.github/ISSUE_TEMPLATE/1_broken_site.yml
@@ -1,5 +1,5 @@
name: Broken site
-description: Report broken or misfunctioning site
+description: Report error in a supported site
labels: [triage, site-bug]
body:
- type: checkboxes
@@ -7,7 +7,7 @@ body:
label: DO NOT REMOVE OR SKIP THE ISSUE TEMPLATE
description: Fill all fields even if you think it is irrelevant for the issue
options:
- - label: I understand that I will be **blocked** if I remove or skip any mandatory\* field
+ - label: I understand that I will be **blocked** if I *intentionally* remove or skip any mandatory\* field
required: true
- type: checkboxes
id: checklist
@@ -16,15 +16,15 @@ body:
description: |
Carefully read and work through this check list in order to prevent the most common mistakes and misuse of yt-dlp:
options:
- - label: I'm reporting a broken site
+ - label: I'm reporting that a **supported** site is broken
required: true
- - label: I've verified that I'm running yt-dlp version **2022.09.01** ([update instructions](https://github.com/yt-dlp/yt-dlp#update)) or later (specify commit)
+ - label: I've verified that I'm running yt-dlp version **2023.03.04** ([update instructions](https://github.com/yt-dlp/yt-dlp#update)) or later (specify commit)
required: true
- label: I've checked that all provided URLs are playable in a browser with the same IP and same login details
required: true
- label: I've checked that all URLs and arguments with special characters are [properly quoted or escaped](https://github.com/yt-dlp/yt-dlp/wiki/FAQ#video-url-contains-an-ampersand--and-im-getting-some-strange-output-1-2839-or-v-is-not-recognized-as-an-internal-or-external-command)
required: true
- - label: I've searched the [bugtracker](https://github.com/yt-dlp/yt-dlp/issues?q=) for similar issues **including closed ones**. DO NOT post duplicates
+ - label: I've searched [known issues](https://github.com/yt-dlp/yt-dlp/issues/3766) and the [bugtracker](https://github.com/yt-dlp/yt-dlp/issues?q=) for similar issues **including closed ones**. DO NOT post duplicates
required: true
- label: I've read the [guidelines for opening an issue](https://github.com/yt-dlp/yt-dlp/blob/master/CONTRIBUTING.md#opening-an-issue)
required: true
@@ -50,6 +50,8 @@ body:
options:
- label: Run **your** yt-dlp command with **-vU** flag added (`yt-dlp -vU
([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_linux_armv7l](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux_armv7l)|Linux standalone armv7l (32-bit) binary
+[yt-dlp_linux_aarch64](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux_aarch64)|Linux standalone aarch64 (64-bit) binary
[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
@@ -209,11 +234,20 @@ File|Description
:---|:---
[yt-dlp.tar.gz](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz)|Source tarball
[SHA2-512SUMS](https://github.com/yt-dlp/yt-dlp/releases/latest/download/SHA2-512SUMS)|GNU-style SHA512 sums
+[SHA2-512SUMS.sig](https://github.com/yt-dlp/yt-dlp/releases/latest/download/SHA2-512SUMS.sig)|GPG signature file for SHA512 sums
[SHA2-256SUMS](https://github.com/yt-dlp/yt-dlp/releases/latest/download/SHA2-256SUMS)|GNU-style SHA256 sums
+[SHA2-256SUMS.sig](https://github.com/yt-dlp/yt-dlp/releases/latest/download/SHA2-256SUMS.sig)|GPG signature file for SHA256 sums
+
+The public key that can be used to verify the GPG signatures is [available here](https://github.com/yt-dlp/yt-dlp/blob/master/public.key)
+Example usage:
+```
+curl -L https://github.com/yt-dlp/yt-dlp/raw/master/public.key | gpg --import
+gpg --verify SHA2-256SUMS.sig SHA2-256SUMS
+gpg --verify SHA2-512SUMS.sig SHA2-512SUMS
+```
-
-Note: The manpages, shell completion files etc. are available in the [source tarball](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz)
+**Note**: The manpages, shell completion files etc. are available inside the [source tarball](https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz)
## DEPENDENCIES
Python versions 3.7+ (CPython and PyPy) are supported. Other versions and implementations may or may not work correctly.
@@ -229,8 +263,9 @@ While all the other dependencies are optional, `ffmpeg` and `ffprobe` are highly
* [**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)
-
- **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
+ There are bugs in ffmpeg 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 some of 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
+
+ **Important**: What you need is ffmpeg *binary*, **NOT** [the python package of the same name](https://pypi.org/project/ffmpeg)
### 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)
@@ -275,7 +310,9 @@ To build the standalone executable, you must have Python and `pyinstaller` (plus
On some systems, you may need to use `py` or `python` instead of `python3`.
-Note that pyinstaller with versions below 4.4 [do not support](https://github.com/pyinstaller/pyinstaller#requirements-and-tested-platforms) Python installed from the Windows store without using a virtual environment.
+`pyinst.py` accepts any arguments that can be passed to `pyinstaller`, such as `--onefile/-F` or `--onedir/-D`, which is further [documented here](https://pyinstaller.org/en/stable/usage.html#what-to-generate).
+
+**Note**: Pyinstaller versions below 4.4 [do 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.
@@ -298,11 +335,15 @@ If you wish to build it anyway, install Python and py2exe, and then simply run `
### Related scripts
-* **`devscripts/update-version.py [revision]`** - Update the version number based on current date
-* **`devscripts/set-variant.py variant [-M update_message]`** - Set the build variant of the executable
+* **`devscripts/update-version.py`** - Update the version number based on current date.
+* **`devscripts/set-variant.py`** - Set the build variant of the executable.
+* **`devscripts/make_changelog.py`** - Create a markdown changelog using short commit messages and update `CONTRIBUTORS` file.
* **`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
+Note: See their `--help` for more info.
+
+### Forking the project
+If you fork the project on GitHub, you can run your fork's [build workflow](.github/workflows/build.yml) to automatically build the selected version(s) as artifacts. Alternatively, you can run the [release workflow](.github/workflows/release.yml) or enable the [nightly workflow](.github/workflows/release-nightly.yml) to create full (pre-)releases.
# USAGE AND OPTIONS
@@ -318,6 +359,11 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--version Print program version and exit
-U, --update Update this program to the latest version
--no-update Do not check for updates (default)
+ --update-to [CHANNEL]@[TAG] Upgrade/downgrade to a specific version.
+ CHANNEL and TAG defaults to "stable" and
+ "latest" respectively if omitted; See
+ "UPDATE" for details. Supported channels:
+ stable, nightly
-i, --ignore-errors Ignore download and postprocessing errors.
The download will be considered successful
even if the postprocessing fails
@@ -408,6 +454,8 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--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
+ --enable-file-urls Enable file:// URLs. This is disabled by
+ default for security reasons.
## Geo-restriction:
--geo-verification-proxy URL Use this proxy to verify the IP address for
@@ -426,23 +474,24 @@ You can also fork the project on github and run your fork's [build workflow](.gi
explicitly provided IP block in CIDR notation
## Video Selection:
- -I, --playlist-items ITEM_SPEC Comma separated playlist_index of the videos
+ -I, --playlist-items ITEM_SPEC Comma separated playlist_index of the items
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. E.g. "-I 1:3,7,-5::2" used on a
- playlist of size 15 will download the videos
+ playlist of size 15 will download the items
at index 1,2,3,7,11,13,15
- --min-filesize SIZE Do not download any videos smaller than
+ --min-filesize SIZE Abort download if filesize is smaller than
+ SIZE, e.g. 50k or 44.6M
+ --max-filesize SIZE Abort download if filesize is larger 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]].
- E.g. --date today-2weeks
+ E.g. "--date today-2weeks" downloads only
+ videos uploaded on the same day two weeks ago
--datebefore DATE Download only videos uploaded on or before
this date. The date formats accepted is the
same as --date
@@ -469,7 +518,10 @@ You can also fork the project on github and run your fork's [build workflow](.gi
dogs" (caseless). Use "--match-filter -" to
interactively ask whether to download each
video
- --no-match-filter Do not use generic video filter (default)
+ --no-match-filter Do not use any --match-filter (default)
+ --break-match-filters FILTER Same as "--match-filters" but stops the
+ download process when a video is rejected
+ --no-break-match-filters Do not use any --break-match-filters (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
@@ -483,11 +535,9 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--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 --break-on-existing, --break-on-reject,
- --max-downloads, and autonumber resets per
- input URL
+ --break-per-input Alters --max-downloads, --break-on-existing,
+ --break-match-filter, and autonumber to
+ reset per 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
@@ -519,8 +569,8 @@ You can also fork the project on github and run your fork's [build workflow](.gi
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
+ (Alias: --no-abort-on-unavailable-fragments)
+ --abort-on-unavailable-fragments
Abort download if a fragment is unavailable
(Alias: --no-skip-unavailable-fragments)
--keep-fragments Keep downloaded fragments on disk after
@@ -562,7 +612,7 @@ You can also fork the project on github and run your fork's [build workflow](.gi
Needs ffmpeg. This option can be used
multiple times to download multiple
sections, e.g. --download-sections
- "*10:15-15:00" --download-sections "intro"
+ "*10:15-inf" --download-sections "intro"
--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
@@ -679,8 +729,7 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--cache-dir DIR Location in the filesystem where yt-dlp can
store some downloaded information (such as
client ids and signatures) permanently. By
- default $XDG_CACHE_HOME/yt-dlp or
- ~/.cache/yt-dlp
+ default ${XDG_CACHE_HOME}/yt-dlp
--no-cache-dir Disable filesystem caching
--rm-cache-dir Delete all filesystem cache files
@@ -720,7 +769,7 @@ You can also fork the project on github and run your fork's [build workflow](.gi
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).
+ --use-postprocessor (default: video).
Implies --quiet. Implies --simulate unless
--no-simulate or later stages of WHEN are
used. This option can be used multiple times
@@ -773,7 +822,7 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--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,
+ --add-headers 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
@@ -888,11 +937,11 @@ You can also fork the project on github and run your fork's [build workflow](.gi
specific bitrate like 128K (default 5)
--remux-video FORMAT Remux the video into another container if
necessary (currently supported: avi, flv,
- mkv, mov, mp4, webm, aac, aiff, alac, flac,
- m4a, mka, mp3, ogg, opus, vorbis, wav). If
- target container does not support the
- video/audio codec, remuxing will fail. You
- can specify multiple rules; e.g.
+ gif, mkv, mov, mp4, webm, aac, aiff, alac,
+ flac, m4a, mka, mp3, ogg, opus, vorbis,
+ wav). If target container does not support
+ the video/audio codec, remuxing will fail.
+ You can specify multiple rules; e.g.
"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
@@ -947,13 +996,18 @@ You can also fork the project on github and run your fork's [build workflow](.gi
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
+ --parse-metadata [WHEN:]FROM:TO
+ Parse additional metadata like title/artist
from other fields; see "MODIFYING METADATA"
- for details
- --replace-in-metadata FIELDS REGEX REPLACE
+ for details. Supported values of "WHEN" are
+ the same as that of --use-postprocessor
+ (default: pre_process)
+ --replace-in-metadata [WHEN:]FIELDS REGEX REPLACE
Replace text in a metadata field using the
given regex. This option can be used
- multiple times
+ multiple times. Supported values of "WHEN"
+ are the same as that of --use-postprocessor
+ (default: pre_process)
--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
@@ -974,18 +1028,18 @@ You can also fork the project on github and run your fork's [build workflow](.gi
--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
+ when to execute it, separated by a ":".
+ Supported values of "WHEN" are the same as
+ that of --use-postprocessor (default:
+ after_move). 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,_filename|)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: ass, lrc, srt, vtt)
@@ -1023,14 +1077,16 @@ You can also fork the project on github and run your fork's [build workflow](.gi
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
+ "video" (after --format; before
+ --print/--output), "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,
@@ -1041,10 +1097,10 @@ Make chapter entries for, or remove various segments (sponsor,
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. E.g.
+ music_offtopic, poi_highlight, chapter, all
+ and default (=all). You can prefix the
+ category with a "-" to exclude it. See [1]
+ for description of the categories. E.g.
--sponsorblock-mark all,-preview
[1] https://wiki.sponsor.ajay.app/w/Segment_Categories
--sponsorblock-remove CATS SponsorBlock categories to be removed from
@@ -1053,8 +1109,8 @@ Make chapter entries for, or remove various segments (sponsor,
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
+ refers to "all,-filler" and poi_highlight,
+ chapter are not available
--sponsorblock-chapter-title TEMPLATE
An output template for the title of the
SponsorBlock chapters created by
@@ -1079,29 +1135,40 @@ Make chapter entries for, or remove various segments (sponsor,
--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
+ --extractor-args IE_KEY:ARGS Pass ARGS arguments to the IE_KEY extractor.
+ See "EXTRACTOR ARGUMENTS" for details. You
+ can use this option multiple times to give
arguments for different extractors
# CONFIGURATION
You can configure yt-dlp by placing any supported command line option to a configuration file. The configuration is loaded from the following locations:
-1. **Main Configuration**: The file given by `--config-location`
-1. **Portable Configuration**: `yt-dlp.conf` in the same directory as the bundled binary. If you are running from source-code (`