yt-dlp is a feature-rich command-line audio/video downloader with support for thousands of sites. The project is a fork of youtube-dl based on the now inactive youtube-dlc.
INSTALLATION
Detailed instructions
Release Files
Update
Dependencies
Compile
USAGE AND OPTIONS
General Options
Network Options
Geo-restriction
Video Selection
Download Options
Filesystem Options
Thumbnail Options
Internet Shortcut Options
Verbosity and Simulation Options
Workarounds
Video Format Options
Subtitle Options
Authentication Options
Post-processing Options
SponsorBlock Options
Extractor Options
CONFIGURATION
Configuration file encoding
Authentication with netrc
Notes about environment variables
OUTPUT TEMPLATE
Output template examples
FORMAT SELECTION
Filtering Formats
Sorting Formats
Format Selection examples
MODIFYING METADATA
Modifying metadata examples
EXTRACTOR ARGUMENTS
PLUGINS
Installing Plugins
Developing Plugins
EMBEDDING YT-DLP
Embedding examples
CHANGES FROM YOUTUBE-DL
New features
Differences in default behavior
Deprecated options
CONTRIBUTING
Opening an Issue
Developer Instructions
WIKI
FAQ
You can install yt-dlp using the binaries, pip or one using a third-party package manager. See the wiki for detailed instructions
File | Description |
---|---|
yt-dlp | Platform-independent zipimport binary. Needs Python (recommended for Linux/BSD) |
yt-dlp.exe | Windows (Win8+) standalone x64 binary (recommended for Windows) |
yt-dlp_macos | Universal MacOS (10.15+) standalone executable (recommended for MacOS) |
File | Description |
---|---|
yt-dlp_x86.exe | Windows (Win8+) standalone x86 (32-bit) binary |
yt-dlp_linux | Linux standalone x64 binary |
yt-dlp_linux_armv7l | Linux standalone armv7l (32-bit) binary |
yt-dlp_linux_aarch64 | Linux standalone aarch64 (64-bit) binary |
yt-dlp_win.zip | Unpackaged Windows executable (no auto-update) |
yt-dlp_macos.zip | Unpackaged MacOS (10.15+) executable (no auto-update) |
yt-dlp_macos_legacy | MacOS (10.9+) standalone x64 executable |
File | Description |
---|---|
yt-dlp.tar.gz | Source tarball |
SHA2-512SUMS | GNU-style SHA512 sums |
SHA2-512SUMS.sig | GPG signature file for SHA512 sums |
SHA2-256SUMS | GNU-style SHA256 sums |
SHA2-256SUMS.sig | GPG signature file for SHA256 sums |
The public key that can be used to verify the GPG signatures is available here 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 (autocomplete) files etc. are available inside the source tarball
You can use yt-dlp -U
to update if you are using the release binaries
If you installed with pip, simply re-run the same command that was used to install the program
For other third-party package managers, see the wiki or refer to their documentation
There are currently three release channels for binaries: stable
, nightly
and master
.
stable
is the default channel, and many of its changes have been tested by users of the nightly
and master
channels.
The nightly
channel has releases scheduled to build every day around midnight UTC, for a snapshot of the project's new patches and changes. This is the recommended channel for regular users of yt-dlp. The nightly
releases are available from yt-dlp/yt-dlp-nightly-builds or as development releases of the yt-dlp
PyPI package (which can be installed with pip's --pre
flag).
The master
channel features releases that are built after each push to the master branch, and these will have the very latest fixes and additions, but may also be more prone to regressions. They are available from yt-dlp/yt-dlp-master-builds.
When using --update
/-U
, a release binary will only update to its current channel.--update-to CHANNEL
can be used to switch to a different channel when a newer version is available. --update-to [CHANNEL@]TAG
can also be used to upgrade or downgrade to specific tags from a channel.
You may also use --update-to
(
) to update to a channel on a completely different repository. Be careful with what repository you are updating to though, there is no verification done for binaries from different repositories.
Example usage:
yt-dlp --update-to master
switch to the master
channel and update to its latest release
yt-dlp --update-to [email protected]
upgrade/downgrade to release to stable
channel tag 2023.07.06
yt-dlp --update-to 2023.10.07
upgrade/downgrade to tag 2023.10.07
if it exists on the current channel
yt-dlp --update-to example/[email protected]
upgrade/downgrade to the release from the example/yt-dlp
repository, tag 2023.09.24
Important: Any user experiencing an issue with the stable
release should install or update to the nightly
release before submitting a bug report:
# To update to nightly from stable executable/binary: yt-dlp --update-to nightly # To install nightly with pip: python3 -m pip install -U --pre "yt-dlp[default]"
Python versions 3.9+ (CPython) and 3.10+ (PyPy) are supported. Other versions and implementations may or may not work correctly.
While all the other dependencies are optional, ffmpeg
and ffprobe
are highly recommended
ffmpeg and ffprobe - Required for merging separate video and audio files, as well as for various post-processing tasks. License depends on the build
There are bugs in ffmpeg that cause various issues when used alongside yt-dlp. Since ffmpeg is such an important dependency, we provide custom builds with patches for some of these issues at yt-dlp/FFmpeg-Builds. See the readme 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
certifi* - Provides Mozilla's root certificate bundle. Licensed under MPLv2
brotli* or brotlicffi - Brotli content encoding support. Both licensed under MIT 1 2
websockets* - For downloading over websocket. Licensed under BSD-3-Clause
requests* - HTTP library. For HTTPS proxy and persistent connections support. Licensed under Apache-2.0
The following provide support for impersonating browser requests. This may be required for some sites that employ TLS fingerprinting.
curl_cffi (recommended) - Python binding for curl-impersonate. Provides impersonation targets for Chrome, Edge and Safari. Licensed under MIT
Can be installed with the curl-cffi
group, e.g. pip install "yt-dlp[default,curl-cffi]"
Currently included in yt-dlp.exe
, yt-dlp_linux
and yt-dlp_macos
builds
mutagen* - For --embed-thumbnail
in certain formats. Licensed under GPLv2+
AtomicParsley - For --embed-thumbnail
in mp4
/m4a
files when mutagen
/ffmpeg
cannot. Licensed under GPLv2+
xattr, pyxattr or setfattr - For writing xattr metadata (--xattr
) on Mac and BSD. Licensed under MIT, LGPL2.1 and GPLv2+ respectively
pycryptodomex* - For decrypting AES-128 HLS streams and various other data. Licensed under BSD-2-Clause
phantomjs - Used in extractors where javascript needs to be run. Licensed under BSD-3-Clause
secretstorage* - For --cookies-from-browser
to access the Gnome keyring while decrypting cookies of Chromium-based browsers on Linux. Licensed under BSD-3-Clause
Any external downloader that you want to use with --downloader
avconv and avprobe - Now deprecated alternative to ffmpeg. License depends on the build
sponskrub - For using the now deprecated sponskrub options. Licensed under GPLv3+
rtmpdump - For downloading rtmp
streams. ffmpeg can be used instead with --downloader ffmpeg
. Licensed under GPLv2+
mplayer or mpv - For downloading rstp
/mms
streams. ffmpeg can be used instead with --downloader ffmpeg
. Licensed under GPLv2+
To use or redistribute the dependencies, you must agree to their respective licensing terms.
The standalone release binaries are built with the Python interpreter and the packages marked with * included.
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
To build the standalone executable, you must have Python and pyinstaller
(plus any of yt-dlp's optional dependencies if needed). The executable will be built for the same CPU architecture as the Python used.
You can run the following commands:
python3 devscripts/install_deps.py --include pyinstaller python3 devscripts/make_lazy_extractors.py python3 -m bundle.pyinstaller
On some systems, you may need to use py
or python
instead of python3
.
python -m bundle.pyinstaller
accepts any arguments that can be passed to pyinstaller
, such as --onefile/-F
or --onedir/-D
, which is further documented here.
Note: Pyinstaller versions below 4.4 do not support Python installed from the Windows store without using a virtual environment.
Important: Running pyinstaller
directly instead of using python -m bundle.pyinstaller
is not officially supported. This may or may not work correctly.
You will need the build tools python
(3.9+), zip
, make
(GNU), pandoc
* and pytest
*.
After installing these, simply run make
.
You can also run make yt-dlp
instead to compile only the binary without updating any of the additional files. (The build tools marked with * are not needed for this)
devscripts/install_deps.py
- Install dependencies for yt-dlp.
devscripts/update-version.py
- Update the version number based on the 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
to something nonempty to forcefully disable lazy extractor loading.
Note: See their --help
for more info.
If you fork the project on GitHub, you can run your fork's build workflow to automatically build the selected version(s) as artifacts. Alternatively, you can run the release workflow or enable the nightly workflow to create full (pre-)releases.
yt-dlp [OPTIONS] [--] URL [URL...]
Ctrl+F
is your friend :D
-h, --help Print this help text and exit --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 can be a repository as well. CHANNEL and TAG default to "stable" and "latest" respectively if omitted; See "UPDATE" for details. Supported channels: stable, nightly, master -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 --use-extractors NAMES Extractor names to use separated by commas. You can also use regexes, "all", "default" and "end" (end URL matching); e.g. --ies "holodex.*,end,youtube". Prefix the name with a "-" to exclude it, e.g. --ies default,-generic. Use --list-extractors for a list of extractor names. (Alias: --ies) --default-search PREFIX Use this prefix for unqualified URLs. E.g. "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 to --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 --plugin-dirs PATH Path to an additional directory to search for plugins. This option can be used multiple times to add multiple directories. Note that this currently only works for extractor plugins; postprocessor plugins can only be loaded from the default plugin directories --flat-playlist Do not extract the videos of a playlist, only list them --no-flat-playlist Fully extract the videos of a playlist (default) --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) --color [STREAM:]POLICY Whether to emit color codes in output, optionally prefixed by the STREAM (stdout or stderr) to apply the setting to. Can be one of "always", "auto" (default), "never", or "no_color" (use non color terminal sequences). Use "auto-tty" or "no_color-tty" to decide based on terminal support only. Can be used multiple times --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. E.g. --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
--proxy URL Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS proxy, specify a proper scheme, e.g. socks5://user:[email protected]: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 --impersonate CLIENT[:OS] Client to impersonate for requests. E.g. chrome, chrome-110, chrome:windows-10. Pass --impersonate="" to impersonate any client. Note that forcing impersonation for all requests may have a detrimental impact on download speed and stability --list-impersonate-targets List available clients to impersonate. -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-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 --xff VALUE How to fake X-Forwarded-For HTTP header to try bypassing geographic restriction. One of "default" (only when known to be useful), "never", an IP block in CIDR notation, or a two-letter ISO 3166-2 country code
-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 items at index 1,2,3,7,11,13,15 --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 --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" 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 are the same as --date --dateafter DATE Download only videos uploaded on or after this date. The date formats accepted are 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 at least one of the conditions is met. E.g. --match-filters !is_live --match-filters "like_count>?100 & description~='(?i)bcats & dogsb'" 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-filters -" to interactively ask whether to download each video --no-match-filters Do not use any --match-filters (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 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 --no-break-on-existing Do not stop the download process when encountering a file that is in the archive (default) --break-per-input Alters --max-downloads, --break-on-existing, --break-match-filters, 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 the playlist is skipped
-N, --concurrent-fragments N Number of fragments of a dash/hlsnative video that should be downloaded concurrently (default is 1) -r,&n