mpv yt-dlp Not Found: How to Fix It

When mpv reports that yt-dlp or youtube-dl is unavailable, the problem is usually not video decoding, subtitles, HDR, or the media URL itself. mpv relies on an external downloader to resolve many website URLs, and the error means mpv could not discover or execute that downloader. The most common causes are a missing installation, an incorrect PATH, a frontend that inherited a different environment, a bad ytdl_path setting, shell quoting errors, or an obsolete youtube-dl fallback. The steps below isolate these causes without deleting your configuration or changing unrelated playback settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a direct terminal test. This separates mpv itself from launchers, file managers, custom input bindings, profiles, and third-party scripts.

Open Command Prompt or PowerShell on Windows, Terminal on macOS, or a terminal emulator on Linux. Run mpv with a legitimate, publicly accessible URL that yt-dlp supports:

mpv --no-config "https://example-supported-site.invalid/video-url"

Replace the placeholder with the actual URL you are troubleshooting. Keep quotation marks around URLs because characters such as ampersands and question marks can be interpreted by the shell.

The --no-config option temporarily prevents user and system configuration files from affecting the test. It does not delete or modify those files. If mpv still says that yt-dlp, youtube-dl, or the external downloader cannot be found, downloader discovery is the leading issue.

1.1 Test the downloader independently

In the same terminal, run:

yt-dlp --version

A successful test prints a version identifier and returns to the prompt without a command-not-found error. At that point, yt-dlp is installed and available to that particular shell.

If the command is not recognized, install yt-dlp using an official installation method suitable for your operating system. Avoid random download sites, unofficial codec packs, and binaries repackaged by unknown parties. After installation, close and reopen the terminal so it receives the updated PATH, then run yt-dlp --version again.

Stop changing mpv settings if both the independent yt-dlp command and the clean mpv URL test work. The fault is then likely in a normal mpv configuration, profile, script, input binding, or graphical frontend rather than the installation.

1.2 Verify that the two commands use the same environment

Testing from the same terminal matters. A graphical mpv frontend launched from the desktop may not inherit the PATH used by an interactive shell. This is especially common after changing environment variables without signing out, or when shell startup files add directories that graphical applications never read.

Launch mpv from the terminal where yt-dlp --version succeeds:

mpv "https://actual-url-here"

If this works while the desktop shortcut or frontend fails, yt-dlp is installed correctly. The remaining problem is the frontend's environment or executable-path configuration.

2. Check the Downloader Path and Relevant mpv Configuration

mpv's built-in ytdl hook invokes an external program. Modern setups should prefer yt-dlp rather than relying on an old youtube-dl installation. You can either make yt-dlp discoverable through PATH or configure the hook with an explicit executable path.

2.1 Install yt-dlp in PATH

PATH is a list of directories that the operating system searches for executable commands. Adding yt-dlp's directory to PATH allows both mpv and terminal sessions to locate it without a full path.

Use the operating system's normal package manager or the official yt-dlp installation instructions. Then verify discovery:

• Windows Command Prompt: where yt-dlp
• PowerShell: Get-Command yt-dlp
• Linux or macOS: command -v yt-dlp

The result should identify the executable you intended to install. Follow it with yt-dlp --version. If multiple locations appear, an older copy may be taking precedence. Remove the obsolete PATH entry or explicitly point mpv to the current executable.

2.2 Set ytdl_path explicitly

mpv exposes downloader selection through the built-in ytdl hook's script options. For a one-time diagnostic test, specify the path on the command line:

mpv --no-config --script-opts=ytdl_hook-ytdl_path="/absolute/path/to/yt-dlp" "https://actual-url-here"

On Windows, an example may look like this:

mpv --no-config --script-opts=ytdl_hook-ytdl_path="C:\Tools\yt-dlp.exe" "https://actual-url-here"

For persistent configuration, add the following to script-opts.conf in mpv's configuration directory:

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

Alternatively, the script option can be placed in mpv.conf using the complete option name:

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

Be careful if script-opts already exists in mpv.conf. Replacing the entire line can discard options for other scripts. Using script-opts.conf is often clearer.

Success means mpv starts resolving the URL instead of reporting that the downloader is unavailable. Once that happens, stop changing discovery settings. Any later HTTP, login, format, or unsupported-site error is a different troubleshooting stage.

2.3 Use Windows folder placement carefully

A common portable Windows arrangement places yt-dlp.exe beside mpv.exe. This often makes the two tools easy to manage, but behavior can differ depending on the mpv build, launcher, and working directory. Do not assume that the current folder shown by a shortcut is the mpv program folder.

For the most predictable result, use one of these approaches:

1. Put yt-dlp.exe in a dedicated tools directory included in the system or user PATH.
2. Configure an absolute ytdl_hook-ytdl_path pointing to yt-dlp.exe.
3. For a portable test, open a terminal in the mpv directory and launch mpv.exe directly.

If placing the executable beside mpv fixes the issue, verify that you are using a trusted yt-dlp release and that your frontend launches the same mpv.exe. Multiple mpv installations can otherwise make the apparent fix inconsistent.

2.4 Inspect profiles, scripts, and input bindings

A profile may replace script options, disable the ytdl hook, or select a different downloader. Use mpv's profile display option to inspect a named profile:

mpv --show-profile=profile-name

Review mpv.conf, included configuration files, and profile sections for settings involving ytdl, script-opts, or script loading. Also inspect input.conf if the error occurs only after pressing a custom key. The binding may launch a script or command with an outdated downloader name.

Third-party scripts can maintain their own yt-dlp path. Search their documentation and configuration files rather than assuming mpv's built-in setting controls every script. Temporarily move only the suspected script out of the scripts directory for testing. Do not delete the entire configuration folder.

3. Check Operating System, Frontend, Path, and Network Conditions

If the downloader exists but mpv cannot execute it, check the operating system boundary between the two programs.

3.1 Refresh environment variables used by graphical frontends

Applications inherit environment variables when they start. A frontend left running during a PATH change may continue using the old value. Completely exit the frontend, including tray processes, and open it again. If that fails, sign out and back in. A restart is rarely the first necessary step, but it can refresh a stubborn desktop session.

On macOS and Linux, PATH additions made only in interactive shell files may not reach applications launched from a desktop menu or Finder. Configure the frontend with an explicit yt-dlp path when it provides that option, launch it from a working terminal, or use mpv's explicit hook path.

3.2 Check permissions and executable status

On Linux and macOS, a manually downloaded file must have execute permission. Inspect it with ls -l. If the trusted file lacks execute permission, apply it to that file:

chmod u+x /absolute/path/to/yt-dlp

Then run the file directly with /absolute/path/to/yt-dlp --version. On managed systems, security software or operating system policies may block unfamiliar executables. Review the actual security notification or event log rather than broadly disabling protection.

On Windows, confirm that the file is really named yt-dlp.exe and not yt-dlp.exe.exe or an incomplete browser download. Use file properties or where yt-dlp to confirm the executable being selected.

3.3 Correct shell quoting and path syntax

Paths containing spaces must be quoted correctly. URLs should also be quoted. When configuration parsing and shell parsing are both involved, test with a simple path such as C:\Tools\yt-dlp.exe to eliminate ambiguity.

Do not copy Unix paths into Windows configuration or Windows backslash paths into Linux commands. If a configured path fails, run that exact executable directly with --version. Success proves the path points to a runnable downloader.

3.4 Separate discovery failures from network failures

Once mpv launches yt-dlp, the message may change to an HTTP error, certificate problem, authentication request, extractor failure, or unsupported URL. That change is useful: downloader discovery has been fixed.

Test the URL directly:

yt-dlp --simulate "https://actual-url-here"

If this fails too, investigate yt-dlp updates, site support, network access, authentication requirements, or URL validity. Do not keep modifying mpv's hardware decoder, GPU driver, display server, audio backend, subtitle settings, or HDR options. Those components operate after URL resolution and cannot make a missing external downloader appear.

4. Use mpv Logging to Identify the Exact Discovery Failure

Terminal output is usually more informative than a brief on-screen message. Increase logging for the built-in ytdl hook:

mpv --no-config --msg-level=ytdl_hook=trace "https://actual-url-here"

To preserve the full output in a file, add --log-file:

mpv --no-config --msg-level=ytdl_hook=trace --log-file=mpv-ytdl.log "https://actual-url-here"

Search the log for ytdl, yt-dlp, youtube-dl, failed, and not found. The useful distinction is whether mpv could not locate the executable, could not run it, or ran it and received an error.

4.1 Interpret common log outcomes

• Executable not found: Fix PATH or set an absolute ytdl hook path.
• Permission denied: Correct executable permission or operating system policy.
• Downloader ran but returned an error: Test the URL directly with yt-dlp.
• No ytdl hook activity: Check whether the hook or built-in scripts were disabled.
• Old youtube-dl selected: Remove the stale fallback or explicitly select yt-dlp.

The stats overlay and track list are useful only after a stream has opened. They can confirm selected formats, tracks, decoding performance, and dropped frames, but they do not diagnose an executable that mpv cannot find. Likewise, screenshot settings, shaders, video output, audio output, and hardware decoding are not part of downloader discovery.

5. Run a Clean Temporary Test Before Changing Multiple Options

Use a small test matrix so every result has a clear meaning. Avoid changing PATH, scripts, profiles, and frontend settings simultaneously.

1. Run yt-dlp --version in a terminal.
2. Run yt-dlp using its absolute path and --version.
3. Run mpv --no-config with the URL from the same terminal.
4. Run mpv with an explicit ytdl_hook-ytdl_path.
5. Run normal mpv from the terminal.
6. Finally, test the graphical frontend or desktop shortcut.

If step four works, the downloader and URL are usable, and ordinary executable discovery is the problem. If clean mpv works but normal mpv fails, inspect configuration and scripts. If terminal-launched mpv works but the frontend fails, fix the frontend environment. If yt-dlp itself cannot process the URL, the issue is outside mpv.

Change one setting, repeat the same test, and record the result. Stop as soon as the original URL opens and the log shows yt-dlp being invoked successfully. Further unrelated tuning can introduce a second problem.

6. Quick Fix Checklist

• Run yt-dlp --version and confirm it prints a version.
• Use where yt-dlp, Get-Command yt-dlp, or command -v yt-dlp.
• Install yt-dlp through an official or trusted package source.
• Restart the terminal and fully reopen graphical frontends after changing PATH.
• Test mpv with --no-config from the same terminal.
• Quote the URL and any executable path containing spaces.
• Set ytdl_hook-ytdl_path to an absolute yt-dlp path when PATH is unreliable.
• On Windows, verify which mpv.exe and yt-dlp.exe are actually being used.
• Check profiles, input bindings, and third-party scripts for obsolete downloader settings.
• Avoid falling back to a stale youtube-dl executable when current yt-dlp is available.
• Use --msg-level=ytdl_hook=trace and --log-file for exact errors.
• Stop changing settings once mpv launches yt-dlp and begins resolving the URL.

7. Frequently Asked Questions

7.1 Why does yt-dlp work in my terminal but not in mpv?

mpv may have been launched by a frontend or desktop environment with a different PATH. Launch mpv from the working terminal to confirm this. Then restart the frontend, configure its environment, or set an absolute ytdl_hook-ytdl_path.

7.2 Should yt-dlp.exe be placed in the Windows mpv folder?

It can be convenient for a portable setup, but an explicit path or a dedicated PATH directory is more predictable. If you place it beside mpv, verify that your shortcut and frontend use that exact mpv installation.

7.3 Can hardware decoding or GPU settings cause yt-dlp not found?

No. Hardware decoding, HDR, shaders, video output, and GPU drivers matter after media data is available. A downloader-not-found message occurs earlier, while mpv is trying to resolve the online URL.

7.4 Should I install youtube-dl as a fallback?

Usually not. A stale youtube-dl installation can create confusing fallback behavior. Prefer a current yt-dlp installation and configure mpv to use it explicitly when necessary. Remove obsolete PATH entries after confirming they are not needed by another application.

7.5 Why does the error change after I set ytdl_path?

A changed error often means discovery is fixed. For example, an HTTP, authentication, extractor, or unsupported-site error indicates that mpv successfully launched yt-dlp. Test the URL directly with yt-dlp --simulate and troubleshoot that new error instead.

7.6 Do I need to delete my mpv configuration folder?

No. First use --no-config for a temporary clean test. If that succeeds, inspect only the relevant ytdl settings, profiles, input bindings, and scripts. Preserve the rest of your configuration, including subtitles, tracks, HDR profiles, shaders, IPC settings, and hardware-decoding preferences.