You are reading the documentation for the in-development version of Streamlink.

Plugin sideloading

Streamlink supports overriding its built-in plugins or loading custom third party plugins without having to modify its sources or its built and installed Python distribution. This is called plugin sideloading.

Those additional plugin modules will automatically be loaded from the paths listed below, or from the path(s) of the --plugin-dir CLI argument, if it is set.

Attention

Do not attempt to modify built-in plugins or to add custom plugins to Streamlink's built Python distribution. In order to keep loading times low, Streamlink implements a lazy plugin-loading system for its built-in plugins, which means that pluginmatcher and pluginargument data is pre-computed and cached, thus making modifications to plugin modules or adding new plugin modules pointless. Instead, sideload plugins.

Warning

If one of the sideloaded plugins fails to load and execute, e.g. due to a SyntaxError being raised by the parser, then this exception won't be caught by Streamlink and the execution will stop, even if the input stream URL does not match the faulty plugin.

Note

Custom plugin modules will always be loaded and executed at once, increasing the load and initialization time of the Streamlink session. Built-in plugins on the other hand are loaded lazily, unless overridden.

Overriding

If a plugin is added with the same name as a built-in plugin, then the added plugin will take precedence. This can be useful for upgrading or modifying plugins independently of the Streamlink version.

In this case, a log message will be written to log level debug:

[session][debug] Plugin PLUGINNAME is being overridden by PATH-TO-PLUGIN-FILE (sha256:CHECKSUM)

Sideloading locations

Platform	Location
Linux, BSD	Path ${XDG_DATA_HOME:-${HOME}/.local/share}/streamlink/plugins Example /home/USERNAME/.local/share/streamlink/plugins
macOS	Path ${HOME}/Library/Application Support/streamlink/plugins Example /Users/USERNAME/Library/Application Support/streamlink/plugins
Windows	Path %APPDATA%\streamlink\plugins Example C:\Users\USERNAME\AppData\Roaming\streamlink\plugins