youtube-dl

library2021.12.17pypiunverified

youtube-dl is a command-line program and Python library designed to download videos from YouTube.com and many other video-hosting sites. The official PyPI package, version `2021.12.17`, is no longer actively maintained and is significantly outdated. For current site compatibility, bug fixes, and new features, users are strongly recommended to use the `yt-dlp` fork or the `youtube-dl` nightly builds, which are built from the main repository's `master` branch.

http-networking

pip install youtube-dl

INSTALL

IMPORT

SIG · YOUTUBE-DL

youtube-dl

http-networkingenv2021.12.17

Install

2.8s avg

Import

847ms

Disk

60MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2021.12.17 · 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

musl

py 3.10–3.930 runs

installs and imports cleanly · install 0.0s · import 0.904s · 91.7MB

glibc

py 3.10–3.930 runs

installs and imports cleanly · install 2.8s · import 0.790s · 31MB

60MB installed

● package 60MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YoutubeDL

✓ from youtube_dl import YoutubeDL

This quickstart demonstrates how to programmatically download a video using the `youtube-dl` library. It configures the downloader to select the best available video and audio quality, merge them, and save the file with the video's title.

import youtube_dl ydl_opts = { 'format': 'bestvideo+bestaudio/best', 'outtmpl': '%(title)s.%(ext)s', 'noplaylist': True # Only download single video, not playlist } def download_video(url): try: with youtube_dl.YoutubeDL(ydl_opts) as ydl: ydl.download([url]) print(f"Successfully downloaded: {url}") except Exception as e: print(f"Error downloading {url}: {e}") # Replace with your desired video URL video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" download_video(video_url)

youtube-dl --version

Debug

Known issues

breakingThe official `youtube-dl` PyPI package (`2021.12.17`) is severely outdated and often fails to download from frequently updated sites like YouTube due to changes in their platforms. Most users should install `yt-dlp` (a feature-rich, actively maintained fork) or the `youtube-dl` nightly build for up-to-date functionality.

fix

Install `yt-dlp` (`pip install yt-dlp`) or `youtube-dl-nightly` (`pip install youtube-dl-nightly`).

affects: <=2021.12.17

gotchaSite extractors, especially for major platforms like YouTube, frequently break due to continuous website changes (e.g., API updates, new obfuscation techniques). This necessitates frequent updates to the downloader. Using an outdated version will often result in download failures.

fix

Regularly update the library (e.g., `pip install -U yt-dlp` or `youtube-dl -U` for manual installations) or switch to a more actively maintained fork/build.

affects: All versions, especially older ones.

gotchaExcessive or aggressive downloading can lead to your IP address being temporarily blocked (resulting in HTTP 429 'Too Many Requests' or 403 'Forbidden' errors) by video platforms.

fix

Implement `--sleep-interval` and `--max-sleep-interval` options to add delays between downloads. Consider using cookies with `--cookies-from-browser` to mimic legitimate browsing sessions.

affects: All versions

gotchaPython 2 support is deprecated and no longer fully functional or recommended. Modern development and `yt-dlp` primarily support Python 3.10+ (CPython) and 3.11+ (PyPy).

fix

Ensure you are using Python 3.6 or newer. For `yt-dlp`, Python 3.10+ is recommended.

affects: <3.6

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'youtube_dl'

The `youtube-dl` package has not been installed or is not accessible in the current Python environment. This can happen if the `youtube-dl.exe` (standalone binary) was downloaded instead of the Python package.

fix

Install the Python package: `pip install youtube-dl` (or `pip install yt-dlp` for the recommended fork).

ERROR: This video is unavailable.

The video may be genuinely unavailable, region-locked, private, or the `youtube-dl` extractor for the site is outdated and cannot properly access the video.

fix

Try updating the library (`youtube-dl -U` or `pip install -U yt-dlp`). If the issue persists, try a proxy (`--proxy`), provide cookies (`--cookies-from-browser`), or check if the video is truly available and not region-locked/private.

ERROR: Signature extraction failed: Python interpreter path not found

This error often indicates that `youtube-dl` or `yt-dlp` could not locate or execute the necessary JavaScript interpreter (like Node.js or a Python-based equivalent) to decode video signatures, which YouTube frequently changes. This typically occurs with outdated versions.

fix

Update `youtube-dl` or `yt-dlp` to the latest version. For `yt-dlp` especially, ensure `yt-dlp-ejs` and a JavaScript runtime (e.g., `deno` or `node.js`) are installed and accessible.

UnicodeEncodeError: 'charmap' codec can't encode character...

This error occurs when `youtube-dl` tries to write filenames containing characters not supported by the default system encoding, often on Windows.

fix

Set your system's console or terminal to use UTF-8 encoding (e.g., `chcp 65001` on Windows CMD). Alternatively, use the `--restrict-filenames` option to only allow ASCII characters, or a custom `outtmpl` that sanitizes names.

Upgrade

Version history

2021.12.17latest on PyPI · released Dec 16, 2021

Audit

Dependencies

ffmpegrequiredRequired for merging separately downloaded audio and video streams (e.g., for high-quality YouTube formats), and for many advanced post-processing features.

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

No resource links recorded.