mpv Install Build Missing Lua: How to Fix It

If mpv reports that the installed build is missing Lua, the most visible symptom is often a missing on-screen controller, commonly called the OSC. Lua scripts may also fail to load, including bundled scripts and custom scripts placed in your mpv configuration directory. This is usually a build or packaging problem rather than a subtitle, GPU, hardware-decoding, HDR, audio, or media-file problem. The safest approach is to confirm the missing capability with a clean command, inspect mpv's terminal output, and install a trusted build that includes Lua support before changing scripts or unrelated playback settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a local media file that you know mpv can play. A short video stored on the local disk is preferable because it removes network access, yt-dlp, stream authentication, and remote server behavior from the test.

Open Command Prompt or PowerShell on Windows, or a terminal on Linux or macOS. Run the following command, replacing the sample path with the actual path to your file:

mpv --no-config --osc=yes "path/to/test-video.mp4"

The --no-config option prevents your normal configuration, profiles, input bindings, and user scripts from affecting the test. The --osc=yes option explicitly requests mpv's on-screen controller. Quoting the path prevents spaces and shell-sensitive characters from being interpreted incorrectly.

Move the pointer over the playback window after the video opens. A successful test displays the OSC controls. If the video plays but no controls appear, inspect the terminal for a message saying that Lua support is unavailable, a Lua script cannot be initialized, or the OSC cannot be loaded.

1.1 Why the OSC is an effective Lua test

mpv's OSC is implemented as a built-in Lua script. Consequently, an mpv build without Lua support can still decode and display media while being unable to run the OSC. This explains the confusing combination of normal playback and missing controls.

A missing OSC does not always prove that Lua is absent. The OSC can be disabled by an option, hidden by configuration, or affected by input behavior. That is why the clean command and terminal messages matter. If the terminal explicitly reports missing Lua support, stop adjusting OSC layout, visibility, or script settings. Those changes cannot add a capability omitted when mpv was built.

1.2 Test a custom script directly

If your original problem concerns a particular script, test it only after the clean OSC test. You can request a script explicitly with:

mpv --no-config --script="path/to/script.lua" "path/to/test-video.mp4"

Success means the script initializes without a Lua-support error and performs its documented function. If every Lua script fails in the same way, the common cause is the mpv build. Do not begin debugging the script's source code until you have confirmed that the player can run Lua at all.

2. Check the mpv Build and Its Package Options

Lua support is determined when mpv is compiled. It cannot be enabled later by adding a line to mpv.conf. If a distributor, package maintainer, or local build process disabled Lua or could not find an appropriate Lua dependency, the resulting executable may lack support for Lua scripts.

Run this command to identify the executable being used and view its build information:

mpv --version

Keep the output for comparison, but do not assume every build presents Lua support in exactly the same way in its version summary. The runtime error produced when mpv attempts to load the OSC or a Lua script is generally the more direct test.

2.1 Make sure the expected executable is running

It is possible to install a corrected package but continue launching an older executable elsewhere on the system. Locate the command selected by your shell:

• On Windows Command Prompt, run where mpv.
• On PowerShell, run Get-Command mpv.
• On Linux or macOS, run command -v mpv.

If multiple paths appear, compare them with the application shortcut, file association, or launcher you normally use. Run the executable using its full path and repeat the clean OSC test. Success means the intended executable opens and the OSC loads without a missing-Lua message.

2.2 Install a trusted build that includes Lua

If the installed mpv build definitely lacks Lua, replace it through a trusted distribution channel. On Linux, prefer the normal package repository for your distribution or another repository explicitly documented by that distribution. Check package descriptions and build options when multiple variants exist, such as minimal, headless, or reduced-dependency packages.

On macOS, use the package manager or installation source you trust and verify that its mpv formula or package includes scripting support. On Windows, use a build source referenced by the official mpv installation documentation or a package manager whose package provenance you have verified. Avoid codec packs and random download sites. Lua support must be present in mpv itself, and installing an unrelated codec pack will not repair it.

After installing the replacement, close existing mpv processes, open a new terminal, and run:

mpv --no-config --osc=yes "path/to/test-video.mp4"

Stop changing settings when the OSC appears and the terminal no longer reports missing Lua. At that point, the required build capability is working. Any remaining failure affecting one custom script can be investigated separately.

2.3 Rebuild only if you intentionally compile mpv

If you compile mpv yourself, review the build system's feature summary and dependency detection rather than assuming Lua was enabled. Install the Lua development dependency supported by the mpv source version you are building, configure the scripting feature as enabled, and check that configuration completes without marking the required dependency unavailable.

Do not copy build flags from an old forum post without checking the current build documentation. Build systems and option names can change. A successful rebuild is one whose configuration summary confirms scripting support and whose installed executable passes the clean OSC test.

3. Check Options That Can Mimic Missing Lua

If the clean OSC test succeeds, Lua is present. The original problem is then probably caused by configuration, script-loading options, an incorrect path, or a profile. Reintroduce those elements one at a time.

3.1 Inspect OSC and script-loading options

Search mpv.conf and command-line arguments for settings that disable the OSC or automatic script loading. Relevant options include osc=no and load-scripts=no. A launcher may also supply these options without showing them in your main configuration file.

For a custom script, verify that it uses the .lua extension and resides in the correct scripts directory for the configuration location mpv is actually using. Alternatively, specify the script's absolute path with --script. Success means the script is listed as loaded in the terminal and its feature becomes available.

3.2 Check profiles and input bindings

A profile can override an earlier option. If you launch mpv with a named profile, inspect it using:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile you actually use. Look for OSC, script-loading, terminal, or input settings that differ from your clean test.

An input binding can also make a working script appear broken. Review input.conf for duplicate keys, malformed commands, or bindings overridden later in the file. Test the script through its normal interface before concluding that its shortcut failed. Once the script works with default input behavior, add custom bindings back individually.

3.3 Separate Lua failures from unrelated playback options

Subtitle selection, audio and video track selection, output drivers, hardware decoding, HDR processing, shaders, and screenshot templates do not add Lua support. They should be examined only if Lua has been confirmed working and the remaining symptom directly involves one of those functions.

• If video is blank but the OSC works, test the video output and hardware decoder.
• If subtitles are absent, inspect the track list and subtitle-selection options.
• If online URLs fail, test yt-dlp availability, network access, and the URL itself.
• If screenshots fail, inspect the screenshot directory, filename template, and write permissions.
• If only a script feature fails, inspect that script's documented requirements and messages.

This separation prevents an mpv player issue from turning into several unrelated configuration changes.

4. Check Paths, Permissions, and External Tools When Relevant

Operating system permissions do not normally cause an executable to be compiled without Lua. They can, however, prevent a working Lua script from being read or stop it from writing files.

4.1 Verify file paths and shell quoting

Use absolute paths during diagnosis. Put paths containing spaces in quotes. On Windows, confirm that a script has not accidentally been saved as script.lua.txt because file extensions are hidden. On Unix-like systems, ensure the script is readable by the account running mpv.

If an explicitly supplied script path works while automatic loading does not, the build supports Lua and the problem is the configuration directory or script placement. Stop reinstalling mpv and correct the path instead.

4.2 Check script-specific permissions

A script that writes thumbnails, bookmarks, history, logs, or temporary data needs permission to write to its target directory. Test with a user-owned directory rather than elevating mpv to administrator or root. Running a media player with unnecessary elevated privileges creates avoidable risk.

4.3 Treat yt-dlp and network problems separately

Some Lua scripts interact with external programs, but mpv's normal handling of many online URLs may also involve yt-dlp independently of your custom script. If local OSC and Lua tests pass while an online URL fails, check terminal output for yt-dlp discovery, unsupported-site, authentication, certificate, or network errors.

Test a legal, publicly accessible URL and verify the external tool through the same shell environment that launches mpv. A successful local Lua test combined with a failed network test means reinstalling Lua is unlikely to help.

5. Use Terminal Output and Focused Logging

Terminal output is the fastest way to distinguish a missing build feature from a configuration mistake. Launching mpv by double-clicking a file may hide the relevant message, so reproduce the issue from a terminal.

5.1 Increase message detail

Use a verbose message level for a controlled test:

mpv --no-config --osc=yes --msg-level=all=v "path/to/test-video.mp4"

Look for messages mentioning Lua, OSC, scripts, failed initialization, unknown options, or unreadable paths. Do not treat every warning as the cause. Focus on entries emitted immediately before or during the failed script load.

5.2 Save a log file

To preserve output for comparison, run:

mpv --no-config --osc=yes --log-file="mpv-lua-test.log" "path/to/test-video.mp4"

Open the log as text and search for lua, osc, script, error, and failed. Remove personal file paths, URLs, tokens, and other sensitive information before sharing a log publicly.

5.3 Use stats and track information appropriately

mpv's stats overlay can be another indication that bundled scripting works, although its key binding and behavior can be customized. The track list is useful for subtitle, audio, and video selection problems, but it does not diagnose missing Lua. Use each tool for the symptom it actually measures instead of using playback statistics as proof of build support.

6. Run a Clean Temporary Test Before Changing Many Options

The most reliable troubleshooting sequence changes one variable at a time. Do not delete your entire configuration folder. Preserve it and bypass it temporarily with --no-config.

1. Choose a known-good local media file.
2. Run mpv with --no-config --osc=yes.
3. Read the terminal output for an explicit Lua or OSC error.
4. Confirm which mpv executable the shell launches.
5. If Lua is absent, install or build a trusted Lua-enabled package.
6. Repeat the identical clean command.
7. Restore your normal configuration without custom scripts.
8. Add profiles, scripts, and input bindings back one group at a time.

If the clean test fails with an explicit missing-Lua error, configuration cleanup is not the next step. If the clean test succeeds, replacing the build is not the next step. This decision point keeps the investigation short and protects a working setup from unnecessary edits.

7. Quick Fix Checklist

• Run mpv --no-config --osc=yes with a known-good local file.
• Confirm that the terminal explicitly reports a Lua or OSC loading failure.
• Use where mpv, Get-Command mpv, or command -v mpv.
• Check whether the installed package is a minimal or reduced-feature build.
• Replace it through a trusted package manager or officially documented build source.
• Repeat the same clean command after installation.
• If the OSC works, inspect osc, load-scripts, profiles, and script paths.
• Do not debug script code until basic Lua execution succeeds.
• Do not change hwdec, HDR, subtitle, or audio settings for a confirmed Lua-build error.
• Stop when the OSC and a known-good Lua script load without Lua-related errors.

8. Frequently Asked Questions

8.1 Does mpv need Lua for video playback?

Not necessarily. Core playback can work in a build that lacks Lua, which is why video and audio may play normally while the OSC and Lua scripts are missing. Lua is required for Lua-based functionality, not for every decoding or output operation.

8.2 Why is the OSC missing even though mpv plays the file?

The OSC is a Lua script. It can be missing because the build lacks Lua, because osc=no is active, or because script loading is disabled or failing. The clean --no-config --osc=yes test and terminal output distinguish these causes.

8.3 Can I fix missing Lua by installing Lua separately?

Usually not for a prebuilt mpv executable. The player must have been compiled with the relevant scripting support. Installing a standalone Lua interpreter does not retroactively add that feature to an existing mpv binary. Install a suitable mpv package or rebuild mpv correctly.

8.4 Should I troubleshoot the custom script first?

No. First prove that a built-in Lua feature such as the OSC can load. If mpv says the build lacks Lua, script edits cannot solve the underlying problem. Investigate script compatibility and configuration only after basic Lua execution works.

8.5 Can hardware decoding or GPU drivers cause missing Lua?

GPU drivers, display servers, output drivers, and hardware decoders can cause rendering or performance problems, but they do not normally explain an explicit missing-Lua build message. Troubleshoot them only if Lua works and a separate video-output symptom remains.

8.6 What does a successful fix look like?

The same clean command that previously failed now opens the local file, displays the OSC when you move the pointer, and produces no missing-Lua or script-initialization error. A known-good custom script should also load when explicitly requested. Once those checks pass, stop replacing packages and address any remaining script-specific issue separately.