mpv Ytdl Hook Script Not Loading: How to Fix It

When mpv opens local media normally but fails on an online URL, the ytdl_hook integration may not be running, may be unable to find yt-dlp, or may be receiving an argument that mpv interprets as a local path. Configuration profiles, wrapper scripts, outdated external tools, network restrictions, and shell quoting can produce the same symptom. The safest approach is to reproduce the failure with a clean command, inspect mpv's log, test yt-dlp independently, and change only the component proven to be failing.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start outside your usual launcher, file manager, desktop shortcut, or custom script. Open PowerShell, Command Prompt, Terminal, or a Linux shell and pass a known supported URL directly to mpv. Use a URL you are authorized to access.

1.1 Run mpv without your normal configuration

On Linux or macOS, run:

mpv --no-config --log-file=mpv-ytdl-test.log "https://example.com/video-page"

On Windows PowerShell or Command Prompt, the same basic form applies:

mpv.exe --no-config --log-file=mpv-ytdl-test.log "https://example.com/video-page"

Replace the example address with a real page supported by your installed yt-dlp. Keep the quotation marks, particularly when the URL contains &, ?, or other shell-sensitive characters.

A successful test normally causes yt-dlp to resolve the page into one or more playable media URLs. mpv may print format information, identify audio and video tracks, buffer data, and begin playback. If this clean command works, stop investigating installation or network causes. The failure is probably in your regular mpv.conf, a profile, an alias, a shortcut, or a wrapper command.

If mpv reports that the location cannot be opened, treats the text as a filename, or never prints any ytdl-related activity, continue with the checks below.

1.2 Verify that ordinary direct streams still work

There is an important distinction between a webpage URL and a direct media URL. mpv can often open a direct HTTP media file or stream through its normal demuxing path. A webpage usually requires ytdl_hook and yt-dlp to discover the underlying media.

If an ordinary direct stream works but a supported webpage does not, the output driver, hardware decoder, HDR settings, audio backend, and subtitle settings are unlikely to be the first cause. Concentrate on ytdl_hook, executable discovery, URL handling, and network access instead.

2. Check ytdl_hook and the Options That Control It

mpv includes the ytdl_hook integration as a built-in script in normal official builds. The hook does not itself download or extract website information. It calls an external program, normally yt-dlp or the older youtube-dl, and then gives the resulting media addresses to mpv.

2.1 Make sure ytdl support is not disabled

Search your mpv configuration, profiles, launch arguments, aliases, and shortcuts for settings that disable ytdl handling. The most relevant setting is:

ytdl=no

Remove it or temporarily override it at the command line:

mpv --no-config --ytdl=yes "https://example.com/video-page"

Also inspect custom script-loading settings. The load-scripts option controls automatic loading from user script directories, while ytdl directly controls the built-in ytdl hook. Do not assume that every script-related option has the same effect. The log is the best way to establish whether ytdl_hook itself initialized.

Success means the log shows ytdl_hook activity and mpv proceeds to ask an external downloader to process the URL. Once that happens, stop changing unrelated mpv playback settings.

2.2 Check profiles and command-line overrides

An option in mpv.conf can be overridden by a profile, and a command-line option can override both. Review profiles that match protocols, extensions, or your launcher. Also inspect commands bound in input.conf if the problem occurs only when opening a URL through a custom key binding.

Use the following command to inspect a named profile:

mpv --show-profile=profile-name

Replace profile-name with the relevant profile. Look for ytdl=no, unexpected script options, or URL-related options. If playback succeeds with --no-config but fails normally, re-enable your configuration in small sections until the responsible setting is identified.

2.3 Avoid changing unrelated playback options first

Subtitle selection, audio track selection, video track selection, hardware decoding, HDR tone mapping, GPU output, and screenshot settings generally act after a page has been resolved into media streams. They can cause missing tracks, a black screen, playback errors, or screenshot failures, but they do not normally explain the complete absence of ytdl_hook activity.

Only investigate those settings if the log confirms that yt-dlp resolved the page and mpv opened the returned streams. At that stage, try --hwdec=no, default track selection, or a basic output configuration as a separate playback test.

3. Verify yt-dlp or youtube-dl Executable Discovery

The most common mpv ytdl hook script not loading fix is ensuring that a working yt-dlp executable is installed and discoverable. A loaded hook cannot resolve supported webpages if its external extractor is missing.

3.1 Test yt-dlp directly

Open the same terminal used to launch mpv and run:

yt-dlp --version

On some Windows installations, use:

yt-dlp.exe --version

Then test URL extraction without downloading the media:

yt-dlp --simulate --verbose "https://example.com/video-page"

If the shell says the command does not exist or is not recognized, mpv probably cannot find it through the same environment. Install yt-dlp through its official distribution instructions or a trusted operating-system package manager. Do not download renamed executables from random codec, mirror, or file-sharing sites.

If yt-dlp starts but reports that the site is unsupported, authentication is required, or network access failed, ytdl_hook is not the primary fault. Resolve the extractor, account, URL, or network issue before changing mpv.

3.2 Confirm PATH from mpv's launch environment

PATH can differ between an interactive terminal and a graphical application. This is common when mpv is opened from a desktop shortcut, Finder, a Windows launcher, or a sandboxed package. A command may work in your shell while a GUI-launched mpv process cannot discover it.

Compare these cases:

• Launch mpv from the terminal where yt-dlp --version succeeds.
• Launch the same URL from your normal shortcut or application association.
• Check whether only the graphical launch fails.

If terminal playback works, correct the launcher's environment or configure the ytdl executable path explicitly. mpv supports a ytdl_hook script option for this purpose:

script-opts=ytdl_hook-ytdl_path=/absolute/path/to/yt-dlp

On Windows, use the full path to yt-dlp.exe. Paths containing spaces must be represented carefully according to mpv's configuration parsing rules. Test the setting on the command line before making it permanent, and consult the mpv manual for escaping rules relevant to your platform.

Success means the log identifies the selected executable, extraction completes, and mpv begins opening the returned stream URLs.

4. Check URL Handling, Shell Quoting, and Network Access

4.1 Ensure mpv receives a URL rather than a local path

Copy the complete URL, including https://. Without a scheme, mpv may interpret input as a local filename. A malformed launcher command can also prepend a working directory or remove part of the address.

Always quote URLs in terminal tests. On many shells, an ampersand starts another command, a question mark may participate in pattern matching, and other characters can be altered before mpv sees them. If the log displays only part of the URL, fix shell quoting or the launcher placeholder.

If a custom input.conf binding prompts for or constructs a URL, bypass it by passing the address directly on the command line. If direct input works, repair the binding rather than modifying ytdl_hook.

4.2 Separate network failures from hook failures

yt-dlp may be blocked by a firewall, proxy, DNS filter, certificate problem, captive portal, or site restriction. Test the same URL with yt-dlp --simulate --verbose. Its output usually gives more precise extractor and network information than a generic mpv open failure.

Do not disable TLS verification as a routine fix. Correct the system clock, trusted certificate store, proxy configuration, firewall rule, or network environment instead. Corporate and school networks may require an approved proxy or may intentionally block streaming domains.

4.3 Consider authentication and site limitations

Some pages require authentication, age confirmation, geographic availability, or browser-derived session information. A site can also change its page format, temporarily breaking an older extractor. Update yt-dlp using its official installation method, then repeat the direct simulation test.

Do not attempt to bypass DRM. ytdl_hook and yt-dlp are not general DRM removal tools. If the media is protected or unavailable to your account or region, changing mpv's video output, decoder, or scripts will not make it playable.

5. Use mpv Logs to Find the Exact Failure Stage

Verbose output distinguishes a hook that never runs from one that runs but cannot invoke yt-dlp. It also shows whether extraction succeeds and playback fails later.

5.1 Create a focused diagnostic log

Run:

mpv --no-config --msg-level=all=v --log-file=mpv-ytdl.log "https://example.com/video-page"

Open mpv-ytdl.log in a text editor and search for terms such as ytdl, hook, yt-dlp, youtube-dl, failed, error, and not found.

• No ytdl_hook messages may indicate disabled ytdl support, an unusual build, or input not handled as an online URL.
• Executable-not-found output points to PATH or an incorrect configured path.
• Extractor errors point to yt-dlp, the website, authentication, or network access.
• Successful extraction followed by demuxer, decoder, audio, or GPU errors means the hook worked and the remaining problem is playback.

Logs can contain URLs, local paths, account identifiers, query tokens, and other private information. Redact them before posting a log publicly.

5.2 Use other diagnostic tools only when relevant

The stats overlay and track list become useful after a stream opens. Press the default stats key if available in your configuration, or inspect mpv's terminal output to confirm selected video, audio, and subtitle tracks. If extraction succeeds but no expected track appears, compare yt-dlp's available formats with mpv's selected formats.

--show-profile is useful for configuration diagnosis. The stats overlay is useful for active playback. Neither replaces log output when the hook does not run at all.

6. Run a Clean Temporary Test Before Editing Files

A controlled sequence prevents several simultaneous changes from hiding the real fix. Perform these tests in order:

1. Confirm yt-dlp --version works in the current terminal.
2. Run yt-dlp --simulate --verbose against the target URL.
3. Run mpv with --no-config, a quoted URL, and a log file.
4. If necessary, pass an explicit ytdl executable path.
5. Only after clean playback succeeds, test your normal configuration.
6. Re-enable profiles, custom scripts, and launcher commands one group at a time.

Keep the first successful command unchanged and use it as your baseline. When one added option makes the failure return, stop. That option or the associated environment is the useful lead.

If both yt-dlp and clean mpv tests succeed, there is no reason to reinstall mpv, replace codecs, delete the entire configuration directory, or change GPU drivers. Compare your normal launch command and configuration against the successful baseline.

7. Quick Fix Checklist

• Include the full https:// URL and quote it correctly.
• Confirm ytdl=no is not active in a config, profile, alias, or shortcut.
• Test with mpv --no-config.
• Run yt-dlp --version from the same terminal.
• Test the URL with yt-dlp --simulate --verbose.
• Verify that GUI-launched mpv has access to the same PATH.
• Set an explicit trusted yt-dlp path if PATH discovery is unreliable.
• Write an mpv log and search for ytdl_hook and executable errors.
• Update yt-dlp from its official source or trusted package manager when extraction fails.
• Investigate hwdec, HDR, subtitles, tracks, audio, or GPU output only after extraction succeeds.

8. Frequently Asked Questions

8.1 Is ytdl_hook included with mpv?

Normal mpv distributions include ytdl_hook as a built-in integration, but it relies on an external extractor such as yt-dlp. Packaging can vary, so the definitive check is mpv's verbose log. If a third-party or minimal build lacks expected scripting functionality, obtain mpv through the official project guidance or a trusted operating-system package source.

8.2 Does disabling user scripts disable ytdl_hook?

Not necessarily. User script autoloading and the built-in ytdl integration are controlled by different options. Check ytdl directly and use verbose logging instead of assuming that load-scripts explains the failure.

8.3 Why does yt-dlp work in Terminal but not through my mpv shortcut?

The shortcut may launch mpv with a different PATH. Launch mpv from the working terminal to confirm the difference, then correct the shortcut environment or configure an absolute yt-dlp path.

8.4 Why does mpv say the online URL is a missing file?

The argument may lack https://, may have been truncated by shell characters, or may have been transformed by a launcher or input binding. Quote the complete address and test it directly from a terminal.

8.5 Can hardware decoding or HDR settings stop ytdl_hook from loading?

They normally affect playback after extraction, not hook invocation. If the log shows successful extraction followed by video output or decoder errors, test --hwdec=no and a clean output configuration. If there are no hook messages, focus elsewhere.

8.6 When should I stop changing settings?

Stop changing ytdl settings when the log shows successful extraction and mpv opens the returned media streams. Any remaining black screen, silent audio, missing subtitle, track-selection, HDR, screenshot, or GPU problem belongs to a later playback stage and should be diagnosed separately.