types-yt-dlp

2026.3.17.20260408 verified Fri May 01 auth: no python

Typing stubs for yt-dlp, providing type hints for the yt-dlp library. Current version 2026.3.17.20260408, released weekly by typeshed. Compatible with Python >=3.10.

pip install types-yt-dlp

Common errors

error ModuleNotFoundError: No module named 'yt_dlp' ↓

cause yt-dlp library not installed.

fix

Run 'pip install yt-dlp'

error ImportError: cannot import name 'YoutubeDL' from 'yt_dlp' ↓

cause Typo or wrong case. Correct name is 'YoutubeDL'.

fix

Use 'from yt_dlp import YoutubeDL'

error TypeError: 'tuple' object is not callable ↓

cause Accidentally overwritten tuple or misused options dict.

fix

Ensure options dict does not contain keys that conflict with function names.

error yt_dlp.utils.DownloadError: ERROR: unable to download video ↓

cause Network issue, invalid URL, or YouTube blocking.

fix

Check URL, network, and consider using cookies or proxies.

Warnings

gotcha The stub package must be installed separately; it does not ship with yt-dlp. Forgetting to install types-yt-dlp results in missing type hints. ↓

fix Run 'pip install types-yt-dlp' or add it to your dev dependencies.

deprecated Old import patterns like 'from yt_dlp.utils import ...' may not be fully covered by stubs. Prefer top-level imports. ↓

fix Use 'from yt_dlp import ...' for main classes.

gotcha The stubs are generated from typeshed and may lag behind yt-dlp releases. Newer yt-dlp features might not have type hints. ↓

fix Check the yt-dlp version compatibility; upgrade types-yt-dlp regularly.

Imports

YoutubeDL
```
from yt_dlp import YoutubeDL
```
The types stub mirrors the yt-dlp package structure.

Quickstart

Minimal example showing typed usage of YoutubeDL.

import yt_dlp

def download(url: str) -> None:
    ydl_opts = {'quiet': True}
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
        info = ydl.extract_info(url, download=False)
        print(info.get('title', 'No title'))

download('https://www.youtube.com/watch?v=dQw4w9WgXcQ')