Skip to content
Back to top
View this page
Edit this page

# Migrations

## streamlink 8.0.0

### HLSStream url_master argument

Support for the deprecated `url_master` argument and respective class attribute in `HLSStream` and `MuxedHLSStream` has been removed.

#6688

Migration

`HLSStream` and `MuxedHLSStream` objects which originate from a multivariant (master) playlist should receive a reference to the `M3U8` instance of the parsed multivariant playlist via the `multivariant` argument. The `multivariant.uri` attribute is a string of the multivariant playlist address.

## streamlink 7.0.0

### Config file paths

Support for the old and deprecated config file paths, including plugin-specific config file paths, has been removed.

#3766
#6149

Migration

Please switch to the config file paths listed in the Configuration file section of the CLI docs, or use the `--config` CLI argument to set custom config file paths.

### Custom plugins sideloading paths

Support for the old and deprecated custom plugins sideloading paths has been removed.

#3766
#6150

Migration

Please see the plugins directory paths listed in the Plugin sideloading section of the CLI docs, or use the `--plugin-dir` CLI argument to set the path to another location.

### Stream-type related CLI arguments

The deprecated `--hls-segment-{attempts,threads,timeout}` and `--{hls,http-stream}-timeout` CLI arguments, as well as their deprecated `{dash,hls}-segment-{attempts,threads,timeout}` and `{dash,hls,http-stream}-timeout` session option counterparts have been removed.

#3893
#6232

Migration

CLI arguments

- use `--stream-segment-attempts` instead of `--hls-segment-attempts`

- use `--stream-segment-threads` instead of `--hls-segment-threads`

- use `--stream-segment-timeout` instead of `--hls-segment-timeout`

- use `--stream-timeout` instead of `--{hls,http-stream}-timeout`

Session options

- use `stream-segment-attempts` instead of `{dash,hls}-segment-attempts`

- use `stream-segment-threads` instead of `{dash,hls}-segment-threads`

- use `stream-segment-timeout` instead of `{dash,hls}-segment-timeout`

- use `stream-timeout` instead of `{dash,hls,http-stream}-timeout`

### HTTPSession and HTTPAdapters

The deprecated import paths for the `HTTPSession` class and custom `HTTPAdapter` classes have been removed.

#5807
#6274

Migration

Plugin implementors were never supposed to import the `HTTPSession` class directly, and instead should always reference the `http` attribute of Streamlink's `session` attribute in instances of `Plugin`.

Import Streamlink's custom `HTTPAdapter` classes from `streamlink.session.http`.

### streamlink.plugins re-exports

The deprecated import paths for the `NoPluginError`, `NoStreamsError`, `PluginError`, and `Plugin` classes have been removed.

#6005
#6274

Migration

Import error classes from `streamlink.exceptions` or `streamlink.plugin`.

Import the `Plugin` class from `streamlink.plugin`.

### --force-progress

The deprecated `--force-progress` CLI argument has been removed.

#5268
#6196

Migration

Use `--progress=force` instead of `--force-progress`.

## streamlink 6.0.0

### Player-path-only --player CLI argument

Despite having the dedicated CLI argument for setting custom player arguments `--player-args`, Streamlink used to support setting custom player arguments using the `--player` CLI argument.

This meant that the `--player` value had to be treated as a command line string rather than a player path. As a result of this, player paths would need to be quoted if they contained whitespace characters. While the default config file of Streamlink's Windows installer tried to teach this, it was often used incorrectly on command-line shells, especially on Windows where escaping the CLI argument is more difficult compared to POSIX compliant command-line shells. Not quoting the player path on Windows still worked, but at the cost of potentially resolving an incorrect or malicious executable.

The support for custom player arguments in `--player` was a relic from the Livestreamer project and has finally been removed. `--player` now only accepts player executable path strings and any custom player arguments need to be set using the `--player-args` CLI argument where the argument value gets properly interpreted using shell-like syntax.

Streamlink's Windows installer has received a new default config file and users now also can choose to overwrite their existing config file from previous installs. The default behavior remains the same with existing config files staying untouched.

#5305
#5310

Migration

1. Move any custom player arguments from the value of `--player` to `--player-args`

2. In config files, remove any quotation from the value of `--player` (command-line shells will of course require quotation when the player path contains whitespace characters)

### {filename} variable in --player-args

The `--player-args`'s `{filename}` variable has been removed. This was kept as a fallback when the `{playerinput}` variable as added to prevent confusion around the player's input argument for various different stream transport methods, like stdin, named pipes, passthrough, etc.

#3313
#5310

Migration

1. Rename `{filename}` to `{playerinput}`

### Plugin.can_handle_url() and Plugin.priority()

Streamlink 2.3.0 deprecated the `can_handle_url()` and `priority()` classmethods of `Plugin` in favor of the plugin matcher API. These deprecated classmethods have now been removed.

#3814
#5403

Migration

1. Replace custom matching logic in `Plugin.can_handle_url()` with `pluginmatcher` decorators

2. Replace custom plugin priority matching logic in `Plugin.priority()` with the `priority` argument of the `pluginmatcher` decorators

### Plugin.__init__(self, url) compatibility wrapper

Streamlink 5.0.0 deprecated the usage of the old `Plugin` constructor without the `Streamlink` `session` argument. `session` was added because the old `Plugin.bind()` classmethod got removed, which previously bound the session instance to the entire `Plugin` class, rather than individual `Plugin` instances, causing Python's garbage collector to not be able to let go of any loaded built-in plugins when initializing more than one session.

#4768
#5402

Migration

1. Replace the arguments of custom constructors of each `Plugin` subclass with `*args, **kwargs` and call `super().__init__(*args, **kwargs)`

2. If needed, access the `url` using `self.url`

### Streamlink.{g,s}et_plugin_option()

The `Streamlink.get_plugin_option()` and `Streamlink.set_plugin_option()` methods were removed as a result of moving plugin options from the `Plugin` classes to individual `Plugin` instances.

Plugin options now must be get/set referencing the `Plugin.options` instance and its respective `get()` and `set()` methods.

Alternatively, when initializing a `Plugin` class, e.g. after calling `Streamlink.resolve_url()` or `Streamlink.streams()`, an optional pre-initialized instance of `Options` can be passed to the constructor of the resolved `Plugin` class.

Be aware that `Streamlink.resolve_url()` will return the explicit plugin name, plugin class and the resolved URL, whereas `Streamlink.streams()` will initialize the first matching plugin automatically, so it's possible to pass custom options to a different plugin by accident, if the URL matches an unintended plugin.

#5033

Migration

1. Initialize an `Options` object with the desired key-value pairs and pass it to the `Plugin` constructor or the `Streamlink.streams()` method.

2. After instantiating a `Plugin` class, get or set its options using the `get()`/`set()` methods on the `Plugin.options` instance.

3. If plugin options need to be accessed in custom `Stream` implementations related to custom `Plugin` implementations, then those options need to be passed from the `Plugin` to the `Stream` constructor beforehand, since the `Streamlink` session can't be used for that anymore.

Before

    from streamlink.session import Streamlink

    session = Streamlink()
    session.set_plugin_option("twitch", "api-header", [("Authorization", "OAuth TOKEN")])
    streams = session.streams("twitch.tv/...")

After

    from streamlink.options import Options
    from streamlink.session import Streamlink

    session = Streamlink()
    options = Options()
    options.set("api-header", [("Authorization", "OAuth TOKEN")])
    streams = session.streams("twitch.tv/...", options)

Alternative

    from streamlink.options import Options
    from streamlink.session import Streamlink

    session = Streamlink()
    pluginname, Pluginclass, resolved_url = session.resolve_url("twitch.tv/...")
    options = Options()
    options.set("api-header", [("Authorization", "OAuth TOKEN")])
    plugin = Pluginclass(session, resolved_url, options)
    streams = plugin.streams()

### Global plugin arguments

Streamlink 5.3.0 deprecated the `is_global=True` argument of the `pluginargument` decorator (as well as the `Argument` class), as global plugin arguments were deemed unnecessary. The `is_global` argument has thus been removed now.

#5140
#5033

Migration

1. Get the value of the global argument using `Streamlink.get_option()` instead of getting it from `Plugin.options`

### plugin.api.validate.text

Streamlink 5.2.0 deprecated the `plugin.api.validate.text` alias for `str`. This was a remnant of the Python 2 era and has been removed.

#5090
#5404

Migration

1. Replace `plugin.api.validate.text` with `str`

### HTTPStream and HLSStream signature changes

The signatures of the constructors of `HTTPStream` and `HLSStream`, as well as the `HLSStream.parse_variant_playlist()` classmethod were changed and fixed.

#5429

Migration

1. Set the `Streamlink` session instance as a positional argument, or replace the `session_` keyword with `session`

## streamlink 5.0.0

### Session.resolve_url() return type changes

With the removal of the `Plugin.bind()` classmethod, the return value of `Streamlink.resolve_url()` and `Streamlink.resolve_url_no_redirect()` were changed. Both methods now return a three-element tuple of the resolved plugin name, plugin class and URL.

#4768

Migration

1. Return type changed from `tuple[type[Plugin], str]` to `tuple[str, type[Plugin], str]`

## streamlink 4.0.0

### streamlink.plugin.api.utils

The `streamlink.plugin.api.utils` module has been removed, including the `itertags` function and the export aliases for `streamlink.utils.parse`.

#4455
#4467

Migration

1. Write validation schemas using the `parse_{html,json,xml}()` validators. Parsed HTML/XML documents enable data extraction with XPath queries.

2. Alternatively, import the `parse_{html,json,qsd,xml}()` utility functions from the `streamlink.utils.parse` module

## streamlink 3.0.0

### Plugin class returned by Session.resolve_url()

In order to enable `Plugin` constructors to have access to plugin options derived from the resolved plugin arguments, `Plugin` instantiation moved from `Streamlink.resolve_url()` to `streamlink_cli`, and the return value of `Streamlink.resolve_url()` and `Streamlink.resolve_url_no_redirect()` were changed.

#4163

Migration

1. Return type changed from `Plugin` to `tuple[type[Plugin], str]`