youtube-dl

2021.12.17 · maintenance · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'youtube_dl'
```
cause 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.
```
cause 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
```
cause 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...
```
cause 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.

Warnings

breaking The 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`).
gotcha Site 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.
gotcha Excessive 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.
gotcha Python 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.

Install

pip install youtube-dl Official (Outdated) PyPI Release
pip install youtube-dl-nightly Official Nightly Build (More Up-to-date)
pip install yt-dlp Recommended Fork (yt-dlp)
brew install youtube-dl macOS (Homebrew)
sudo curl -L https://yt-dl.org/downloads/latest/youtube-dl -o /usr/local/bin/youtube-dl && sudo chmod a+rx /usr/local/bin/youtube-dl Linux/macOS (Manual Latest youtube-dl)

Imports

YoutubeDL
```
from youtube_dl import YoutubeDL
```

Quickstart

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)

view raw JSON →