mpv YouTube URL Not Playing: How to Fix It

When an mpv YouTube URL is not playing, the failure usually happens before normal video decoding begins. mpv relies on its built-in ytdl_hook script and an external extractor, normally yt-dlp, to turn a YouTube page URL into playable media streams. A missing or outdated yt-dlp executable, incorrect URL quoting, network or certificate trouble, a broken site extractor, or an interfering mpv configuration can stop that process. Less commonly, mpv successfully resolves the URL but then encounters a video output, audio output, hardware-decoding, HDR, track-selection, or script problem. The safest approach is to test the smallest possible command, read the relevant log output, and change one variable at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin outside your usual launcher, file manager, playlist, browser extension, or custom key binding. Open Command Prompt, PowerShell, Terminal, or a Linux shell and run mpv directly with a normal public YouTube video URL.

mpv --no-config "https://www.youtube.com/watch?v=VIDEO_ID"

Replace VIDEO_ID with the identifier from a publicly accessible video. Keep the quotation marks. The --no-config option temporarily bypasses your user configuration, profiles, scripts, shaders, and most custom behavior without deleting anything.

A successful test opens the video, starts playback, and shows normal audio or video track information in the terminal. If that happens, stop changing yt-dlp, network, or operating system settings. The YouTube extraction path works, and the problem is probably inside your normal mpv configuration or the application that launches mpv.

If the clean command fails, note what happens:

• mpv immediately says the URL cannot be opened.
• The log mentions that yt-dlp or youtube-dl was not found.
• ytdl_hook reports an extractor, certificate, HTTP, or network error.
• A stream is resolved, but the window is blank or playback has no audio.
• The command works with some YouTube videos but not one particular video.

These outcomes point to different causes. Do not start by changing hardware decoding, subtitle preferences, or HDR settings if the log says the external extractor could not be found. Likewise, do not reinstall yt-dlp repeatedly if mpv has already resolved separate audio and video streams and the failure occurs during output initialization.

1.1 Test a Plain Watch URL

Use a standard https://www.youtube.com/watch?v=... address for the first test. Temporarily avoid playlist parameters, timestamps, tracking parameters, Shorts redirects, and URLs copied through another service. A simplified URL removes ambiguity caused by shell characters and playlist handling.

If the plain watch URL works, add the required parameters back one at a time. You can stop when you identify the parameter or launch method that triggers the failure.

1.2 Distinguish Extraction From Playback

Extraction happens when yt-dlp examines the page and returns direct stream information. Playback begins when mpv opens those streams, selects tracks, initializes decoders, and creates audio and video outputs. Terminal lines mentioning formats, audio tracks, video tracks, or separate stream URLs usually indicate that extraction succeeded. Errors that appear after those lines are more likely to involve media playback than YouTube URL recognition.

2. Verify yt-dlp Discovery and YouTube Extraction

For current YouTube support, yt-dlp is the external tool normally used by mpv's ytdl_hook. mpv must be able to locate and execute it. Having yt-dlp somewhere on the computer is not enough if that location is absent from the environment used to launch mpv.

2.1 Check Whether the Executable Is Discoverable

On Windows Command Prompt, run:

where yt-dlp

On PowerShell, run:

Get-Command yt-dlp

On Linux or macOS, run:

command -v yt-dlp

A successful result prints the executable path. If no path appears, install yt-dlp using its official instructions or a trusted operating-system package source, then place it on PATH. Avoid random download sites and unofficial codec bundles.

After changing PATH, close and reopen the terminal. Desktop applications may also require a sign-out, restart, or relaunch before they inherit the new environment. Repeat the discovery command and then rerun the minimal mpv test. Success means the shell finds yt-dlp and mpv no longer reports that the executable is missing.

Graphical launchers can inherit a different PATH from interactive shells, especially on macOS and Linux. If mpv works from a terminal but fails when started from a desktop shortcut, browser extension, or file manager, compare the launch environments. The problem is then the launcher's environment or command construction, not YouTube playback itself.

2.2 Check yt-dlp Directly

Run yt-dlp independently before changing mpv options:

yt-dlp --version

Then ask it to inspect the target video without downloading media:

yt-dlp --simulate --verbose "https://www.youtube.com/watch?v=VIDEO_ID"

You can also list the available formats:

yt-dlp -F "https://www.youtube.com/watch?v=VIDEO_ID"

If yt-dlp prints video metadata or a format table, its extractor and basic network access are working. Return to mpv troubleshooting. If yt-dlp itself reports an extractor error, unsupported URL, certificate problem, login requirement, or HTTP failure, mpv cannot repair that upstream failure.

Update yt-dlp through the same trusted installation method you originally used. A standalone official binary may support its own update command, while package-manager installations should normally be updated through that package manager. Do not replace a managed package with an unrelated binary unless you understand which executable your shell and mpv will select.

2.3 Recognize Site Extractor Failures

YouTube changes can temporarily break extraction in outdated tools. Typical signs include messages about failing to extract player data, unavailable formats, signature processing, or an unsupported page. Confirm the behavior with yt-dlp directly and test a second public video.

• If every ordinary public video fails in yt-dlp, update yt-dlp and retest.
• If one video fails while others work, inspect that video's availability or restrictions.
• If yt-dlp works but mpv fails, investigate mpv's ytdl_hook invocation and configuration.
• If both tools fail only on one network, investigate filtering, proxy, DNS, or TLS interception.

Success means yt-dlp can inspect the page and mpv can obtain playable streams. Once both conditions are true, stop changing extractor settings.

3. Check URL Quoting, Network Access, and Certificates

3.1 Quote the Complete URL

YouTube URLs often contain an ampersand, especially when they include playlist, index, or timestamp parameters. Shells can interpret this character as command syntax. Always quote the entire URL.

mpv "https://www.youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID"

In a configuration, script, input binding, or launcher, make sure the URL reaches mpv as one argument. A browser extension that constructs mpv URL without safe argument handling can truncate the address or invoke unintended shell behavior. If a quoted terminal command works but the integration fails, repair the integration rather than changing mpv playback options.

3.2 Test Basic Network Reachability

Open the same video in a browser on the same computer and network. Browser success does not prove yt-dlp access because the browser may use a different proxy, DNS mode, certificate store, authentication state, or IPv4 and IPv6 route. It does confirm that the page is generally reachable.

Review the verbose yt-dlp output for DNS lookup failures, connection timeouts, proxy errors, HTTP status codes, or TLS certificate messages. Corporate networks, school networks, security software, transparent proxies, and filtered DNS services can affect command-line tools differently from browsers.

If you intentionally use a proxy, verify that it is configured correctly for both yt-dlp and mpv. Also check whether proxy-related environment variables are stale. Do not disable certificate validation as a routine fix. A certificate error can indicate an incorrect system clock, an outdated trust store, TLS inspection, or an improperly configured proxy.

3.3 Check Time and Certificate Stores

Confirm that the operating system's date, time, and time zone are accurate. TLS certificates are validated against the system clock. Install normal operating-system security and certificate-store updates from the platform vendor. On managed networks, ask the administrator whether HTTPS inspection requires an approved organization certificate.

Success means yt-dlp reaches YouTube without certificate, proxy, DNS, or timeout errors. Once that happens, return to the mpv command and avoid weakening TLS security.

4. Inspect mpv Options, Profiles, Scripts, and Track Selection

If --no-config works but your normal command fails, the problem is local configuration. Do not delete the entire config directory. Isolate settings gradually and preserve a backup of any file you edit.

4.1 Review the Relevant Configuration Files

Check mpv.conf, input.conf, enabled profiles, user scripts, and launcher arguments. Pay particular attention to options related to:

• ytdl, ytdl-format, or ytdl_hook script options
• Proxy, cookies, HTTP headers, or user-agent overrides
• Audio and video track selection
• vid=no, aid=no, or forced track identifiers
• vo, ao, gpu-api, and gpu-context
• hwdec, HDR, tone mapping, shaders, and high-bit-depth output
• Subtitle scripts or settings that invoke external programs
• Playlist, cache, stream-lavf, or demuxer overrides
• Scripts that replace URLs, control IPC, or intercept file loading

Temporarily comment out one suspicious option by placing # at the start of its line, then retest. If playback returns, restore and adjust only that option. This is safer than replacing the full configuration.

4.2 Examine Format Selection

An overly restrictive ytdl-format expression can reject every format available for a particular video. Test without your custom format selection:

mpv --no-config "https://www.youtube.com/watch?v=VIDEO_ID"

If you need to retain other configuration while bypassing one custom choice, temporarily comment out the ytdl-format line. Success means mpv selects playable audio and video tracks automatically. Stop there, then simplify the custom expression instead of changing decoders or network settings.

4.3 Check Input Bindings and Launch Scripts

An input.conf binding may pass clipboard text incorrectly, omit quotation handling, or call an outdated script. Test the URL by typing the direct terminal command. If direct playback works, inspect the binding or script that loads the URL.

IPC clients can also send a malformed loadfile command or alter replacement and append behavior. Capture the exact JSON command and verify that the complete URL is one valid string. This is particularly important for URLs containing ampersands, question marks, and Unicode characters.

5. Separate Video, Audio, Hardware Decoding, and HDR Problems

When the log shows that yt-dlp returned streams but playback remains black, silent, or unstable, test output components separately. These tests are relevant only after extraction succeeds.

5.1 Disable Hardware Decoding Temporarily

Run:

mpv --no-config --hwdec=no "https://www.youtube.com/watch?v=VIDEO_ID"

If software decoding works, the URL and extractor are healthy. The issue is associated with the selected hardware decoder, GPU driver, codec support, or video output context. Update the GPU driver from the hardware or operating-system vendor, then test mpv's safer automatic hardware-decoding mode before forcing a specific API.

High-resolution YouTube formats may use VP9 or AV1, which can expose hardware support limitations. A high-bitrate or high-resolution stream may also be too demanding for software decoding on older hardware. Test a lower format or smaller video only after confirming extraction.

5.2 Test Video and Audio Independently

To test audio without video output, use:

mpv --no-config --vid=no "https://www.youtube.com/watch?v=VIDEO_ID"

To test video without audio output, use:

mpv --no-config --aid=no "https://www.youtube.com/watch?v=VIDEO_ID"

If audio-only playback works but normal playback fails, focus on the video decoder, GPU context, display server, shaders, HDR options, or video output. If video-only works, investigate the audio backend, selected device, exclusive-mode settings, and forced audio-track options.

5.3 Remove HDR and Shader Overrides

YouTube extraction is not controlled by HDR or shader settings, but those settings can make successfully resolved video appear blank, incorrectly colored, or unable to initialize. Test without custom shaders, forced target color spaces, display peak overrides, or experimental GPU options.

On Linux, a difference between Wayland and X11 sessions can expose a GPU-context or driver issue. On Windows, forced GPU APIs or outdated drivers can cause output initialization failures. On macOS, test the standard supported output path before adding advanced rendering options. Success is stable audio and visible video with default output settings. Once achieved, restore enhancements individually.

6. Read Terminal Output and ytdl_hook Logs

mpv's terminal output is usually more useful than a generic error dialog. Run a verbose test and save the result:

mpv --no-config --msg-level=all=v --log-file=mpv-youtube.log "https://www.youtube.com/watch?v=VIDEO_ID"

Use a writable file path if the current directory is protected. Close mpv after the test, then open the log in a text editor and search for ytdl_hook, yt-dlp, error, failed, vo, and ao.

6.1 Interpret Common ytdl_hook Results

• A message that the executable was not found means discovery failed. Fix PATH or the launch environment.
• An extractor or unsupported-site error means yt-dlp could not interpret the page. Test and update yt-dlp.
• A certificate, DNS, proxy, or timeout message points to network access rather than mpv rendering.
• Format-selection failure often points to a restrictive ytdl format rule or video-specific availability.
• Successful stream URLs followed by decoder or output errors mean ytdl_hook completed its job.

Logs can contain URLs, file paths, headers, account-related information, or temporary media tokens. Redact sensitive values before sharing a log publicly.

6.2 Inspect Profiles and Runtime State

If a named profile may be involved, use mpv's --show-profile option with that profile name to inspect what it applies. Compare those settings with the successful clean command. Profiles can activate conditionally, so review automatic profile conditions as well as profiles you explicitly select.

During playback, mpv's stats overlay can show the selected codecs, dropped frames, hardware decoding state, and synchronization behavior. The track list can confirm whether both video and audio streams were loaded. These tools are useful after the URL resolves. They cannot diagnose a missing yt-dlp executable if no tracks were created.

7. Run a Clean Temporary Test Before Permanent Changes

Use a short test matrix rather than changing several permanent settings together:

1. Run the quoted URL with --no-config.
2. Run yt-dlp --simulate --verbose on the same URL.
3. Confirm executable discovery with where, Get-Command, or command -v.
4. Save an mpv verbose log and inspect ytdl_hook output.
5. If streams resolve, test --hwdec=no, --vid=no, and --aid=no separately.
6. Re-enable your configuration in small groups until the failure returns.

This sequence identifies the layer that fails: command construction, extractor discovery, YouTube extraction, network access, configuration, decoding, or output. It also provides a clear stopping rule. When a test succeeds, stop making unrelated changes and compare that successful command with the failing one.

For example, if mpv --no-config works, there is no reason to alter system certificates. If yt-dlp fails directly, there is no reason to tune mpv shaders. If both audio-only and video-only tests work but combined playback does not, inspect track synchronization, output initialization, and custom scripts rather than URL quoting.

8. Quick Fix Checklist

• Quote the complete YouTube URL, including every query parameter.
• Test a simple public watch URL without playlist or tracking parameters.
• Run mpv once with --no-config.
• Confirm that the shell can discover yt-dlp.
• Run yt-dlp --simulate --verbose on the same URL.
• Update yt-dlp through its official or trusted package source.
• Read verbose ytdl_hook output before changing playback options.
• Check proxy, DNS, certificate, firewall, and system-clock errors.
• Remove restrictive ytdl-format rules temporarily.
• Test without custom scripts, profiles, shaders, or IPC clients.
• Use --hwdec=no only after streams are successfully resolved.
• Test audio-only and video-only playback to isolate output failures.
• Restore settings one at a time and stop after finding the cause.

9. Frequently Asked Questions

9.1 Does mpv Download YouTube Videos to Play Them?

mpv normally asks yt-dlp to extract media information and then streams the selected audio and video. Temporary buffering and caching may occur, but opening a URL for playback is not the same as deliberately downloading a permanent media file. Available behavior depends on your mpv options and scripts.

9.2 Why Does yt-dlp Work in a Terminal but Not in mpv?

mpv may be launched with a different PATH, especially from a desktop shortcut, file manager, browser extension, or macOS graphical application. It may also use a different configuration, format rule, proxy setting, or executable selection. Launch mpv from the same terminal where yt-dlp is discoverable. If that works, repair the graphical launch environment.

9.3 Why Does One YouTube Video Fail While Others Play?

The individual video may be private, removed, age-restricted, region-restricted, live, members-only, or otherwise unavailable to the extractor in the current context. Its available formats may also conflict with a restrictive ytdl-format rule. Test the URL directly with yt-dlp and compare it with a known public video.

9.4 Should I Delete My Entire mpv Configuration?

No. First use --no-config, which provides a clean temporary test without destroying custom settings. If the clean test works, comment out likely options or move individual scripts temporarily. Preserve backups and restore components one at a time.

9.5 Can Hardware Decoding Cause a YouTube URL Failure?

Hardware decoding does not normally cause yt-dlp discovery or site extraction failures. It can cause black video, decoder errors, crashes, or output problems after mpv has obtained the streams. Look at the log order. If ytdl_hook succeeds and the later failure names a decoder, GPU API, or video output, test --hwdec=no.

9.6 How Do I Know the Problem Is Fixed?

The issue is fixed when the same quoted YouTube URL consistently resolves into tracks and plays with expected audio and video through your intended launch method. If a minimal command works but your browser extension or custom binding does not, troubleshooting is not finished until that integration passes the URL correctly. Once the intended workflow works, stop changing unrelated mpv, network, or GPU settings.