How to Use Plugins in yt-dlp

Note that all plugins are imported even if not invoked, and that there are no checks performed on plugin code. Use plugins at your own risk and only if you trust the code!

Plugins can be of <type>s extractor or postprocessor.

• Extractor plugins do not need to be enabled from the CLI and are automatically invoked when the input URL is suitable for it.
• Extractor plugins take priority over built-in extractors.
• Postprocessor plugins can be invoked using --use-postprocessor NAME.

Plugin Structure

Plugins are loaded from the namespace packages yt_dlp_plugins.extractor and yt_dlp_plugins.postprocessor.

In other words, the file structure on the disk looks something like:

yt_dlp_plugins/
    extractor/
        myplugin.py
    postprocessor/
        myplugin.py

yt-dlp looks for these yt_dlp_plugins namespace folders in many locations (see below) and loads in plugins from all of them. Set the environment variable YTDLP_NO_PLUGINS to something nonempty to disable loading plugins entirely.

See the wiki for some known plugins

Installing Plugins

Plugins can be installed using various methods and locations.

1. Configuration Directories

Plugin packages (containing a yt_dlp_plugins namespace folder) can be dropped into the following standard configuration locations:

User Plugins

• ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plugins/ (recommended on Linux/macOS)
• ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
• ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/ (recommended on Windows)
• ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
• ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
• ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/

System Plugins

• /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
• /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/

2. Executable Location

Plugin packages can similarly be installed in a yt-dlp-plugins directory under the executable location (recommended for portable installations):

• Binary: where <root-dir>/yt-dlp.exe, <root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/
• Source: where <root-dir>/yt_dlp/__main__.py, <root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/

3. pip and other locations in PYTHONPATH

• Plugin packages can be installed and managed using pip. See yt-dlp-sample-plugins for an example.
  • Note: plugin files between plugin packages installed with pip must have unique filenames.
• Any path in PYTHONPATH is searched in for the yt_dlp_plugins namespace folder.
  • Note: This does not apply for Pyinstaller builds.

Archive Support

.zip, .egg and .whl archives containing a yt_dlp_plugins namespace folder in their root are also supported as plugin packages.

• e.g. ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip where mypluginpkg.zip contains yt_dlp_plugins/<type>/myplugin.py

Run yt-dlp with --verbose to check if the plugin has been loaded.

Developing Plugins

See the yt-dlp-sample-plugins repo for a template plugin package and the Plugin Development section of the wiki for a plugin development guide.

All public classes with a name ending in IE/PP are imported from each file for extractors and postprocessors respectively. This respects underscore prefix (e.g. _MyBasePluginIE is private) and __all__. Modules can similarly be excluded by prefixing the module name with an underscore (e.g. _myplugin.py).

To replace an existing extractor with a subclass of one, set the plugin_name class keyword argument (e.g. class MyPluginIE(ABuiltInIE, plugin_name='myplugin') will replace ABuiltInIE with MyPluginIE). Since the extractor replaces the parent, you should exclude the subclass extractor from being imported separately by making it private using one of the methods described above.

If you are a plugin author, add yt-dlp-plugins as a topic to your repository for discoverability.

See the Developer Instructions on how to write and test an extractor.