yt-dlp

2026.3.17 · active · verified Sun Apr 05

yt-dlp is a feature-rich command-line audio/video downloader with support for thousands of sites. It is an actively maintained fork of `youtube-dl`, with frequent releases, often multiple times a month, to adapt to changes in video platforms and add new features.

Warnings

breaking YouTube 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.
Fix: Users 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.
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.
Fix: Ensure `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.
gotcha For 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.
Fix: Install Deno (recommended) or another supported JavaScript runtime on your system. Ensure `yt-dlp-ejs` is installed (it's part of `yt-dlp[default]`).
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.
Fix: Upgrade your Python installation to meet the minimum requirements, currently Python 3.10+ (CPython) and 3.11+ (PyPy).
gotcha For 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.
Fix: Utilize the `--cookies-from-browser` CLI option or the `cookiefile` option in `ydl_opts` to pass browser cookies for authentication instead of relying on OAuth.

Install

pip install yt-dlp Basic Installation
pip install -U --pre "yt-dlp[default]" Nightly/Pre-release with default dependencies (recommended for latest fixes)

Imports

YoutubeDL
```
from yt_dlp import YoutubeDL
```
yt-dlp is a separate project from the original youtube-dl, and its module is named 'yt_dlp'.
YoutubeDL
```
from yt_dlp import YoutubeDL
```
The PyPI package name is 'yt-dlp' (hyphen), but the Python module name is 'yt_dlp' (underscore).

Quickstart

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)

view raw JSON →