mpv Script Not Loading: How to Fix It

When an mpv user script does not load, the failure usually comes from one of a few places: mpv is reading a different configuration directory, the script is in the wrong folder, the filename or script type is unsupported, the script crashes during initialization, or a command-line option disables normal configuration loading. The fastest solution is to confirm the symptom with a tiny known-good script, inspect mpv's terminal output, and change only the setting that the evidence identifies.

This guide focuses specifically on Lua and JavaScript user scripts. It applies to Windows, Linux, and macOS, whether you use mpv for local media, subtitles, HDR playback, online URLs, playlists, network streams, shaders, hardware decoding, yt-dlp integration, or IPC automation.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before changing your main configuration, determine whether mpv can load any script at all. A minimal test separates script-loading problems from unrelated playback issues such as hardware decoding, output drivers, shaders, network access, or a damaged media file.

1.1 Locate the Configuration Directory mpv Is Actually Using

The normal user configuration directory depends on the operating system and packaging method. Common locations include:

• Windows: %APPDATA%\mpv, which commonly expands to C:\Users\YourName\AppData\Roaming\mpv
• Linux and other Unix-like systems: ~/.config/mpv
• macOS: ~/.config/mpv
• Portable Windows installations: a portable_config directory beside mpv.exe can override the normal user directory

Create a directory named scripts directly inside the active configuration directory. A typical Linux or macOS path is ~/.config/mpv/scripts. A typical Windows path is %APPDATA%\mpv\scripts.

Do not assume the configuration directory based only on where you placed mpv.conf. Package managers, portable builds, graphical front ends, environment variables, and launcher shortcuts can cause a different mpv executable or configuration location to be used.

1.2 Create a Tiny Known-Good Lua Script

Create a plain-text file named script-test.lua in the scripts directory. Put this code in it:

mp.register_event("file-loaded", function()
    mp.osd_message("Test script loaded")
    mp.msg.info("Known-good test script loaded")
end)

Save the file, close every running mpv instance, and start mpv from a terminal with a local media file:

mpv --no-config --script=/absolute/path/to/script-test.lua /path/to/media-file

On Windows, quote paths that contain spaces:

mpv.exe --no-config --script="C:\Users\YourName\Desktop\script-test.lua" "C:\Media\test video.mkv"

Success means an on-screen message appears after the file loads and the terminal reports Known-good test script loaded. If this works, mpv's script engine is functioning. Stop investigating build support and focus on your normal script directory, script dependencies, or configuration. If it fails, keep the terminal open and inspect the error instead of changing playback options.

2. Check the Script and Its Direct Configuration

A script-loading failure should be investigated at the script layer first. Subtitle preferences, audio tracks, video output, HDR settings, hardware decoding, yt-dlp, screenshots, and stream options matter only if the script interacts with those features or playback fails after the script has already loaded.

2.1 Verify the Filename and Script Type

mpv recognizes scripts by their file type. Lua scripts normally use .lua. JavaScript scripts use .js and depend on JavaScript support being present in the mpv build. Avoid misleading names such as example.lua.txt, which Windows may display as example.lua when known extensions are hidden.

Check the real filename in file properties or enable filename extensions in the file manager. Also confirm that the downloaded item is the actual raw script, not an HTML page saved from a code-hosting website. Opening the file in a text editor should show script source code rather than webpage markup.

If a Lua test loads but a JavaScript script does not, the problem may be JavaScript support or the script itself. If neither loads, test explicit loading with --script and inspect the log.

2.2 Confirm Lua Support in the mpv Build

Standard full mpv builds commonly support Lua scripting, but custom, embedded, or unusually minimal builds may omit expected features. Run the following command in a terminal:

mpv --version

Review the displayed build information and then run the known-good Lua script explicitly. The explicit test is more useful than relying on assumptions about a package name. An error stating that the script language cannot be handled, or an unrecognized scripting API error at startup, points toward the build or an incompatible script.

Use mpv from the official project links or a trusted operating-system package repository. Do not install random codec packs or unverified binaries. Scripts are not codecs, so codec packs do not repair script discovery.

2.3 Distinguish the scripts and script-opts Directories

The scripts directory contains executable user scripts. The script-opts directory contains optional configuration files read by scripts. Placing a Lua file in script-opts will not normally cause mpv to execute it.

A common layout looks like this:

mpv/
  mpv.conf
  input.conf
  scripts/
    example.lua
  script-opts/
    example.conf

The option filename and keys must match what the script expects. Some scripts use a different internal name from the downloaded filename, so consult the script's documentation. A missing script-opts file usually causes default settings to be used. A malformed option can instead trigger an error or make a feature appear inactive.

Success means the script appears in the startup log without an initialization error and responds to its documented command or key binding. Once that happens, stop moving files and investigate only the script's options or activation conditions.

2.4 Check input.conf and Script Bindings

A loaded script can look inactive when its key binding is missing, overridden, or written with the wrong script-message name. Examine input.conf for duplicate bindings. Later or conflicting bindings may replace the action you expected.

If the script documentation provides a binding such as a script-message or script-binding command, copy it exactly. Key names can differ from the printed character, and graphical launchers may intercept some shortcuts.

Test the script's feature through the mpv console or a temporary, simple key binding if the script supports one. Success means the expected action occurs even if the original keyboard shortcut did not work. In that case, the script was loading correctly and only the binding needs repair.

2.5 Check Profiles and Options That Affect Script Loading

Review launcher arguments, shortcuts, shell aliases, and profiles for options such as --no-config, --no-scripts, an explicit --config-dir, or a manually defined script path. A profile can also alter conditions under which a script appears useful, such as disabling video, changing tracks, or selecting another output path.

Use --show-profile=PROFILE_NAME to print a named profile's contents. This helps identify inherited options without activating and deactivating settings blindly. If removing one script-related disabling option restores loading, stop there and retain the rest of the profile.

3. Check Operating System and External Dependencies

If the script path and file type are correct, investigate access restrictions and dependencies. These checks are especially relevant when a script loads but immediately reports errors.

3.1 Verify File Permissions and Path Quoting

The user running mpv must be able to read the script and enter every parent directory in its path. On Linux and macOS, inspect permissions with ls -l. Avoid running mpv as an administrator or with sudo merely to bypass a permission problem. Correct ownership and read access for the affected files instead.

Shell quoting matters when loading a script explicitly. Spaces, parentheses, wildcard characters, and backslashes can be interpreted by the shell before mpv receives the argument. Quote complete paths and use absolute paths during diagnosis.

Success means the explicit --script command loads the file without a file-not-found or permission-denied message. If it works only with an absolute path, correct the original path or configuration directory instead of changing unrelated mpv settings.

3.2 Check Download Quarantine and Security Controls

macOS, Windows security tools, endpoint protection, or restrictive application sandboxing can block downloaded files or external processes. Inspect security notifications and the file's properties. Only allow a script after reviewing its source and obtaining it from a trusted project.

Some sandboxed mpv packages may not see files outside their permitted locations. Move the test script into the package's documented configuration area or use a packaging method that provides the access you need. Do not disable system-wide security controls as a first response.

3.3 Verify External Tools Only When the Script Requires Them

Some scripts call programs such as yt-dlp, ffmpeg, curl, or platform-specific utilities. mpv may successfully load the script even when the external program is missing. The failure then appears only when you invoke a feature.

Run the required tool from the same terminal environment used to launch mpv. If the command is not found, configure the script with an absolute executable path or add the trusted installation directory to the appropriate PATH environment variable.

For online playback, separate script behavior from network and yt-dlp behavior. First test the script with a local file. Then test the URL directly in mpv. A site extraction error, authentication requirement, unavailable stream, or blocked network request does not prove the user script failed to load.

4. Use mpv Logging to Identify the Exact Failure

Terminal output is the most reliable way to distinguish discovery, syntax, dependency, and runtime failures. Launching mpv only by double-clicking a file can hide the useful message.

4.1 Increase Script-Related Message Detail

Start with verbose terminal output:

mpv -v /path/to/media-file

For more targeted detail, use message-level controls:

mpv --msg-level=all=v /path/to/media-file

You can also write output to a file:

mpv --log-file=mpv-script-test.log --msg-level=all=v /path/to/media-file

Search the log for the script filename, lua, javascript, error, failed, or scripts. Useful findings include file-not-found errors, syntax errors with line numbers, unknown API functions, missing modules, and failures to launch external commands.

A syntax error means mpv found the script but could not initialize it. That is different from a discovery failure. Restore an unmodified copy compatible with your environment or correct the reported line if you maintain the script.

4.2 Interpret Playback Tools Correctly

The stats overlay and track list help when a script depends on playback state, but they do not directly prove script discovery. Use the stats overlay to verify video decoding, dropped frames, output details, and hardware decoding. Use mpv's track information to confirm that expected audio, video, or subtitle tracks exist and are selected.

For example, a subtitle automation script may load correctly but do nothing when the file has no subtitle track. An HDR-oriented script may load but not activate for SDR content. A screenshot helper may fail because its output directory is unwritable. A stream helper may wait for a supported URL rather than a local file.

Success means the log confirms script initialization and the required media condition is present. At that point, stop changing script paths. Troubleshoot the specific media, output directory, selected track, driver, decoder, or external tool named in the error.

5. Run a Clean Temporary Test Before Changing Multiple Options

A controlled test prevents configuration interactions from obscuring the cause. Do not delete your entire configuration directory. Preserve it and bypass it temporarily.

5.1 Test Without the Normal Configuration

Run mpv with --no-config, explicitly load the known-good script, and use a small local media file:

mpv --no-config --script=/absolute/path/script-test.lua /absolute/path/test-file.mp4

If this succeeds, repeat the test while loading the real script explicitly. If the real script fails, its code, compatibility, dependencies, or options are responsible. If both scripts succeed explicitly but not through automatic discovery, the active configuration directory or scripts folder is wrong.

5.2 Reintroduce Components One at a Time

1. Test the known-good script explicitly with --no-config.
2. Test the real script explicitly with --no-config.
3. Allow the normal configuration but keep the script explicit.
4. Move the verified script into the active scripts directory.
5. Restore its script-opts configuration.
6. Restore its input bindings and relevant profile.

After each step, launch mpv and verify the script's startup message or documented action. The first step that causes failure identifies the layer to inspect. Stop as soon as the cause is isolated. Changing hardware decoding, GPU drivers, audio backends, display servers, subtitle styling, and network settings simultaneously makes the result harder to interpret.

6. Quick Fix Checklist

• Confirm that mpv is using the configuration directory you expect.
• Place executable scripts in scripts, not script-opts.
• Check for hidden extensions such as .lua.txt.
• Open the file and confirm it contains source code, not saved HTML.
• Test a tiny known-good Lua script with an explicit --script path.
• Use --no-config to bypass profiles and conflicting options temporarily.
• Read terminal output or create a log with --log-file.
• Check whether --no-scripts or a custom --config-dir is active.
• Verify input.conf bindings separately from script loading.
• Check external tools only when the script documentation requires them.
• Use a local media file before testing URLs, streams, HDR, or unusual formats.
• Stop changing settings once the log confirms the script loads successfully.

7. Frequently Asked Questions

7.1 Where Should mpv Scripts Be Installed?

They normally belong in a scripts directory inside mpv's active user configuration directory. Common locations are %APPDATA%\mpv\scripts on Windows and ~/.config/mpv/scripts on Linux and macOS. Portable or packaged installations may use another location, so verify which mpv executable and configuration directory are active.

7.2 Why Does a Script Work With --script but Not Automatically?

This usually means the script itself is valid but automatic discovery is looking elsewhere. Check the directory name, the active configuration path, portable configuration, custom --config-dir arguments, file permissions, and options that disable scripts.

7.3 Does --no-config Disable an Explicitly Loaded Script?

--no-config prevents normal configuration files from being loaded. An explicitly supplied --script=/path/file.lua is useful precisely because it creates a controlled script test. Do not expect scripts stored in the usual directory to be discovered normally while performing a clean no-config test.

7.4 Why Is the Script Listed in the Log but Not Doing Anything?

The script may require a key binding, a supported media type, an available subtitle or audio track, a writable output directory, a particular playback state, or an external program. If initialization succeeds, stop troubleshooting script discovery and test the feature's documented activation conditions.

7.5 Can Hardware Decoding or the GPU Prevent a Script From Loading?

Hardware decoding, GPU drivers, output drivers, and display servers usually affect playback or rendering rather than initial Lua script discovery. They become relevant when the log confirms that the script loaded and the failing function depends on video output, shaders, HDR metadata, screenshots, or frame processing.

7.6 What Is the Fastest Reliable mpv Script Not Loading Fix?

Run a known-good Lua script with --no-config and an explicit absolute --script path, while saving verbose terminal output. If that succeeds, repair automatic discovery or the real script. If it fails, use the exact log message to address permissions, syntax, build support, or an invalid path.