#6509·streamlink

Add support for host-specific proxies with wildcards (`--http-proxy "[HOST ]...PROXY"`)

Author: bastimeyerCreated Apr 27, 2025Updated Jul 23, 2025
Labelsfeature requestCLIAPI: http-session

Streamlink currently only allows setting one global proxy server (HTTP/HTTPS/SOCKS4/SOCKS5) for all of its HTTP/HTTPS connections via --http-proxy=PROXY (--https-proxy is the deprecated alias argument).

This isn't ideal, because bypassing geo-restrictions on web-API endpoints while using the local connection for downloading stream contents is impossible this way (when this is not restricted by the streaming provider). Some plugins therefore need to be forked and sideloaded, which is unnecessary.


The proxy server config is applied by adding the http and https keys to the HTTPSession.proxies dict

which makes requests always select the set proxy. requests however does support more fine-grained control over this by allowing users to specify a scheme and a hostname, with a matching scheme+hostname having a higher priority:

The problem with this though is that while the scheme can be set to all:// (which matches both http and https), hostnames must always match exactly for a proxy to be selected. This is implemented in requests.utils.select_proxy() here:

For an application like Streamlink this doesn't make sense, as the relevant backend hostnames of most of the large streaming providers are dynamic, due to load-balancing reasons. requests unfortunately doesn't support hostname wildcards, as shown in the linked implementation. So in order for Streamlink to add support for host-based proxy configurations, requests's proxy selection needs to be overridden with a function that implements a hostname wildcard selection.

I'm not sure how I feel about this, because urllib3+requests are clearly a dead end for many many years now, and adding more features to Streamlink that depend on low-level overrides of both libs is obviously bad if the eventual goal is to migrate to different networking libs. httpx (#4915) on the other hand does support hostname wildcards in its proxy selection, so it's actually not a bad thing to implement an override for requests now that works similar to httpx, because it could be removed easily when migrating:


On the Streamlink's CLI side of things, --http-proxy/--https-proxy should be turned into a list (action="append"), so that it can be repeated multiple times, and on the session's StreamlinkOptions side of things, the setter function for the http-proxy/https-proxy keys needs to allow passing a list[str] | str value in order to stay backwards compatible.

The value of each proxy config string should be in the form of [HOST ]...PROXY, so basically a space-separated list of multiple optional hostnames (with wildcard support) and the proxy address at the end. From that, the HTTPSession.proxies dict can be built with all the host->proxy mappings. The scheme for each host selection schould be set to all://.


streamlink --http-proxy "*.123.foo *.456.bar proxy1" --http-proxy "proxy2" URL stream

This would use proxy1 for all requests made to *.123.foo or *.456.bar, and proxy2 for everything else.