Install & Compatibility
Where this runs
tested against v2026.8.27.3630.dev0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.724s · 57.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.694s · 60MB
60MB installed
● package 60MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YoutubeDL
✓ from yt_dlp import YoutubeDL
✗ import youtube_dl
yt-dlp is a separate project from the original youtube-dl, and its module is named 'yt_dlp'.
YoutubeDL
✓ from yt_dlp import YoutubeDL
✗ import ytdlp
The PyPI package name is 'yt-dlp' (hyphen), but the Python module name is 'yt_dlp' (underscore).
This quickstart demonstrates how to use `yt-dlp` as a Python library to download a video. It configures options to download the best quality MP4 video and audio, then merges them, saving the file with the video's title. For more advanced options like specifying output directories, proxies, or authentication, the `ydl_opts` dictionary should be extended.
import yt_dlp
def download_video(url):
ydl_opts = {
'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best',
'outtmpl': '%(title)s.%(ext)s',
'merge_output_format': 'mp4'
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
info_dict = ydl.extract_info(url, download=False)
video_title = info_dict.get('title', 'Unknown Title')
print(f"Downloading: {video_title}")
ydl.download([url])
print("Download complete!")
if __name__ == '__main__':
# Replace with a real video URL for testing. Use an anonymous public video.
# For authenticated downloads, configure 'cookiefile' in ydl_opts.
video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" # Example URL
download_video(video_url)
yt-dlp --version
Debug
Known issues
breakingYouTube frequently changes its backend mechanisms, which can temporarily break `yt-dlp`'s ability to download or extract information from YouTube videos. Functionality often breaks without a fixed schedule.fixUsers are strongly advised to update `yt-dlp` regularly. For the quickest fixes, consider installing the nightly release: `pip install -U --pre "yt-dlp[default]"` or `yt-dlp --update-to nightly` for standalone binaries. Report persistent issues on the official GitHub page.
affects: All versions, due to external site changes.
gotcha`ffmpeg` and `ffprobe` are *essential external binaries* (not Python packages) for merging separate audio/video streams, format conversion, embedding metadata, and various post-processing tasks. Without them, `yt-dlp`'s functionality will be severely limited, often resulting in separate audio and video files or inability to download certain formats.fixEnsure `ffmpeg` and `ffprobe` are installed on your system and are accessible in your system's PATH. Official `yt-dlp` documentation provides links to patched `ffmpeg` builds that resolve common issues.
affects: All versions, if not installed/configured.
gotchaFor full YouTube support, an external JavaScript runtime (such as Deno, Node.js, or Bun) is often required in addition to the `yt-dlp-ejs` Python dependency. Recent YouTube changes necessitate a proper JS runtime to solve video extraction challenges, as `yt-dlp`'s built-in interpreter is often insufficient.fixInstall Deno (recommended) or another supported JavaScript runtime on your system. Ensure `yt-dlp-ejs` is installed (it's part of `yt-dlp[default]`).
affects: Versions from 2025.09.25 onwards, or earlier versions attempting YouTube downloads.
breaking`yt-dlp` regularly updates its minimum required Python version. Using older Python versions can lead to `ModuleNotFoundError` for internal dependencies, runtime errors, or lack of support for newer features and fixes.fixUpgrade your Python installation to meet the minimum requirements, currently Python 3.10+ (CPython) and 3.11+ (PyPy).
affects: Versions requiring Python 3.10+ (CPython) / 3.11+ (PyPy) and onwards.
gotchaFor authentication on certain sites, particularly YouTube, using cookies is generally more reliable and recommended than OAuth. OAuth integration for `yt-dlp` has been noted to be unstable or broken.fixUtilize the `--cookies-from-browser` CLI option or the `cookiefile` option in `ydl_opts` to pass browser cookies for authentication instead of relying on OAuth.
affects: All versions, particularly for YouTube authentication.
Errors
Common errors & fixes
ERROR: Signature extraction failed
YouTube frequently changes its internal video playback mechanisms (specifically signature algorithms), which breaks yt-dlp's ability to extract necessary video information.
fixUpdate yt-dlp to the latest version by running `yt-dlp -U` or `pip install --upgrade yt-dlp`.
ERROR: FFmpeg not found. Please install it.
yt-dlp requires FFmpeg for various post-processing tasks like merging audio/video streams, converting formats, and embedding metadata, but it is not bundled with yt-dlp.
fixInstall FFmpeg on your system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download from ffmpeg.org) and ensure its executable is in your system's PATH.
ERROR: [youtube] This video is age-restricted. Please sign in to confirm your age.
The video creator has applied an age restriction, and yt-dlp cannot bypass this restriction without proper authentication (e.g., a signed-in session or cookies).
fixProvide authentication credentials, for example, by loading cookies from your browser: `yt-dlp --cookies-from-browser firefox "URL"` (replace `firefox` with your browser) or using username/password: `yt-dlp --username YOUR_USERNAME --password YOUR_PASSWORD "URL"`.
ERROR: Unable to download webpage: HTTP Error 403: Forbidden
The website has detected and blocked the download attempt, or the content is geo-restricted, or requires specific headers/cookies that are not being sent.
fixTry using a proxy (`yt-dlp --proxy "http://YOUR_PROXY:PORT" "URL"`), providing cookies (`yt-dlp --cookies-from-browser chrome "URL"`), or setting a user-agent (`yt-dlp --user-agent "Mozilla/5.0 ..." "URL"`).
Upgrade
Version history
2026.8.19latest on PyPI · released Aug 19, 2026
Audit
Dependencies
PythonrequiredRequired runtime; versions 3.10+ (CPython) and 3.11+ (PyPy) are supported.
FFmpeg and FFprobeoptionalStrongly recommended external binaries (not Python packages) for merging separate audio/video streams, format conversion, embedding metadata, and various post-processing tasks. Must be in system PATH.
yt-dlp-ejsoptionalRequired for full YouTube support and solving JavaScript challenges. Automatically included with `yt-dlp[default]` installation. Requires an external JavaScript runtime (e.g., Deno, Node.js, Bun).
JavaScript runtime (e.g., Deno, Node.js)optionalRequired by `yt-dlp-ejs` to execute JavaScript challenges on sites like YouTube, crucial for successful downloads. Deno is recommended.