How do I create a plugin for yt-dlp?

A template plugin package repository is available at yt-dlp/yt-dlp-sample-plugins.

To see how to write extractors in general, see the yt-dlp developer instructions.
For information regarding the plugin spec, see the plugins section of the yt-dlp README.

Getting Started

Create a new repository based on yt-dlp/yt-dlp-sample-plugins
Check out the source code with: git clone git@github.com:YOUR_GITHUB_USERNAME/YOUR_REPOSITORY.git
Configure your IDE's run and debug configuration (optional)
Write your plugin code in the yt_dlp_plugins/<type> folder (where type is either extractor or postprocessor). See the sample plugins provided and the yt-dlp developer instructions for more details.
- Some instructions given will not apply to plugin development, but should give you a good idea on what to do.
- The method for testing extractor plugins is the same as with built-in ones.
Configure your plugin package

Add the new files, commit them and push the result, like this:

 $ git add yt_dlp_plugins setup.cfg README.md
 $ git commit -m 'Add yourplugin plugin'
 $ git push origin master

Configuring your plugin package

Modify setup.cfg with your plugin's name and version. It is recommended to bump the version whenever you make changes or a new release.
Update the installation instructions on README.md to point to this repository.
Add yt-dlp-plugins to the repository tags for discoverability.
Be sure to remove any of the sample extractors/post-processors.

Run and debug configuration

Set your IDE's run configuration to point to the yt_dlp Python module.
Add your project's root directory containing yt_dlp_plugins to PYTHONPATH environment variable (this may not be necessary with some IDE run configurations).
The yt_dlp_plugins folder should be automatically picked up by yt-dlp (run with -v to check).

Importing extractors from other plugins

from yt_dlp_plugins.extractor.example import ExampleIE

This works regardless of where the example plugin is installed on the system, as long as yt-dlp can find it. Your IDE may not be able to resolve the import, but it will work at runtime.

If the user does not have the example plugin installed, the import will fail and your extractor will not be imported (but yt-dlp will continue to run).

The same applies for any other plugin type.

Poetry configuration

If you want your plugin to be installable with poetry, you can add the following to your pyproject.toml:

[tool.poetry]
...
packages = [{ include = "yt_dlp_plugins" }]
...

See the Poetry documentation for more details.