Repository navigation
Youtube downloader plugin
Use Hydra's official YouTube Downloader plugin (hydra.youtube) to download a single YouTube video, selected playlist entries, or audio only. The plugin uses yt-dlp to discover media tracks; Hydra downloads the media and ffmpeg combines video and audio or converts audio.
This guide covers the plugin implemented in the repository. If an option is missing in your installed release, check your Hydra and plugin versions before following the examples.
Download youtube-download.hyaplugin from the Hydra releases page. Plugins are installed separately from Hydra.
- Open Options → Extensions & Plugins → Plugins.
- Enter the downloaded package path and choose Review permissions.
- Review the publisher and requested permissions, then accept and install.
- Open the installed plugin's settings to configure the backend, JavaScript runtime, and cookies.
Run these commands from the folder containing the downloaded package:
hydra plugin inspect youtube-download.hyaplugin
hydra plugin install youtube-download.hyaplugin --accept-permissions
hydra plugin info hydra.youtubeName: YouTube Downloader
ID: hydra.youtube
Author: Hydra Team
Version: 0.1.0
Signature: Unsigned
Enabled: true
Location: /Users/javad/.config/hydra/plugins/hydra.youtube/versions/0b35d7794e8db18fd2a1774e8e1e4518e0d8d8e20e2ea8b492e9176272961429
Install yt-dlp using its official installation instructions. Make yt-dlp (yt-dlp.exe on Windows) available on PATH. Install ffmpeg for merging separate video/audio tracks and converting audio; see Hydra ffmpeg integration.
To let the plugin download yt-dlp when it is missing:
hydra plugin set hydra.youtube download_backend true
hydra plugin check hydra.youtubeThe automatic download uses a fixed official release with SHA256 verification. In this repository, that release is 2026.08.19; it does not automatically replace an existing approved backend. Automatic installation supports macOS, Windows, and Linux on x64 and ARM64. Other platforms need a manually installed backend.
CLI and desktop installations share the same plugin settings within the same Hydra profile.
| Setting | Default | Purpose |
|---|---|---|
download_backend |
false |
Download the pinned yt-dlp release if the backend is missing. |
yt_dlp_path |
Unset | Folder containing the yt-dlp program when it is outside PATH. |
javascript_runtime |
default |
Select default, node, or deno for yt-dlp's player challenges. |
use_cookies |
false |
Allow yt-dlp to use cookies supplied to Hydra for the download. |
If yt-dlp is outside PATH, set its containing folder, then approve the executable:
hydra plugin set hydra.youtube yt_dlp_path "/path/to/tools"
hydra plugin grant hydra.youtube exec:yt-dlp
hydra plugin check hydra.youtubeWindows example:
hydra plugin set hydra.youtube yt_dlp_path "C:\Tools\yt-dlp"
hydra plugin grant hydra.youtube exec:yt-dlpThe folder must contain yt-dlp.exe on Windows. Hydra pins the approved executable by its file hash. After updating or replacing yt-dlp, review the new program and run the grant command again.
If logs report a missing JavaScript runtime or player challenge failures, install Node.js or Deno, make it available to Hydra, then select it:
hydra plugin set hydra.youtube javascript_runtime nodeFor Deno, use deno instead of node. Changing this setting does not install the runtime. Restart Hydra or your terminal after changing PATH.
Replace VIDEO_ID with the video's ID. Quote URLs so the shell preserves & and other special characters.
hydra "https://www.youtube.com/watch?v=VIDEO_ID"In a terminal, Hydra offers quality and audio choices when you have not specified them. To use flags and defaults without prompts:
hydra --no-input --quality 1080 --container mkv "https://www.youtube.com/watch?v=VIDEO_ID"Inspect available tracks without downloading:
hydra --list-tracks "https://www.youtube.com/watch?v=VIDEO_ID"Download a specific video track without an additional audio track, using an ID from that list:
hydra --no-input --audio none --track FORMAT_ID "https://www.youtube.com/watch?v=VIDEO_ID"Short links (https://youtu.be/VIDEO_ID) and Shorts links (https://www.youtube.com/shorts/VIDEO_ID) are also supported. For browser cookie import, prefer the full www.youtube.com/watch?v=... URL: Hydra imports cookies for the host in the supplied URL, and a youtu.be URL does not select the YouTube login cookies.
In the desktop app, use Add URL, paste the video URL, wait for inspection, then choose the video/audio tracks and output container before starting. Subtitles can be selected when available and are saved as sidecar files.
Use a dedicated playlist URL:
hydra --no-input --quality 720 --container mkv "https://www.youtube.com/playlist?list=PLAYLIST_ID"Hydra expands the playlist into ordered video jobs. Inspection is limited to the first 512 entries; unavailable items may be absent, and duplicate video IDs are removed. Listing an entry does not guarantee that its video can be downloaded: each video's media formats must also resolve successfully.
In the desktop app, paste the playlist URL into Add URL, select the entries you want, choose quality/audio preferences, and start the selected jobs. The CLI example processes the resolved entries; there is no playlist item selection flag in the current CLI.
A watch URL containing &list=... still downloads one video. For example:
| URL | Result |
|---|---|
https://www.youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID |
The single video. |
https://www.youtube.com/playlist?list=PLAYLIST_ID |
The playlist's available entries, within the inspection limit. |
Keep the original audio format:
hydra --no-input --extract-audio "https://www.youtube.com/watch?v=VIDEO_ID"Convert to MP3 with ffmpeg:
hydra --no-input --extract-audio --audio-format mp3 "https://www.youtube.com/watch?v=VIDEO_ID"The same options work with a playlist:
hydra --no-input --extract-audio --audio-format mp3 "https://www.youtube.com/playlist?list=PLAYLIST_ID"Supported conversion formats are mp3, m4a, opus, flac, and wav. In the desktop app, select Audio only and choose an extraction format.
Start without cookies for public videos. Use a browser session when YouTube requires sign-in or bot verification, or when accessing a private playlist or other content your account can view. Cookies do not grant access beyond that account's permissions.
Two things must be configured: enable use_cookies in the plugin, and supply cookies to the download through Hydra. Enabling the plugin setting alone does not import a browser session.
-
Open the target video in your browser and confirm it plays. Sign in or complete any verification YouTube requests.
-
Enable the plugin's cookie setting:
hydra plugin set hydra.youtube use_cookies true
-
Download using the browser profile that can access the video:
hydra --cookies-from-browser firefox --no-input --quality 1080 --container mkv "https://www.youtube.com/watch?v=VIDEO_ID"
For a specific Chrome profile:
hydra --cookies-from-browser "chrome:Profile 2" --no-input --quality 1080 --container mkv "https://www.youtube.com/watch?v=VIDEO_ID"For a playlist:
hydra --cookies-from-browser firefox --no-input --quality 720 --container mkv "https://www.youtube.com/playlist?list=PLAYLIST_ID"Hydra supports Firefox, LibreWolf, Zen, Chrome, Chromium, Edge, Brave, Vivaldi, Opera, and Safari cookie stores. Use the correct browser and profile; a profile where you are signed out will not provide the needed login session.
- Open Options → Cookies.
- Set Use cookies from to your browser and choose the Profile, if needed.
- Save the settings.
- In Options → Extensions & Plugins → Plugins, enable Use granted browser cookies for YouTube Downloader.
- Open Add URL with a full YouTube URL. Wait for cookie import and video/playlist inspection before starting the download.
The Add URL dialog reports the cookie source or an import error. Downloads captured by Hydra's browser extension already carry the page's cookies; the browser picker applies to manually added downloads.
Export the YouTube session in Mozilla/Netscape cookies.txt format, then supply it to Hydra:
hydra plugin set hydra.youtube use_cookies true
hydra --load-cookies "/private/path/youtube-cookies.txt" --no-input --quality 1080 --container mkv "https://www.youtube.com/watch?v=VIDEO_ID"Use --load-cookies to read the file without writing it back. Replace the watch URL with a dedicated playlist URL to download a playlist with the same session.
YouTube can rotate session cookies. If an exported session stops working, export it again; the upstream YouTube cookie export guide explains a private-window export procedure. Hydra's browser import reads the browser's stored profile cookies, so use an exported file for that private-window session.
The plugin receives only cookies covered by its granted YouTube domains through a temporary Netscape file, which Hydra removes after yt-dlp exits. Keep your exported file private: cookies are session credentials. Do not attach cookie files or cookie values to GitHub issues.
To stop supplying cookies to the backend:
hydra plugin set hydra.youtube use_cookies false- Open the same video in your browser on the same connection and complete any verification.
- Confirm
use_cookiesis enabled and use that browser's signed-in profile or a fresh exported cookie file. - Retry with the full
www.youtube.com/watch?v=...URL. - Check plugin logs if the error remains. Cookies cannot guarantee that YouTube will accept a request.
Playlist inspection retrieves an entry list. Resolving each video's downloadable tracks is a separate request, which can fail because of bot verification, account restrictions, unavailable content, or missing formats.
Copy the failing entry's watch URL and try it by itself with the same cookies. If that also fails, troubleshoot the video/session before retrying the playlist. In the GUI, select fewer entries to isolate the failure.
Check the browser/profile selection and the source path reported by Hydra. On macOS, grant Full Disk Access in System Settings → Privacy & Security to the terminal running Hydra, or to the Hydra desktop app, then restart that application and retry.
If browser database access or decryption still fails, use a fresh Netscape cookie export with --load-cookies. For file-format requirements, see the yt-dlp cookie FAQ.
Install yt-dlp on PATH, set yt_dlp_path to its containing folder, or enable download_backend. If you changed its folder or updated the executable, approve the new binary:
hydra plugin grant hydra.youtube exec:yt-dlp
hydra plugin check hydra.youtubeDo not disable executable verification to work around an approval error.
Confirm ffmpeg is installed and visible to the process running Hydra:
ffmpeg -versionThen restart Hydra and retry. High-quality video commonly has a separate audio track. Select audio in the GUI or keep the CLI's default --audio best; --audio none intentionally omits an additional audio track. Try --container mkv if the selected codecs cannot be combined in your chosen container.
Check the selected JavaScript runtime and the approved yt-dlp version. Update a manually installed backend through its installation method, then grant exec:yt-dlp again. The plugin's automatic backend download does not upgrade an existing approved binary.
For transfer failures, retry the original YouTube page URL to resolve fresh media links. Avoid changing the proxy or network between inspection and transfer: extracted URLs can depend on the connection used to obtain them. See the yt-dlp extracted URL FAQ.
Some YouTube formats require additional backend features such as PO tokens. The current Hydra plugin has no setting for PO tokens or arbitrary yt-dlp extractor arguments. See the upstream YouTube extractor notes when cookies and runtime setup do not resolve the failure.
The plugin supports direct HTTP media tracks. Live streams, DRM-protected formats, and formats available only through segmented manifests are unsupported. Cookies do not remove these limitations. A requested resolution or track must be available in the resolved track list.
Pause downloads and retry later. Reduce the number of playlist entries attempted together. Repeated immediate retries can prolong the problem; upstream documents this error as a YouTube request rate limit.
Hydra runs yt-dlp with --ignore-config, --no-plugin-dirs, and --skip-download. Configure the supported settings in Hydra. Adding cookie options, extractor arguments, or third-party yt-dlp plugins to your normal yt-dlp configuration will not affect this resolver.
Check that the plugin is installed and enabled:
hydra plugin list
hydra plugin enable hydra.youtube
hydra plugin check hydra.youtubeUse a supported watch, short, Shorts, or dedicated playlist URL. Remove --no-plugins from the download command. To explicitly select the YouTube plugin:
hydra --plugin hydra.youtube --list-tracks "https://www.youtube.com/watch?v=VIDEO_ID"hydra --version
hydra plugin info hydra.youtube
hydra plugin check hydra.youtube
hydra plugin logs hydra.youtubeIn the desktop app, choose View plugin logs in plugin settings. Report your OS, Hydra/plugin versions, backend installation method and version, selected runtime, exact error, and whether a single video or playlist failed. Include a public reproducing URL when possible. Review logs before posting and redact credentials, cookie values, private URLs, and signed media links.
Report reproducible problems in Hydra issues. Download only content you are authorized to save.