mpv Script Options Ignored: How to Fix It

When mpv script options appear to be ignored, the script is often running but reading a different file, expecting a different option name, or loading its settings only at startup. The most common causes are an incorrect script-opts directory, a configuration filename that does not match the script's option namespace, invalid key=value syntax, multiple mpv configuration locations, or a script that was never loaded. Less often, the requested behavior depends on subtitles, tracks, hardware decoding, HDR output, yt-dlp, network access, or another mpv subsystem rather than the script option itself. The following process isolates those possibilities without deleting your configuration or changing unrelated playback settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing several files, establish whether the script can load and whether one unmistakable option changes its behavior. Choose an option documented by the script and select a value that produces an obvious result. A tiny timing adjustment can be difficult to confirm, while changing a visible menu position, overlay color, generated filename, or enabled feature is easier to verify.

1.1 Test the script explicitly

Open a terminal and start mpv with its normal configuration disabled, the script loaded explicitly, and the option supplied on the command line. The general pattern is:

mpv --no-config --script=/absolute/path/to/example.lua --script-opts=example-option=value /path/to/media

On Windows, quote paths containing spaces:

mpv.exe --no-config --script="C:\Users\Name\Desktop\example.lua" --script-opts=example-option=value "C:\Videos\test.mkv"

The exact prefix before the option depends on the identifier used by the script. Many scripts use their filename without the .lua extension, but a script can define another identifier when it reads options. Check the script's documentation first. If necessary, inspect its source for a call such as read_options, which commonly reveals the expected identifier and supported keys.

Success means the script loads and the selected behavior visibly changes. If this command works, stop changing playback, GPU, subtitle, or network settings. The script and option are valid, so the remaining problem is almost certainly your normal configuration path, filename, syntax, or an overriding value.

1.2 Understand what the clean test excludes

--no-config prevents your ordinary mpv configuration from influencing the test. Explicitly naming the script also avoids uncertainty about automatic script discovery. This excludes conflicts from mpv.conf, input.conf, profiles, automatically loaded scripts, and many path mistakes.

If the minimal command does not work, check the terminal output before proceeding. An unknown script option may be ignored by the script, while a Lua error, missing module, or incompatible script can prevent initialization entirely. Do not assume that a configuration file is the problem when the script itself did not load.

2. Check the Script Option File and the Related mpv Setting

2.1 Put the file inside the script-opts directory

Persistent script option files belong in a directory named script-opts inside mpv's active configuration directory. A typical layout is:

• ~/.config/mpv/scripts/example.lua
• ~/.config/mpv/script-opts/example.conf
• ~/.config/mpv/mpv.conf
• ~/.config/mpv/input.conf

On Linux and many macOS installations, the normal configuration directory is ~/.config/mpv. On Windows, a common location is %APPDATA%\mpv. However, portable installations, application bundles, environment variables, and launchers can change the active location. Confirm the path from mpv's verbose log instead of relying only on what is customary.

Success means the log shows mpv using the configuration directory that contains your script-opts folder. Once that is confirmed, do not create duplicate copies in additional locations. Duplicates make later troubleshooting harder.

2.2 Match the option filename to the script identifier

For a script named example.lua, the option file is commonly script-opts/example.conf. The match must be exact on case-sensitive filesystems. Files such as example.lua.conf, Example.conf, or example.txt may not be read.

Windows users should enable filename extensions in File Explorer. A file displayed as example.conf may actually be example.conf.txt. Save it as plain text rather than as a rich-text document.

There is an important qualification: the script controls the option namespace it requests. Most scripts align that namespace with the script filename, but not all do. If the author's documentation specifies a different configuration filename, follow that documentation. Success means the expected file is opened or its values are reflected in the script's behavior.

2.3 Use valid key=value syntax

A script option file normally contains one setting per line:

option_name=value

Use the exact key documented by the script. Do not add the script name to every key inside the file unless the script explicitly requires it. For example, if the command-line form is --script-opts=example-size=24, the contents of example.conf are commonly:

size=24

Check for typographic quotation marks, accidental spaces inside a key, unsupported values, misspellings, and copied inline comments. Boolean values are often written as yes or no, but scripts can implement their own parsers and accepted values. The script's documentation is authoritative.

Start with one known option. If it works, add the remaining settings individually. Stop as soon as the intended behavior appears because further edits can obscure which correction solved the problem.

2.4 Restart mpv after editing

Many Lua scripts read option files once during initialization. Saving the file while mpv is open therefore may not change the running instance. Close every mpv window and start a new process after each controlled edit. Pausing, reloading the media, or moving to the next playlist item may not reload the script.

Some scripts provide a documented reload command or key binding. Use it only if the script says it rereads options. Otherwise, a complete restart is the reliable test. Success means a newly started mpv process shows the changed behavior without a command-line override.

2.5 Separate script options from other configuration systems

An entry in script-opts/example.conf does not automatically become a native mpv option. Likewise, putting a native option such as hwdec=auto in a script's file will not configure hardware decoding unless that script explicitly reads it.

• Native mpv options normally belong in mpv.conf.
• Keyboard and mouse bindings normally belong in input.conf.
• Script-specific settings belong in script-opts/name.conf.
• Named profiles belong in mpv.conf and apply only when activated.
• Shaders are loaded through native mpv options or script-defined controls, depending on the setup.

If a key binding calls a script message, verify that the message and script name are correct. A broken binding can make a valid script option appear ineffective because the configured action is never triggered.

3. Check Paths, Permissions, and Dependencies

3.1 Identify portable configuration paths

mpv can use a portable configuration directory instead of the usual per-user location. This is common with self-contained Windows installations and customized application bundles. If a portable_config directory is active, editing %APPDATA%\mpv\script-opts may have no effect.

Do not delete either directory. Launch the exact mpv executable you normally use with verbose logging, identify the configuration files it attempts to load, and edit only the active location. Also check whether a desktop shortcut, file association, launcher, or media manager starts a different mpv executable than your terminal does.

3.2 Verify read permissions and path spelling

The user running mpv must be able to read the script and its option file. On Linux and macOS, check ownership and permissions if files were created with elevated privileges or copied from another account. On Windows, confirm the file is not stored in a protected application directory requiring administrative writes.

Avoid running mpv as administrator merely to work around a configuration problem. A user-owned configuration directory is safer and easier to maintain. Also check path capitalization on Linux, where script-opts and Script-Opts are different directories.

3.3 Determine whether the option depends on another subsystem

A script setting may load correctly but have no visible effect because its required input is absent. Check the direct dependency before assuming that mpv ignored the file.

• A subtitle script may require an active subtitle track, supported subtitle format, or visible subtitle output.
• An audio script may require a selected audio track or a functioning audio output backend.
• A video, shader, HDR, or tone-mapping script may require video output, a compatible GPU context, or a specific rendering path.
• A hardware-decoding control may be limited by the codec, GPU, driver, or selected video output.
• An online-video script may require a working yt-dlp executable, supported URL, and network access.
• A screenshot script may require a writable output directory and a valid filename template.
• A playlist or stream script may not activate for local files, unsupported protocols, or unavailable metadata.

Test with media that definitely meets the feature's conditions. For example, use a file with a known subtitle track when testing subtitle behavior. Success means the prerequisite is visible and the script responds. At that point, stop adjusting unrelated output drivers or decoders.

4. Use mpv Logs and Runtime Information

4.1 Capture terminal output and a log file

Start mpv from a terminal so initialization messages remain visible. For a detailed log, use:

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

Reproduce the problem once, close mpv, and search the log for the script filename, its option namespace, script-opts, error, and failed. The log can reveal which configuration directory was used, whether the script loaded, and whether a runtime error occurred.

Be careful when sharing logs publicly. They can contain usernames, local paths, stream URLs, query tokens, and media filenames. Redact sensitive values without removing the lines surrounding the error.

4.2 Check script-generated messages

Well-designed scripts often report invalid options, missing dependencies, or initialization failures through mpv's logging system. Some remain quiet at the default message level, which is why verbose logging is useful. If the script documents a particular message prefix, increase logging for that component; otherwise, --msg-level=all=v is a practical starting point.

A successful load may produce an initialization message, but not every script announces success. The strongest confirmation is a combination of no script error, the correct configuration path, and the expected behavioral change.

4.3 Inspect profiles, tracks, and playback state

If a named profile might override a related native mpv option, inspect it with --show-profile=profile-name. This displays the profile's contents but does not prove that a script read its own option file. Use it to identify conflicts involving video output, hardware decoding, subtitles, audio, or filters.

Use mpv's track list to verify which video, audio, and subtitle tracks are present and selected. The built-in stats overlay, commonly opened with i, can help confirm decoding and rendering information. These tools are relevant when the script option acts on playback state, but they cannot repair a filename or directory mismatch.

5. Run a Clean Temporary Test Before Making Broad Changes

If the command-line option works but the persistent file does not, create a small temporary configuration rather than dismantling your established setup. The goal is to test only mpv, one script, one option file, and one media file.

1. Create a new temporary directory.
2. Inside it, create scripts and script-opts directories.
3. Copy only the affected script into scripts.
4. Create the matching script-opts/name.conf file.
5. Add one documented key=value setting.
6. Launch mpv with that directory selected through its configuration-directory option.
7. Use a local media file with known tracks and no network dependency.

If the temporary setup works, your main configuration probably contains a duplicate script, a conflicting option, an active profile, a second script that changes the same behavior, or a path mismatch. Reintroduce components one at a time. Do not copy the entire old configuration into the test directory because that immediately restores the uncertainty you are trying to remove.

If the temporary setup fails, confirm the option identifier and supported key against the script's documentation. Then inspect the log for a script error or missing dependency. Only after those checks should you consider whether the script is incompatible with your installed mpv environment.

6. Quick Fix Checklist

• Confirm the script itself loads without a Lua or dependency error.
• Place the option file under the active mpv configuration directory's script-opts folder.
• Match the .conf filename to the script's documented option identifier.
• Check for hidden .txt extensions and case mismatches.
• Use one exact, documented key=value entry.
• Restart mpv completely after saving the file.
• Test the same option through --script-opts.
• Check for portable configuration paths or a different mpv executable.
• Read verbose script log output before changing GPU or decoder settings.
• Verify required subtitles, tracks, URLs, tools, and writable output paths.
• Use a temporary clean configuration to expose conflicts.
• Stop changing settings once the expected behavior appears consistently.

7. Frequently Asked Questions

7.1 Where should mpv script option files go?

They normally go in script-opts inside mpv's active configuration directory. Typical locations include ~/.config/mpv/script-opts on Linux and many macOS setups, or %APPDATA%\mpv\script-opts on Windows. A portable installation can use another directory, so verify the active path in verbose output.

7.2 Should the option file match the Lua filename?

Usually. A script named example.lua commonly reads example.conf. However, scripts can request a different option namespace. Follow the script's documentation or inspect its option-reading call when the obvious filename does not work.

7.3 Why does --script-opts work while the file is ignored?

This strongly suggests that the script and key are valid but the persistent file is misplaced, misnamed, unreadable, or formatted incorrectly. It can also mean you are editing one mpv configuration while launching another installation that uses a portable directory.

7.4 Can mpv reload script options without restarting?

Only if the script implements a reload mechanism. Many scripts read options once when they initialize. Unless the documentation provides a reload command, close all mpv processes and start mpv again.

7.5 Does --no-config prove that my option file works?

No. It is primarily an isolation tool. When you disable normal configuration and explicitly load a script with a command-line option, you prove whether the script can recognize the option without interference. Test the persistent file separately in a clean temporary configuration.

7.6 When is this actually an mpv playback problem?

It becomes a broader playback problem when the logs confirm the script loaded its settings but the required playback condition is missing or failing. Examples include no selected subtitle track, an unavailable audio output, unsupported hardware decoding, a failed yt-dlp invocation, an inaccessible stream, or an unwritable screenshot directory. Diagnose that specific dependency instead of continuing to rename the option file.