Dependencies

Required and optional dependencies for yt-dlp functionality

yt-dlp has minimal required dependencies, but several optional dependencies unlock additional features and capabilities.

Python Requirements

Python versions 3.10+ (CPython) and 3.11+ (PyPy) are supported. Other versions and implementations may or may not work correctly.

If you’re using the standalone binary releases, Python is already included and you don’t need to install it separately.

Strongly Recommended

While technically optional, these dependencies are highly recommended for full functionality:

FFmpeg and FFprobe

ffmpeg and ffprobe are essential for most common use cases.

Required for:

• Merging separate video and audio files
• Converting between formats
• Embedding thumbnails and metadata
• Post-processing tasks (cutting, trimming, etc.)
• Downloading HLS/DASH streams

License: Depends on the build

There are bugs in ffmpeg that cause various issues when used with yt-dlp. We provide custom builds with patches that fix these issues.

Download patched builds: yt-dlp/FFmpeg-Builds

Important: You need the ffmpeg binary, NOT the Python package of the same name.

Installing FFmpeg

# Check if ffmpeg is installed
ffmpeg -version

# Linux (Debian/Ubuntu)
sudo apt install ffmpeg

# macOS (Homebrew)
brew install ffmpeg

# Windows
# Download from https://github.com/yt-dlp/FFmpeg-Builds/releases

yt-dlp-ejs

yt-dlp-ejs - Required for full YouTube support.

License: Unlicense, bundles MIT and ISC components

Requires a JavaScript runtime:

• deno (recommended)
• node.js
• bun
• QuickJS

Standalone binaries typically include yt-dlp-ejs. For pip installations, see the EJS wiki for setup instructions.

Networking Dependencies

These enhance network functionality and protocol support:

Core Networking

Package	Purpose	License
certifi*	Mozilla’s root certificate bundle	MPLv2
brotli* or brotlicffi	Brotli content encoding support	MIT
websockets*	Downloading over websocket	BSD-3-Clause
requests*	HTTP library for HTTPS proxy and persistent connections	Apache-2.0

Browser Impersonation

These enable impersonating browser requests to bypass TLS fingerprinting:

curl_cffi (recommended)

curl_cffi - Python binding for curl-impersonate. Provides impersonation for Chrome, Edge, and Safari.

License: MIT

# Install with curl-cffi extra
pip install "yt-dlp[default,curl-cffi]"

curl_cffi is included in most official builds except:

• yt-dlp (Unix zipimport binary)
• yt-dlp_x86 (Windows 32-bit)
• yt-dlp_musllinux_aarch64

Metadata Dependencies

For embedding thumbnails and writing metadata:

Package	Purpose	License
mutagen*	Embedding thumbnails in various formats	GPLv2+
AtomicParsley	Embedding thumbnails in MP4/M4A when mutagen/ffmpeg cannot	GPLv2+
xattr	Writing xattr metadata on Mac	MIT
pyxattr	Writing xattr metadata on BSD	LGPL2.1
setfattr	Writing xattr metadata (system tool)	GPLv2+

Example: Embedding Thumbnails

yt-dlp --embed-thumbnail URL

# For MP4 files without mutagen, AtomicParsley is used
# Install on Ubuntu/Debian:
sudo apt install atomicparsley

Miscellaneous Dependencies

Package	Purpose	License
pycryptodomex*	Decrypting AES-128 HLS streams	BSD-2-Clause
secretstorage*	Accessing Gnome keyring for browser cookies on Linux	BSD-3-Clause
Any external downloader	For use with --downloader	Varies

Deprecated Dependencies

These are no longer recommended but still supported:

These dependencies are deprecated. ffmpeg can be used instead for most use cases.

Package	Purpose	Alternative
rtmpdump	Downloading RTMP streams	Use ffmpeg: --downloader ffmpeg
mplayer or mpv	Downloading RSTP/MMS streams	Use ffmpeg: --downloader ffmpeg
phantomjs	Running JavaScript (some extractors)	No longer needed for YouTube

Checking Available Dependencies

To see which dependencies are currently available:

yt-dlp --verbose URL

The verbose output displays all detected dependencies at the top.

If you attempt a task requiring a missing dependency, yt-dlp will warn you with a specific message about what’s needed.

Installing Dependencies

Via pip (Python installation)

# Install with recommended dependencies
pip install "yt-dlp[default]"

# Install with all extras
pip install "yt-dlp[default,curl-cffi]"

Standalone Binaries

Packages marked with * are included in the standalone release binaries.

If you’re using a standalone binary, you already have:

• Python interpreter
• certifi
• brotli/brotlicffi
• websockets
• requests
• mutagen
• pycryptodomex
• secretstorage (Linux builds)
• curl_cffi (most builds)

You only need to install external tools like:

• ffmpeg/ffprobe
• AtomicParsley
• External downloaders (aria2c, wget, etc.)

Licensing Considerations

To use or redistribute yt-dlp with dependencies, you must agree to their respective licensing terms.

The standalone PyInstaller-bundled executables include GPLv3+ licensed code (from dependencies like mutagen), so the combined work is licensed under GPLv3+.

The source code, source tarball, and PyPI packages contain only Unlicense code.

For complete licensing details, see THIRD_PARTY_LICENSES.txt in the repository.