mpv No-config Disables Scripts: How to Fix It

When mpv behaves normally until you add --no-config, the option is usually doing exactly what it was designed to do: preventing normal configuration files from being loaded. The confusing part is that the resulting symptoms can look like broken scripts, missing subtitles, disabled shaders, lost keyboard shortcuts, failed HDR settings, unavailable yt-dlp integration, or a hardware-decoding problem. In many cases, the script itself has not been directly disabled. Instead, mpv has stopped loading an option, profile, path, or input binding that the feature depended on. The safest fix is to identify that dependency, test it explicitly, and restore only the required settings rather than changing many unrelated options.

1. What Does --no-config Actually Disable?

The --no-config option tells mpv not to load its normal configuration files. This includes the usual user and system configuration files, particularly mpv.conf and input.conf. As a result, options and bindings stored in those files disappear for that invocation.

This distinction matters because --no-config is primarily a configuration-loading switch. It should not automatically be interpreted as a universal command to disable every script. If a script appears to vanish in clean mode, investigate how the script is discovered, enabled, configured, or controlled.

Common indirect effects include:

• Options in mpv.conf no longer apply.
• Custom bindings in input.conf stop working.
• Profiles are unavailable unless their defining configuration is loaded explicitly.
• A custom script or script-opts setting is no longer applied.
• Shader, subtitle, screenshot, cache, audio, video, HDR, and hardware-decoding options return to defaults.
• Paths defined through configuration options are no longer supplied.
• A wrapper, shortcut, or launcher may use a different configuration directory than expected.

Success at this stage means understanding whether the missing behavior comes from a configuration file, an input binding, a script path, or an unrelated external dependency. Once that category is clear, stop changing unrelated playback settings.

1.1 Why a script can appear disabled

A script may load automatically from mpv's scripts directory while still behaving differently because its options were stored in mpv.conf or a script-specific configuration file. It may also rely on an input binding that was defined in input.conf. In that situation, the script is present but its visible command, menu, shortcut, or preferred behavior is missing.

Another possibility is that the script was never in the standard scripts directory. It may have been loaded by an explicit script=/path/to/script.lua option inside mpv.conf. With configuration loading disabled, that instruction disappears.

2. Confirm the Symptom With a Minimal Clean mpv Command

Begin with one known local media file. A local file removes network access, yt-dlp, authentication, redirects, and remote server behavior from the first test. Open a terminal or command prompt and run:

mpv --no-config "path/to/test-video.mkv"

On Windows, a practical example is:

mpv --no-config "C:\Videos\test-video.mkv"

On Linux or macOS, use an absolute path where possible:

mpv --no-config "/home/user/Videos/test-video.mkv"

Now run the same file without clean mode:

mpv "path/to/test-video.mkv"

Compare only the feature under investigation. For example, check whether a script message appears, a subtitle track is selected, a key binding works, a shader activates, or hardware decoding is reported.

If the feature works without --no-config and fails with it, you have confirmed a configuration-dependent difference. If it fails in both commands, --no-config is probably not the root cause. Move to file, permission, driver, external-tool, or network checks instead.

2.1 Test whether the script itself can be loaded

If you know the script's exact path, load it explicitly during the clean test:

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

Use the appropriate extension for the script, and preserve quotation marks around paths containing spaces. If the script loads now, its old loading mechanism depended on configuration or directory discovery. If it still fails, inspect terminal output for a syntax error, missing module, incompatible API usage, inaccessible file, or incorrect path.

Success means the script initializes or its expected command becomes available. At that point, stop modifying video and audio options because they are not responsible for script discovery.

3. Check the Feature Directly Related to the mpv Player Issue

After reproducing the difference, locate the smallest setting that restores the feature. Do not copy the entire old configuration into the command immediately. Re-add one option at a time so that the dependency remains visible.

3.1 Configuration files and profiles

Inspect mpv.conf for options connected to the symptom. Also search for profile sections such as [profile-name]. A command using --profile=profile-name cannot reproduce a profile whose definition was only present in a configuration file that clean mode skipped.

You can inspect a profile with:

mpv --show-profile=profile-name

Run that command under the same conditions as the failing launch. If mpv reports that the profile does not exist when --no-config is present, the profile was defined in a skipped configuration file.

If you intentionally want clean mode plus a known configuration file, specify the file explicitly:

mpv --no-config --include="/absolute/path/to/test.conf" "path/to/file.mkv"

This is useful for creating a small diagnostic configuration containing only the options needed for the feature. Success means the profile or included option is recognized without restoring the rest of the normal setup.

3.2 Input bindings

If a script appears inactive only because its keyboard shortcut stopped working, inspect input.conf. Clean mode prevents normal input configuration from loading, so custom bindings can disappear even if the script remains active.

Test the script through another documented interface, such as its on-screen menu, console command, or script message. You can also explicitly load an input configuration:

mpv --no-config --input-conf="/absolute/path/to/input.conf" "path/to/file.mkv"

Success means the original key triggers the expected action. Stop troubleshooting script loading if terminal output already confirms that the script initialized and restoring the binding fixes the symptom.

3.3 Scripts directory lookup and config-dir

mpv normally uses platform-specific configuration locations. Scripts placed in the appropriate scripts subdirectory can be discovered from that configuration area. However, a launcher may supply --config-dir, changing which directory mpv treats as its configuration location.

The --config-dir=/path option also affects special path expansion associated with mpv's configuration directory. A path using mpv's ~~/ special prefix resolves relative to the active configuration directory. If a wrapper changes --config-dir, a value such as ~~/scripts, ~~/shaders, or ~~/script-opts may point somewhere different from what you expect.

Check the complete launch command for both --no-config and --config-dir. Then compare the actual script location with the directory mpv is using. For a decisive test, pass an absolute script path instead of relying on special path expansion.

Success means the explicitly named script loads from the expected file. Once confirmed, correct the launcher's configuration directory or move the file to the intended scripts directory. Do not maintain duplicate copies unless you deliberately operate multiple isolated mpv configurations.

3.4 Subtitles and audio or video tracks

Configuration changes can resemble decoding failures. Options that select subtitle languages, force subtitle visibility, choose audio languages, exclude tracks, or set preferred track IDs may have been stored in mpv.conf. Clean mode restores default track selection.

Use mpv's track list or on-screen controls to verify that the desired track actually exists. You can also cycle tracks with mpv's default bindings. Re-add only the relevant option, such as a subtitle file:

mpv --no-config --sub-file="/absolute/path/to/subtitles.srt" "path/to/video.mkv"

If an external subtitle file loads when supplied explicitly, the problem concerns discovery, naming, path expansion, or an omitted configuration option. If the desired audio or subtitle track does not appear in the track list, no selection option can activate it.

3.5 Output drivers, hardware decoding, shaders, and HDR

Options such as vo, gpu-api, gpu-context, hwdec, shader paths, tone-mapping choices, and display-related settings are often stored in mpv.conf. With --no-config, mpv returns to automatic or default selection. The resulting image may look different even though playback remains functional.

Re-add one relevant option manually. For example:

mpv --no-config --hwdec=auto "path/to/test-video.mkv"

If testing a shader, use its absolute path rather than a configuration-relative path. If hardware decoding fails only when forced, return to software decoding while investigating driver and codec support. Successful playback is more important than forcing a particular decoder.

Success means the expected output path is reported and playback is stable. Stop adding GPU options once the required behavior returns, because stacking unrelated rendering settings can create a second problem.

3.6 yt-dlp, online URLs, playlists, and streams

Online playback involves more than mpv configuration. mpv may depend on yt-dlp for supported website URLs, while direct network streams depend on protocol support, server availability, authentication, and correct shell quoting.

If an executable path or script option was stored in mpv.conf, clean mode will omit it. Confirm that yt-dlp is available through the process environment used by mpv. A terminal session, desktop shortcut, and graphical launcher can have different PATH values.

First test a local file. Then test the URL without --no-config, followed by the same URL with it. Quote URLs containing characters interpreted by the shell, especially &. Do not download replacement binaries from random websites. Use the official yt-dlp project or a trusted operating-system package source.

Success means mpv recognizes the URL, invokes the required external tool when applicable, and begins loading media. If the URL fails in both clean and configured modes, investigate the URL, network, authentication, or external tool rather than configuration loading.

3.7 Screenshot settings

Screenshot failures frequently come from a missing configured directory, format, template, or binding. Under clean mode, the custom screenshot key from input.conf may disappear, or screenshots may be written to a default location rather than the configured folder.

Trigger the default screenshot action and watch terminal output for the destination path or error. Confirm that the destination exists and is writable. If necessary, test with an explicit absolute screenshot directory. Success means mpv reports a saved image and the file appears in that location.

4. Check Operating System and External Dependencies

When explicit re-entry of the relevant option does not restore the feature, check the dependency beneath it. Keep these checks tied to the observed symptom.

• Permissions: Confirm that mpv can read the script, media, subtitle, shader, and configuration files and can write to log or screenshot directories.
• Shell quoting: Quote paths containing spaces and URLs containing shell metacharacters. Avoid copying Unix quoting syntax blindly into Windows Command Prompt or PowerShell.
• File paths: Prefer absolute paths during diagnosis. Relative paths can resolve differently depending on the launcher's working directory.
• GPU drivers: Investigate drivers only when logs show output initialization, decoding, presentation, or GPU-context errors.
• Display server: On Linux, Wayland and X11 sessions can lead mpv to select different GPU contexts or presentation paths.
• Audio backend: Check the selected output device and backend when video plays but audio fails. A configured device may have disappeared under clean mode.
• External tools: Verify yt-dlp or other legitimate helper tools from the same environment that launches mpv.
• Media limitations: A damaged file, unsupported stream, missing track, or unusually high bitrate can fail independently of configuration.

For high-bitrate local or network media, distinguish decoding performance from storage or network throughput. If pausing allows the cache to recover, the bottleneck may not be the script or configuration at all.

5. Use Logs and mpv Diagnostics Efficiently

Terminal output is often enough to identify the missing component. Launch mpv from a terminal instead of double-clicking the file so that initialization and error messages remain visible.

5.1 Increase message detail

Use --msg-level to increase logging for the area being investigated. A broad diagnostic command is:

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

This can produce a large amount of output. Search for the script name, failed paths, profile messages, output initialization, track selection, or external command errors.

To preserve output in a file, use:

mpv --no-config --log-file="mpv-clean-test.log" --msg-level=all=v "path/to/test-video.mkv"

Then run a configured comparison:

mpv --log-file="mpv-normal-test.log" --msg-level=all=v "path/to/test-video.mkv"

Compare the startup sections. Look for configuration files loaded, scripts initialized, options applied, tracks selected, and output drivers chosen. Avoid publishing logs without reviewing them because URLs and local paths may contain sensitive information.

5.2 Use the stats overlay and track list

The stats overlay helps identify the active decoder, dropped frames, display synchronization, video parameters, and other playback details. It is useful when the perceived mpv player issue concerns performance, hardware decoding, HDR rendering, or high-bitrate playback.

The track list is more appropriate for subtitle, audio, and embedded-video selection problems. If a track exists but is not selected, restore the selection option. If it does not exist, inspect the media file or external subtitle path.

5.3 Interpret a successful test correctly

A clean test is successful when mpv opens the known file with defaults and no unrelated configuration. It does not need to reproduce every customization. Its purpose is to establish whether the core player works independently of your setup.

If clean mode works but normal mode fails, an option, profile, script, or binding in the normal configuration is likely involved. If normal mode works but clean mode lacks a feature, that feature depends on skipped configuration. If both fail identically, broaden the investigation beyond --no-config.

6. Run a Clean Temporary Test Before Editing Your Setup

Do not delete the entire configuration folder. Instead, preserve your working setup and create a small temporary test file containing one suspected option.

1. Choose one known local media file.
2. Run it with --no-config.
3. Identify one missing behavior.
4. Add the single option most directly connected to that behavior.
5. If necessary, explicitly load one script or one input configuration.
6. Record whether the symptom changes.
7. Add another option only after the previous result is clear.

For example, if a script does not respond, first load the script explicitly. If it initializes but the key does nothing, load the input binding explicitly. If the script then works but uses default behavior, add its script options. This sequence separates loading, control, and configuration into distinct tests.

Stop changing settings as soon as the desired feature works and the log contains no related error. Additional changes make the final fix harder to understand and maintain.

7. Quick Fix Checklist

• Remove --no-config if you expect the normal mpv configuration to load.
• Inspect desktop shortcuts, file associations, shell aliases, wrapper scripts, and launchers for an accidental --no-config.
• Compare one local file with and without clean mode.
• Load the affected script explicitly with --script.
• Load custom key bindings explicitly with --input-conf.
• Check whether the missing feature was defined in mpv.conf or a profile.
• Verify the active --config-dir and any ~~/ special paths.
• Use absolute paths for scripts, shaders, subtitles, logs, and screenshots during testing.
• Re-add one relevant option manually instead of restoring the entire configuration.
• Use --show-profile, terminal output, --msg-level, and --log-file to confirm what loaded.
• Check yt-dlp availability from the same environment that launches mpv.
• Stop when the missing feature returns and the related error disappears.

8. Frequently Asked Questions

8.1 Does --no-config disable every mpv script?

No. Its central purpose is to prevent normal configuration files from loading. A script can appear disabled because its explicit loading option, settings, profile, or keyboard binding came from a skipped configuration file. Test with an explicit --script path and inspect terminal output before concluding that script support itself is disabled.

8.2 Why does my script load but its shortcut stop working?

The shortcut was probably stored in input.conf, which is not loaded normally under --no-config. Explicitly load the input file or invoke the script through another available command. If that works, restore the binding rather than changing script or video settings.

8.3 How does --config-dir affect script and shader paths?

It changes the configuration directory mpv uses. That can change where scripts and related files are discovered and how configuration-relative special paths such as ~~/ resolve. During troubleshooting, replace special or relative paths with absolute paths to determine whether directory selection is the cause.

8.4 Should I keep --no-config in my normal mpv shortcut?

Only if you intentionally want mpv to ignore normal configuration files every time. For most customized installations, leaving it in a desktop shortcut, file association, alias, or wrapper causes settings and bindings to seem randomly missing. Remove it after diagnostic testing if you want your regular setup restored.

8.5 Can I use clean mode while adding one required option?

Yes. This is one of the best diagnostic techniques. Run --no-config and add one command-line option, explicit script, input file, or included test configuration. When that single addition restores the feature, you have identified the relevant dependency.

8.6 What if mpv is not working even without --no-config?

The issue is probably not caused by clean mode. Test a known local file, inspect logs, and check the exact failing layer: media readability, track availability, output initialization, audio device, GPU driver, permissions, external tool, stream URL, or network access. Keep the clean-mode comparison as evidence, but stop treating configuration suppression as the primary cause.

The most reliable mpv no-config disables scripts fix is therefore not a broad reset. Confirm the clean-mode difference, identify the missing configuration dependency, restore it explicitly, and stop when the expected script or playback feature works. This approach preserves a known-good configuration while producing a fix you can explain and maintain.