yt-dlp Wiki

yt-dlp supports a plugin system that allows users to extend its functionality. Plugins are categorized into three main types:

1. Extractors: Plugins that add support for new sites or modify how existing sites are handled (e.g., bypassing age-gates or handling PO Tokens).
2. Postprocessors: Plugins that run after the download is complete to modify the file or metadata (e.g., fixing subtitle formats, applying replaygain to audio, or modifying file timestamps).
3. Other: General purpose extensions (e.g., unlocking browser cookie databases or managing system wake locks).

You can find a curated list of community-maintained plugins on the yt-dlp-plugins GitHub topic.

PO Tokens are subject to continuous changes by YouTube. Key technical constraints include:

• Platform Specificity: Tokens are generated by platform-specific attestation providers (BotGuard for Web, DroidGuard for Android, iOSGuard for iOS). A token from one platform cannot be used on another.
• Content Binding: Most tokens (e.g., for web GVS/Player) are bound to the video ID. This means a new token must be generated for every unique video.
• Lifespan: Tokens have a limited lifespan (ranging from ~12 hours to potentially several months) and must be refreshed periodically.

You can use alternative plugins to yt-dlp-ejs for solving JS challenges.

One featured plugin is yt-dlp-apple-webkit-jsi (by grqz), which provides an experimental Apple WebKit JS Challenge Provider for Apple devices.

Developer Note: Currently, only the base JavaScript Challenge Provider API is public. The API for hooking into yt-dlp's internal EJS scripts is private and subject to breaking changes.

You can import extractors from other installed plugins using standard Python import syntax. This works as long as yt-dlp can find the plugin on the system.

Note on IDEs: Your IDE might show an unresolved import error, but the import will function correctly at runtime.

Error Handling: If the required plugin is not installed on the user's system, the import will fail. In this case, your extractor will not be imported, but yt-dlp will continue to run without crashing.

from yt_dlp_plugins.extractor.example import ExampleIE

If you prefer not to use cookies, you can pass Visitor Data for use in Innertube API requests.

Warning: This method is not recommended for most users. It requires skipping webpage requests to prevent the VISITOR_INFO1_LIVE cookie from interfering, which leads to less stable extraction and more requests being sent.

Use the following --extractor-args configuration:

--extractor-args "youtubetab:skip=webpage" --extractor-args "youtube:player_skip=webpage,configs;visitor_data=VISITOR_DATA_VALUE_HERE"

To avoid re-downloading videos from a playlist, use the --download-archive feature. This maintains a text file of successfully downloaded video IDs. Subsequent runs will skip any ID present in this file.

# Initial run to create the archive
yt-dlp --download-archive archive.txt "https://www.youtube.com/playlist?list=..."

# Subsequent runs will only download new videos
yt-dlp --download-archive archive.txt "https://www.youtube.com/playlist?list=..."

To avoid manual token management, use a plugin that automatically generates and provides tokens to yt-dlp.

Featured Plugins

• bgutil-ytdlp-pot-provider: Uses BgUtils to generate tokens. Maintained by a yt-dlp maintainer.
• yt-dlp-getpot-wpc: Uses a browser session to generate tokens. Useful as a fallback. Maintained by a yt-dlp core maintainer.

To find more options, search the yt-dlp-pot-provider GitHub topic.

Instead of installing local packages, you can instruct yt-dlp to download EJS scripts remotely. This is useful for third-party package users and allows for automatic updates. It is recommended to add these to your yt-dlp configuration file.

Download from npm

Supported Runtimes: Deno and Bun only. Use the following flag:

--remote-components ejs:npm

Download from GitHub

Downloads scripts directly from the yt-dlp/ejs repository. Use the following flag:

--remote-components ejs:github

Note: This may fail if your network restricts access to GitHub or GitHub release assets (e.g., when using --force-ipv6).

YouTube requires a Proof of Origin (PO) Token for certain clients to prevent HTTP 403 errors or IP/account blocking. A PO Token is an attestation that requests are coming from a genuine client (Web, Android, or iOS).

You can provide PO Tokens to yt-dlp in two ways:

1. Manually: Use the po_token extractor argument.
2. Automatically (Recommended): Install a PO Token Provider plugin that hooks into the YouTube extractor to fetch tokens dynamically.

Note: Manually extracting tokens is no longer recommended because YouTube now binds PO Tokens to specific video IDs, requiring a new token for every video.

Cookies can be used to bypass login requirements or solve CAPTCHAs.

1. From Browser: Use --cookies-from-browser <browser_name> (e.g., chrome, firefox). For Flatpak Chrome on Linux, use --cookies-from-browser chrome:~/.var/app/com.google.Chrome/.
2. From File: Use --cookies <path_to_file>. The file must be in Mozilla/Netscape format and start with # HTTP Cookie File or # Netscape HTTP Cookie File.
3. Exporting: You can extract cookies from a browser to a file using: yt-dlp --cookies-from-browser chrome --cookies cookies.txt.

# Extract from browser
yt-dlp --cookies-from-browser chrome

# Use a specific cookie file
yt-dlp --cookies /path/to/cookies/file.txt

# Export cookies to a file for later use
yt-dlp --cookies-from-browser chrome --cookies cookies.txt

To ensure your plugin is correctly identified and discoverable, follow these steps:

1. Metadata: Modify setup.cfg with your unique plugin name and version. It is recommended to bump the version for every change or release.
2. Documentation: Update the installation instructions in your README.md to point to your specific repository.
3. Discoverability: Add the yt-dlp-plugins tag to your repository tags.
4. Cleanup: Remove any sample extractors or post-processors included in the template before publishing.