yt dlp plugins

yt-dlp plugins

Available in 2026.11.0. Added by PR #179.

Plugins add extractors or postprocessors to yt-dlp. Open Settings > yt-dlp > Plugins.

Plugins run arbitrary Python inside the container and can read files and environment variables available to the app. Install only trusted plugins, and protect Settings with Basic Auth or SSO. Extractor plugins take priority over built-in extractors and can change or break indexing and downloads.

Install

• Upload a .zip, .whl or .egg archive, then select Save Plugin. The maximum archive size is 25 MB.
• Paste a direct archive URL and select Install from URL. GitHub release assets are allowed by default. See the URL policy for other hosts.
• Alternatively, place a package in /config/extras/yt-dlp-plugins yourself. A folder must contain yt_dlp_plugins/, for example my-plugin/yt_dlp_plugins/extractor/my_extractor.py.

Uploaded and URL-installed archives must contain yt_dlp_plugins/ at their root. Wrapper directories, unsafe paths and missing namespaces are rejected. An unrelated archive cannot replace an installed package with the same filename through a new install; remove it first.

Successful installation adds an entry under Installed Plugins. This confirms the archive was saved, not that its Python imports or dependencies work. Check the next indexing or download operation and plugin diagnostics.

Packages persist on the /config volume. Installing plugins does not move or delete existing media or rewrite queued jobs. Subsequent operations through the app's yt-dlp command runner load managed plugins with --plugin-dirs; Browse search uses a separate command and does not load them.

Update and remove

URL-installed packages remember their source URL. Update downloads that URL again and replaces the archive; a version-pinned URL stays pinned. There are no automatic background plugin updates. A failed metadata write rejects the install and attempts to restore the previous archive during replacement.

Remove deletes the package and its per-plugin config. It does not delete downloaded media. Removing a plugin can make later operations that depend on it fail. Keep your trusted archive and config if you need to reinstall them.

Per-plugin config

Select Config, enter the plugin's documented yt-dlp options, then select Save Config. Files are stored under /config/extras/yt-dlp-plugin-configs and loaded with --config-locations on subsequent commands through the app's yt-dlp command runner. Options apply globally, not only to that plugin.

For a postprocessor, include --use-postprocessor NAME in its config or the base yt-dlp config. The editor starts empty because plugins do not expose a config schema. The maximum config size is 64 KB. Clear, or saving blank contents, removes that config.

When available, the editor displays bundled README text. Archive READMEs over 20 KB are hidden; folder READMEs are truncated at 20 KB. The README is documentation, not a list of automatically supported settings.

Limits and recovery

• Installing an archive does not install Python dependencies. Packages importing libraries such as requests, pyotp or nodriver need those dependencies supplied in the container.
• The bundled bgutil PO-token plugin cannot be installed again through Settings. Configure POT_PROVIDER_URL instead; see Installation.
• yt-dlp's plugin API can change across yt-dlp versions. A valid archive can still contain an incompatible or broken plugin.
• For URL rejections, check the host allowlist, redirect hosts and private-address policy in the environment reference. Each redirect is validated and each response is size-limited.
• If a new plugin breaks indexing or downloads, remove it and retry the affected work. If Settings is unavailable, stop the app, move that package and its matching config out of the managed directories, then start the app again. Preserve copies for diagnosis; do not remove bundled container files.

Import failures are logged and can notify Apprise. See Diagnostics. A successful fixture or provider lookup does not establish that a full download will complete with every plugin.