{"library":"yt-dlp","title":"yt-dlp","description":"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.","status":"active","version":"2026.3.17","language":"en","source_language":"en","source_url":"https://github.com/yt-dlp/yt-dlp","tags":["video-downloader","audio-downloader","media","youtube","cli-wrapper","web-scraping"],"install":[{"cmd":"pip install yt-dlp","lang":"bash","label":"Basic Installation"},{"cmd":"pip install -U --pre \"yt-dlp[default]\"","lang":"bash","label":"Nightly/Pre-release with default dependencies (recommended for latest fixes)"}],"dependencies":[{"reason":"Required runtime; versions 3.10+ (CPython) and 3.11+ (PyPy) are supported.","package":"Python","optional":false},{"reason":"Strongly recommended external binaries (not Python packages) for merging separate audio/video streams, format conversion, embedding metadata, and various post-processing tasks. Must be in system PATH.","package":"FFmpeg and FFprobe","optional":true},{"reason":"Required for full YouTube support and solving JavaScript challenges. Automatically included with `yt-dlp[default]` installation. Requires an external JavaScript runtime (e.g., Deno, Node.js, Bun).","package":"yt-dlp-ejs","optional":true},{"reason":"Required by `yt-dlp-ejs` to execute JavaScript challenges on sites like YouTube, crucial for successful downloads. Deno is recommended.","package":"JavaScript runtime (e.g., Deno, Node.js)","optional":true}],"imports":[{"note":"yt-dlp is a separate project from the original youtube-dl, and its module is named 'yt_dlp'.","wrong":"import youtube_dl","symbol":"YoutubeDL","correct":"from yt_dlp import YoutubeDL"},{"note":"The PyPI package name is 'yt-dlp' (hyphen), but the Python module name is 'yt_dlp' (underscore).","wrong":"import ytdlp","symbol":"YoutubeDL","correct":"from yt_dlp import YoutubeDL"}],"quickstart":{"code":"import yt_dlp\n\ndef download_video(url):\n    ydl_opts = {\n        'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best',\n        'outtmpl': '%(title)s.%(ext)s',\n        'merge_output_format': 'mp4'\n    }\n    with yt_dlp.YoutubeDL(ydl_opts) as ydl:\n        info_dict = ydl.extract_info(url, download=False)\n        video_title = info_dict.get('title', 'Unknown Title')\n        print(f\"Downloading: {video_title}\")\n        ydl.download([url])\n    print(\"Download complete!\")\n\nif __name__ == '__main__':\n    # Replace with a real video URL for testing. Use an anonymous public video.\n    # For authenticated downloads, configure 'cookiefile' in ydl_opts.\n    video_url = \"https://www.youtube.com/watch?v=dQw4w9WgXcQ\" # Example URL\n    download_video(video_url)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, due to external site changes."},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions, if not installed/configured."},{"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]`).","message":"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.","severity":"gotcha","affected_versions":"Versions from 2025.09.25 onwards, or earlier versions attempting YouTube downloads."},{"fix":"Upgrade your Python installation to meet the minimum requirements, currently Python 3.10+ (CPython) and 3.11+ (PyPy).","message":"`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.","severity":"breaking","affected_versions":"Versions requiring Python 3.10+ (CPython) / 3.11+ (PyPy) and onwards."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly for YouTube authentication."}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}