Install & Compatibility
Where this runs
tested against v8.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.946s · 75.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.7s · import 0.901s · 77MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Streamlink
✓ from streamlink import Streamlink
PluginError
✓ from streamlink.exceptions import PluginError
✗ from streamlink.plugins import PluginError
Re-exports of error classes from `streamlink.plugins` were deprecated in 6.8.0 and removed in 7.0.0. Import from `streamlink.exceptions` instead.
NoPluginError
✓ from streamlink.exceptions import NoPluginError
✗ from streamlink.plugins import NoPluginError
Re-exports of error classes from `streamlink.plugins` were deprecated in 6.8.0 and removed in 7.0.0. Import from `streamlink.exceptions` instead.
Plugin
✓ from streamlink.plugin import Plugin
✗ from streamlink.plugins import Plugin
Re-exports of the `Plugin` class from `streamlink.plugins` were deprecated in 6.8.0 and removed in 7.0.0. Import from `streamlink.plugin` instead.
HTTPSession
✓ session = Streamlink()
http_session = session.http
✗ from streamlink.plugin.api.http_session import HTTPSession
Direct import of `HTTPSession` from `streamlink.plugin.api` or `streamlink.plugin.api.http_session` was deprecated in 6.6.0 and removed in 7.0.0. Access it via the `Streamlink` session's `http` attribute.
This quickstart demonstrates how to use Streamlink programmatically to find and access streams from a given URL. It initializes a Streamlink session, sets an option, resolves streams for a Twitch URL, and attempts to open the 'best' quality stream. For actual media playback, the stream's file-like object would typically be piped to an external video player process.
import streamlink
import os
# Initialize a Streamlink session
session = streamlink.Streamlink()
# Example: Set a session option, e.g., for logging level
session.set_option("log-level", "info")
# Define the URL and desired stream quality
stream_url = "https://www.twitch.tv/twitchdev"
desired_quality = "best"
try:
# Attempt to find streams for the URL
streams = session.streams(stream_url)
if not streams:
print(f"No streams found for {stream_url}")
else:
# Get the desired stream
stream = streams.get(desired_quality)
if stream:
print(f"Opening {desired_quality} stream from {stream_url}")
# Open the stream and read a chunk (or pipe to a player)
with stream.open() as fd:
# This example just reads a small chunk. For actual playback,
# you'd typically pipe this to an external player.
# For example, to play with VLC (requires VLC to be installed and in PATH):
# import subprocess
# player_cmd = ["vlc", "-"]
# p = subprocess.Popen(player_cmd, stdin=subprocess.PIPE)
# for chunk in iter(lambda: fd.read(8192), b''):
# p.stdin.write(chunk)
# p.stdin.close()
# p.wait()
print(f"Successfully accessed {desired_quality} stream.")
# For a real application, you'd stream the data to a player or file
else:
print(f"Stream quality '{desired_quality}' not available. Available: {', '.join(streams.keys())}")
except streamlink.exceptions.NoPluginError:
print(f"No plugin found for URL: {stream_url}")
except streamlink.exceptions.PluginError as e:
print(f"Plugin error: {e}")
streamlink --version
Errors
Common errors & fixes
No playable streams found on this URL: <URL>
The Streamlink plugin for the given URL could not find any streams, often due to changes on the streaming service's side, an invalid URL, or the stream being offline.
fixFirst, verify the URL is correct and the stream is live. Try updating Streamlink (`pip install --upgrade streamlink`) to get the latest plugin definitions. You can also run with `--json` to see raw output or `--loglevel debug` for more details.
Error: Couldn't launch the Stream Unexpected Version check output. / urllib3 (X.Y) or chardet (X.Y.Z) doesn't match a supported version!
A common cause is an incompatibility between Streamlink's `urllib3` dependency (or `requests`' dependency on `urllib3`) and Streamlink's expected version.
fixUpgrade Streamlink and its dependencies: `pip install --upgrade streamlink`. This typically resolves `urllib3` version mismatches.
[stream.hls][warning] Encountered a stream discontinuity. This is unsupported and will result in incoherent output data.
This usually indicates an issue with the HLS stream itself, where segments are not continuous or metadata changes unexpectedly, leading to corrupted output or incomplete recordings.
fixThis often points to a problem with the source stream. Try different stream qualities (`best`, `worst`, or specific resolutions). If recording, try adjusting `--hls-segment-threads` or `--hls-live-restart`. Sometimes, the issue resolves itself or is temporary.
streamlink: error: unrecognized arguments: <some-argument>
This error occurs when Streamlink's CLI parser encounters an argument it doesn't recognize. This often happens after major version updates where CLI arguments are changed or deprecated, or when an outdated configuration file passes invalid options.
fixReview your Streamlink command-line arguments and any custom configuration files. Pay close attention to changes in how `--player` and `--player-args` work since version 6.0.0. Remove or update old config files. Run `streamlink --help` for current argument options.
Upgrade
Version history
8.4.0latest on PyPI · released May 6, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
urllib3requiredHTTP client library, required for network operations.