mpv HTTPS Proxy Not Working: How to Fix It

When an mpv HTTPS proxy is not working, the failure usually occurs in one of three places: mpv opens the stream directly without the expected proxy, yt-dlp performs extraction outside the proxy, or the proxy connection fails because of authentication, certificate interception, environment isolation, or an incompatible proxy URL. The fastest way to solve the problem is to identify which component is making the network request, test it with a simple URL, and change only the setting responsible for that request.

This guide focuses specifically on proxy behavior in mpv on Windows, Linux, and macOS. It also explains how configuration files, profiles, scripts, frontends, environment variables, and yt-dlp can cause a command that appears correct to behave differently than expected.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, changing hardware decoding, or reinstalling anything, run mpv from a terminal with a temporary clean configuration. This separates proxy problems from scripts, profiles, input bindings, shaders, subtitle settings, and frontend behavior.

1.1 Test a simple direct HTTPS URL

Choose a small, legal, publicly accessible HTTPS media URL that mpv can open directly. Avoid beginning with a complex website page, authenticated service, playlist, or URL requiring yt-dlp. Run the following command, replacing the example values with your test URL and proxy:

mpv --no-config --http-proxy=http://127.0.0.1:8080 "https://example.com/test.mp4"

On Windows, run the command in Command Prompt or PowerShell from the directory containing mpv.exe, or use the full executable path. On Linux and macOS, run it from a terminal where the mpv command is available.

A proxy used for HTTPS destinations is often specified with an http:// proxy URL because the client reaches an HTTP proxy and requests an HTTPS tunnel using CONNECT. Do not automatically change the proxy address to https:// merely because the destination is HTTPS. The scheme must describe the proxy endpoint and protocol your proxy server actually supports.

Success means the media begins loading and the proxy server records a connection from mpv. If both happen, stop changing global network settings. Your basic mpv proxy path works, and the original failure is probably tied to yt-dlp, a specific URL, a profile, a script, or the way mpv was launched.

1.2 Compare proxied and unproxied behavior

Run the same clean test without the proxy option:

mpv --no-config "https://example.com/test.mp4"

If both commands work, playback alone does not prove that the proxy was used. Check your proxy access log, use a controlled endpoint that reports the requesting IP address, or temporarily test through a proxy whose traffic you can observe. Do not rely only on whether the video plays.

If the proxied test fails but the direct test succeeds, concentrate on proxy syntax, authentication, certificate handling, and network access. If both fail, verify the test URL independently before diagnosing the proxy.

2. Check Which Component Is Responsible for the Request

mpv can receive network content through different paths. A direct media URL may be opened by mpv's stream layer and FFmpeg libraries. A webpage URL may first be passed to yt-dlp, which extracts one or more media URLs. Those extracted URLs are then opened for playback. Proxy configuration may therefore need to reach both yt-dlp and the subsequent media connection.

2.1 Set the mpv HTTP proxy correctly

For a command-line test, use mpv's HTTP proxy option:

mpv --http-proxy=http://proxy.example:3128 "https://example.com/video.mp4"

In mpv.conf, omit the leading double hyphens:

http-proxy=http://proxy.example:3128

A common mpv player issue is copying command-line syntax directly into the configuration file. Another is placing the option in a profile that is never activated. Test the option on the command line first. If it works there but not from the normal configuration, the problem is configuration loading or profile selection rather than the proxy itself.

If the proxy requires credentials, avoid exposing them in screenshots, shared logs, shell history, or public configuration repositories. Prefer a locally protected configuration or the proxy's supported authentication mechanism. Characters such as @, :, #, and % may need URL encoding when included in credentials.

2.2 Pass a proxy to yt-dlp when extraction is involved

If the input is a website page rather than a direct media file, test yt-dlp independently:

yt-dlp --proxy "http://127.0.0.1:8080" --verbose "https://example.com/watch-page"

Use a URL that yt-dlp legitimately supports and that you are authorized to access. Success means yt-dlp completes extraction through the proxy and prints the selected format or media information without a connection error.

You can pass the yt-dlp proxy option through mpv using raw yt-dlp options:

mpv --ytdl-raw-options=proxy=http://127.0.0.1:8080 "https://example.com/watch-page"

In mpv.conf, the corresponding entry is:

ytdl-raw-options=proxy=http://127.0.0.1:8080

Depending on the URL and extraction result, it can be appropriate to configure both http-proxy for mpv's stream connection and the yt-dlp proxy option for extraction. If yt-dlp succeeds but mpv fails after extraction, the proxy problem is likely in the media playback request rather than the extraction request.

2.3 Verify the yt-dlp executable mpv is using

A terminal may find one yt-dlp installation while mpv, a GUI frontend, or a desktop launcher finds another. Check the executable visible in your shell:

yt-dlp --version

On Windows, also use:

where yt-dlp

On Linux or macOS, use:

command -v yt-dlp

Then inspect mpv's terminal output to confirm that the ytdl hook starts and does not report a missing executable. If necessary, configure the ytdl hook to use a known executable path according to the mpv manual for your installed build. Paths containing spaces must be quoted correctly on the command line.

Success means the same yt-dlp executable works both independently and when launched by mpv. Once confirmed, do not reinstall unrelated codecs, GPU drivers, or audio components.

2.4 Avoid unrelated playback settings during diagnosis

Subtitle selection, audio and video track choices, HDR tone mapping, screenshot templates, output drivers, shaders, and hardware decoding do not normally determine whether an HTTPS request uses a proxy. They can, however, produce errors after the stream has already connected.

During the proxy test, avoid custom options such as --hwdec, GPU profiles, shader chains, external subtitle downloads, and automatic scripts. If the log shows that network data was received and decoding began, the proxy stage succeeded. Treat subsequent decoder, display, audio, subtitle, or screenshot errors as separate problems.

3. Check Environment Variables and Launch Context

Some networking tools and libraries inspect proxy environment variables. Common names include HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and lowercase equivalents. Support and precedence can vary among mpv, FFmpeg libraries, yt-dlp, operating systems, and builds, so an explicit command-line proxy is the best controlled test.

3.1 Inspect environment proxy variables

In Windows Command Prompt, inspect relevant variables with:

set HTTP_PROXY
set HTTPS_PROXY
set ALL_PROXY

In PowerShell, inspect them with:

$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:ALL_PROXY

In Linux or macOS shells, use:

env | grep -i proxy

Look for stale proxy addresses, conflicting uppercase and lowercase variables, incorrect credentials, or a NO_PROXY rule that excludes the target host. Do not assume that setting an operating system's graphical proxy automatically configures every command-line program.

For a temporary PowerShell test, set a variable only in the current process:

$env:HTTPS_PROXY="http://127.0.0.1:8080"
mpv --no-config "https://example.com/test.mp4"

For a temporary POSIX shell test:

HTTPS_PROXY="http://127.0.0.1:8080" mpv --no-config "https://example.com/test.mp4"

If an explicit --http-proxy works while an environment-only test does not, keep the explicit mpv setting or investigate whether the relevant library honors that variable. Do not keep changing unrelated media options.

3.2 Account for frontend environment isolation

A GUI frontend, file manager, desktop shortcut, macOS app bundle, system service, Flatpak, Snap, or sandboxed package may not inherit the same environment as your interactive terminal. This explains why a terminal command works while the normal launcher does not.

Launch mpv directly from the same terminal where the proxy variables are defined. If that works, configure the frontend's mpv arguments, environment, or sandbox permissions rather than editing the media settings. Also confirm that the frontend has not overridden --http-proxy, --ytdl, script options, or the path to yt-dlp.

Success means the frontend produces the same proxy connection as the direct terminal command. At that point, preserve the working launch configuration and stop modifying mpv's decoder or renderer.

3.3 Check firewall and network permissions

The client must be able to connect to the proxy host and port. A local firewall, security product, container boundary, corporate network rule, VPN policy, or sandbox may block mpv or yt-dlp even when a web browser is allowed.

Verify that the proxy hostname resolves and that the port is reachable using operating-system tools approved for your network. If the proxy is bound only to 127.0.0.1, applications inside a container, virtual machine, or sandbox may not share the host's loopback interface.

If the log reports connection refused, timeout, or name resolution failure before any TLS exchange, fix reachability first. Certificate changes will not solve an unreachable proxy.

4. Diagnose Certificate Interception Carefully

Corporate and security proxies sometimes intercept TLS connections and issue replacement certificates signed by a private certificate authority. A browser may trust that authority while mpv, FFmpeg, Python, or yt-dlp uses a different trust store and rejects it.

4.1 Recognize certificate-related failures

Look for messages mentioning certificate verification, an unknown issuer, an untrusted authority, a hostname mismatch, or a failed TLS handshake. These messages indicate that the connection reached a TLS stage, which is different from a timeout or refused connection.

The safe fix is to install the organization's legitimate certificate authority using its documented process and ensure the affected tool can access the appropriate trust store. Ask the network administrator for the correct certificate and instructions. Do not download a certificate from an unrelated website.

Avoid permanently disabling certificate verification. Doing so can conceal interception or impersonation and removes an important security check. A temporary diagnostic test, if supported by a tool, should not become the normal configuration.

4.2 Separate proxy TLS from destination TLS

An HTTPS destination reached through an HTTP proxy typically involves a CONNECT tunnel followed by TLS to the destination. An HTTPS proxy can additionally require TLS between the client and the proxy itself. These are separate trust relationships.

Confirm whether your provider gave you an HTTP proxy, an HTTPS proxy, or a SOCKS proxy. mpv's HTTP proxy option is not a universal replacement for every proxy protocol. If you were given a SOCKS endpoint, use a supported method documented by the relevant tool rather than relabeling it as HTTP.

5. Use mpv Logs to Locate the Failure

Terminal output is more useful than changing multiple settings blindly. Run a clean command with increased logging and save the results to a file:

mpv --no-config --msg-level=all=v --log-file=mpv-proxy.log --http-proxy=http://127.0.0.1:8080 "https://example.com/test.mp4"

Logs may contain complete URLs, query tokens, headers, local paths, usernames, or other sensitive information. Review and redact them before sharing.

5.1 Interpret the order of messages

• If mpv cannot parse the option, correct the option name or syntax before testing the network.
• If the proxy host cannot be resolved, check the hostname and DNS environment.
• If the connection is refused, verify that the proxy is running and listening on the stated port.
• If the request times out, investigate routing, firewall rules, VPN behavior, or proxy availability.
• If yt-dlp reports an extraction error, run yt-dlp independently with its proxy and verbose output.
• If extraction succeeds but opening the returned media URL fails, inspect mpv's stream proxy setting.
• If decoding or display errors appear after data starts arriving, troubleshoot playback separately.

The stats overlay and track list can confirm that playback reached the media stage, but they do not prove which proxy handled the request. The stats overlay is useful for checking whether data is buffering and frames are decoding. The track list helps distinguish a missing selected track from a network failure.

5.2 Inspect profiles without assuming they are active

If you use profiles, inspect the profile definition with mpv's --show-profile option:

mpv --show-profile=profile-name

Check whether the profile contains a proxy setting or another network option. Also verify how the profile is activated. A correct proxy line inside an inactive profile has no effect.

Input bindings can change profiles or run commands during playback, while scripts can modify properties or replace URLs. Temporarily using --no-config prevents most custom configuration from affecting the baseline test. If the clean command works, add your normal configuration back in controlled stages.

6. Run a Clean Temporary Test Before Permanent Changes

Use a short test matrix instead of changing many options at once. Record whether each test connects through the proxy.

1. Open a simple direct HTTPS media URL with --no-config and no proxy.
2. Open the same URL with --no-config and an explicit --http-proxy.
3. Run yt-dlp independently against a supported page with --proxy and verbose output.
4. Run mpv against that page with the yt-dlp proxy passed through --ytdl-raw-options.
5. If needed, add mpv's --http-proxy so both extraction and media playback have explicit proxy settings.
6. Repeat the working command without --no-config.
7. Finally, repeat it through the usual frontend or desktop launcher.

The first step that fails identifies the layer requiring attention. For example, if direct media works through the proxy but a webpage does not, focus on yt-dlp. If the terminal works but the frontend fails, focus on launch arguments, environment inheritance, executable paths, and sandbox access.

Once a test succeeds and proxy logs confirm the expected route, stop changing settings. Make the smallest permanent change needed, then keep a copy of the known-good command for future mpv troubleshooting.

7. Quick Fix Checklist

• Test with mpv --no-config and a simple direct HTTPS media URL.
• Use --http-proxy=http://host:port when the proxy endpoint is an HTTP proxy.
• Confirm proxy usage through server logs or another controlled observation method.
• Test yt-dlp independently with its --proxy option.
• Pass the proxy to yt-dlp through --ytdl-raw-options when extraction is involved.
• Verify which yt-dlp executable mpv and the frontend can find.
• Inspect HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.
• Check whether a GUI launcher inherits the terminal's environment.
• Use --msg-level=all=v and --log-file to identify the failing layer.
• Check certificate trust if a managed proxy intercepts TLS.
• Do not troubleshoot HDR, hwdec, shaders, audio, or screenshots unless the log reaches playback.
• Apply one permanent change only after the clean command succeeds.

8. Frequently Asked Questions

8.1 Why does mpv work directly but fail through the proxy?

The proxy address may be incorrect, unavailable, blocked, or using a different protocol than expected. Authentication or TLS interception can also fail. Start with an explicit --http-proxy test and inspect the log for resolution, timeout, connection, authentication, or certificate errors.

8.2 Why does a direct video URL work but a website URL fail?

The website URL probably requires yt-dlp extraction. mpv's stream proxy does not necessarily guarantee that the separate yt-dlp process receives the same proxy configuration. Test yt-dlp with --proxy, then pass that option through mpv's yt-dlp raw options.

8.3 Should an HTTPS destination use an https proxy URL?

Not necessarily. Many HTTPS destinations are reached through an HTTP proxy using CONNECT, so the proxy endpoint is still written as http://host:port. Use the scheme specified by the proxy provider. The destination's scheme does not automatically determine the proxy endpoint's scheme.

8.4 Why does the command work in a terminal but not in my mpv frontend?

The frontend may not inherit proxy environment variables, may use a different configuration directory, may point to another mpv or yt-dlp executable, or may run in a sandbox. Reproduce the exact terminal arguments in the frontend and verify its environment and executable paths.

8.5 Can hardware decoding or HDR settings stop mpv from using a proxy?

They do not normally control proxy routing. They can cause playback to fail after the media connection succeeds. If logs show downloaded data, detected tracks, and decoder initialization, treat the hwdec, GPU, display server, or HDR issue separately.

8.6 How do I know the mpv HTTPS proxy not working fix is complete?

The test media loads, the log contains no proxy or TLS failure, and a trusted observation such as the proxy's access log confirms that the request followed the intended route. The same result should then occur from your normal configuration or frontend. Once those conditions are met, stop changing options and preserve the working setup.