{"id":15067,"library":"youtube-dl","title":"youtube-dl","description":"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.","status":"maintenance","version":"2021.12.17","language":"en","source_language":"en","source_url":"https://github.com/ytdl-org/youtube-dl","tags":["video downloader","youtube","media","cli","audio"],"install":[{"cmd":"pip install youtube-dl","lang":"bash","label":"Official (Outdated) PyPI Release"},{"cmd":"pip install youtube-dl-nightly","lang":"bash","label":"Official Nightly Build (More Up-to-date)"},{"cmd":"pip install yt-dlp","lang":"bash","label":"Recommended Fork (yt-dlp)"},{"cmd":"brew install youtube-dl","lang":"bash","label":"macOS (Homebrew)"},{"cmd":"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","lang":"bash","label":"Linux/macOS (Manual Latest youtube-dl)"}],"dependencies":[{"reason":"Required for merging separately downloaded audio and video streams (e.g., for high-quality YouTube formats), and for many advanced post-processing features.","package":"ffmpeg"}],"imports":[{"symbol":"YoutubeDL","correct":"from youtube_dl import YoutubeDL"}],"quickstart":{"code":"import youtube_dl\n\nydl_opts = {\n    'format': 'bestvideo+bestaudio/best',\n    'outtmpl': '%(title)s.%(ext)s',\n    'noplaylist': True # Only download single video, not playlist\n}\n\ndef download_video(url):\n    try:\n        with youtube_dl.YoutubeDL(ydl_opts) as ydl:\n            ydl.download([url])\n        print(f\"Successfully downloaded: {url}\")\n    except Exception as e:\n        print(f\"Error downloading {url}: {e}\")\n\n# Replace with your desired video URL\nvideo_url = \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" \ndownload_video(video_url)","lang":"python","description":"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."},"warnings":[{"fix":"Install `yt-dlp` (`pip install yt-dlp`) or `youtube-dl-nightly` (`pip install youtube-dl-nightly`).","message":"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.","severity":"breaking","affected_versions":"<=2021.12.17"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially older ones."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are using Python 3.6 or newer. For `yt-dlp`, Python 3.10+ is recommended.","message":"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).","severity":"gotcha","affected_versions":"<3.6"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the Python package: `pip install youtube-dl` (or `pip install yt-dlp` for the recommended fork).","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.","error":"ModuleNotFoundError: No module named 'youtube_dl'"},{"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.","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.","error":"ERROR: This video is unavailable."},{"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.","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.","error":"ERROR: Signature extraction failed: Python interpreter path not found"},{"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.","cause":"This error occurs when `youtube-dl` tries to write filenames containing characters not supported by the default system encoding, often on Windows.","error":"UnicodeEncodeError: 'charmap' codec can't encode character..."}],"ecosystem":"pypi"}