mpv Config File Ignored: How to Fix It

When an mpv configuration change has no visible effect, the player is usually reading a different file, receiving an overriding command-line option, applying a profile only under certain conditions, or encountering a setting that cannot affect the current media or system. The fastest way to fix an mpv config file ignored problem is to prove which configuration file mpv loads, test one unmistakable option, and then reintroduce profiles, scripts, shaders, hardware decoding, and other customizations gradually. This guide walks through that process on Windows, Linux, and macOS without asking you to erase your existing configuration.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by separating configuration loading from playback problems. A subtitle that does not appear, HDR output that looks wrong, or a stream that fails can resemble a configuration failure even when mpv loaded mpv.conf correctly. Test an option whose result is easy to recognize.

1.1 Add One Obvious Temporary Setting

Open the suspected mpv.conf and temporarily add a simple option such as:

volume=20

Save the file, close every running mpv window, and start mpv again with a local media file. Do not use a desktop shortcut that already supplies volume options. If playback begins at 20 percent volume, the configuration is being read. Remove the temporary line and concentrate on the specific option that is failing.

If the volume does not change, do not start rewriting unrelated settings. Continue to the directory, filename, and logging checks below. Success at this stage means an unmistakable setting from the file affects a newly launched mpv process. Once that happens, stop moving or renaming the file.

1.2 Compare Normal Playback With --no-config

Run the same local file once normally and once with configuration disabled:

mpv "test-video.mkv"
mpv --no-config "test-video.mkv"

On Windows PowerShell or Command Prompt, use the executable name or full path appropriate to your installation. The --no-config option tells mpv not to load its normal configuration files. If both runs behave identically despite your obvious test option, mpv is probably not finding the file you edited. If they differ, the configuration is loading and the remaining issue is likely an override, conditional profile, unsupported option, script interaction, or media limitation.

2. Check the Config File Location and Name

The most common mpv config file ignored fix is placing a correctly named plain-text file in the directory used by the exact mpv executable being launched.

2.1 Use the Correct Config Directory for Your Operating System

Common user configuration locations are:

• Linux: ~/.config/mpv/mpv.conf, unless the relevant configuration environment variables or an explicit config directory change the location.
• macOS: ~/.config/mpv/mpv.conf is the standard location documented by mpv. Confirm the home directory belongs to the user launching mpv.
• Windows: %APPDATA%\mpv\mpv.conf for a normal per-user configuration.
• Windows portable mode: portable_config\mpv.conf beside mpv.exe. The directory must be named portable_config.

A Windows portable configuration takes precedence for that executable. This can explain why edits under %APPDATA% appear to be ignored. It can also explain inconsistent behavior when two mpv installations exist and only one has a neighboring portable_config directory.

On any operating system, a launcher, package wrapper, or custom command may use --config-dir. That option directs mpv to another configuration directory. Inspect shortcuts, shell aliases, desktop entries, scripts, and application integrations if the normal location does not match the log.

2.2 Verify the Exact Filename and Extension

The main file must be named mpv.conf. On Windows, File Explorer may hide known extensions, allowing a file displayed as mpv.conf to be named mpv.conf.txt. Enable filename extensions in Explorer or inspect the file from PowerShell.

Also confirm that the editor did not create a rich-text document. Use a text editor and save plain text. A byte order mark is not normally the first suspect, but switching to a conventional UTF-8 plain-text save can remove editor-related uncertainty.

Success means the log identifies the same file you edited and a simple test option takes effect. At that point, do not create duplicate copies in several directories because duplicates make later troubleshooting harder.

3. Check the Setting Directly Related to the Issue

Once configuration loading is confirmed, test the failing feature itself. An option can be loaded but overridden, limited to a profile, rejected as invalid, or irrelevant to the selected track or output path.

3.1 Look for Command-Line and Later-File Overrides

Command-line options can override values from mpv.conf. Options parsed later can also replace earlier values. Review the command shown in a shortcut, launcher, file association, shell alias, or frontend. For example, a shortcut containing --volume=100 can supersede volume=20.

Within mpv.conf, search for repeated settings. Profiles and included configuration files may apply another value. Test with a direct terminal command that supplies no optional arguments beyond the filename. If that works, add the launcher's arguments back one at a time.

3.2 Distinguish mpv.conf From input.conf

General player options belong in mpv.conf. Key and mouse bindings belong in input.conf in the same active configuration directory. A line such as SPACE cycle pause is an input binding, not an mpv.conf option.

If a binding fails, check for conflicting bindings, keyboard-layout differences, and scripts that capture the same key. Test a distinctive unused key and a simple command. Success means pressing the key produces the expected action in a newly launched player.

3.3 Inspect Profiles and Conditional Profiles

A setting beneath a profile header does not apply globally. For example:

[high-quality]
scale=ewa_lanczossharp

This setting applies only when the profile is activated, such as with --profile=high-quality, or when an associated automatic condition matches. Use:

mpv --show-profile=high-quality

This displays the profile's contents so you can check spelling and the options it would apply. For conditional profiles, verify that the condition actually matches the current file, protocol, dimensions, or other property. A profile that works on a local MKV may correctly remain inactive for an online URL.

3.4 Test Subtitles and Audio or Video Tracks

Subtitle styling options cannot display a subtitle track that is not selected or available. Use mpv's track list or stats display to verify the file contains the expected subtitle, audio, and video tracks. External subtitles must be discoverable, explicitly loaded, or named according to the configured matching behavior.

Similarly, language preferences influence selection only when matching tracks exist and have useful language metadata. If a file labels every audio track as unknown, an audio-language preference may not select the track you expected.

Success means the intended track is listed and selected, and the relevant option changes that track's behavior. If the track does not exist or its metadata is inadequate, stop modifying unrelated rendering settings.

3.5 Isolate Video Output, Hardware Decoding, HDR, and Shaders

Options involving vo, gpu-api, gpu-context, hwdec, HDR, tone mapping, or shaders depend on operating-system capabilities, graphics drivers, display configuration, and the media format. Loading an option does not guarantee that the requested decoder or output path is available.

Temporarily remove forced backends and test conservative values. For hardware decoding, compare the configured behavior with --hwdec=no. For shaders, test without the shader line and verify that every referenced file path exists. Quote command-line paths containing spaces; in the configuration file, follow mpv's configuration syntax rather than copying shell quoting blindly.

Success means the log reports the intended decoder and output path without fallback or initialization errors. Once playback is stable, re-enable one advanced option at a time.

3.6 Check Scripts, yt-dlp, Streams, and Screenshots

Scripts normally belong in the active configuration directory's scripts subdirectory. A script may require a particular runtime feature, companion module, or script-specific options file. Confirm that startup output identifies the script and reports no load error.

For online URLs, mpv may rely on yt-dlp for site extraction. A valid mpv.conf cannot compensate for a missing executable, blocked network request, unsupported website, authentication requirement, or obsolete external tool. Use a trusted installation source and verify that the same user account can run yt-dlp from the terminal.

For network streams, first test the URL directly and examine terminal errors. Expired tokens, unavailable servers, TLS problems, firewalls, and unsupported manifests are not configuration-loading failures.

Screenshot options can load correctly while saving fails because the target directory does not exist or is not writable. Test with a known writable absolute directory, then press the configured screenshot key. Success means mpv reports a saved image and the file appears at the expected path.

4. Check Operating System and External Dependencies

If mpv reads the correct configuration but the feature still fails, inspect the system dependency closest to that feature.

4.1 Confirm Permissions and Paths

The user launching mpv must be able to read mpv.conf, included files, scripts, shaders, fonts, and external subtitles. Screenshot and cache destinations must be writable. Avoid running mpv as an administrator merely to hide a permissions problem. Instead, place user configuration and output files in locations owned by the user.

Relative paths may be interpreted from a working directory you did not expect, especially when mpv starts through a graphical launcher. For a diagnostic test, use an absolute path to a shader, subtitle, script resource, or screenshot directory. If that succeeds, correct the relative-path assumption rather than changing the underlying feature.

4.2 Match the Test to the Relevant Backend

• For black video, rendering errors, HDR problems, or failed hardware decoding, inspect the GPU driver and active display server or graphics API.
• For missing or distorted sound, inspect the selected audio device, audio backend, channel layout, and whether another application has exclusive access.
• For online playback, check DNS, proxy settings, certificates, firewall rules, yt-dlp availability, and whether the URL itself remains valid.
• For high-bitrate media, test local storage throughput, network stability, demuxer behavior, and decoding load before assuming the configuration was skipped.

Stop when a backend-neutral test works and the log identifies a failure in one specific backend. Further edits to the config location will not repair a graphics driver, unreachable server, or unreadable media file.

5. Use mpv Logging and Diagnostic Tools

Terminal output is more reliable than guessing. Launch the same mpv executable you normally use and preserve a log for comparison.

5.1 Confirm the Loaded File With --log-file

Run:

mpv --log-file=mpv.log --msg-level=all=v "test-video.mkv"

Open mpv.log and search for configuration-loading messages, the path to mpv.conf, option parsing errors, unknown options, profile activity, script loading, selected tracks, video output, audio output, and hardware decoding. Use a writable absolute path for the log if the current directory is protected.

The key success signal is that the log names the exact configuration file you edited and does not report an error for the test option. If it names another path, edit that file or deliberately launch mpv with the intended configuration directory. If no user configuration appears, return to the filename, extension, portable-mode, and executable checks.

5.2 Compare Configured and Clean Logs

Create one normal log and one clean log:

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

Compare the selected tracks, enabled scripts, profiles, decoder, video output, audio output, and errors. This reveals whether the configuration actually changes startup and which component introduces the failure.

5.3 Use Profiles, Stats, and Track Information

Use --show-profile=PROFILE_NAME to inspect a named profile. During playback, mpv's stats overlay can expose rendering, decoding, dropped-frame, synchronization, and track information. The default i binding commonly opens statistics unless the input configuration has replaced it.

Track information is particularly useful for subtitle and language-selection problems. Confirm what mpv detected before changing selection rules. Diagnostic success means you can point to a specific loaded option, active profile, chosen track, fallback, or startup error.

6. Run a Clean Temporary Test Before Making Broad Changes

Do not delete the entire configuration folder. Preserve it and test with a separate temporary directory instead. This protects working scripts, bindings, profiles, and shader settings.

6.1 Build a Minimal Temporary Configuration

1. Create an empty temporary directory in a writable location.
2. Add an mpv.conf containing only volume=20.
3. Launch mpv with --config-dir pointing to that directory.
4. Confirm that the volume test works.
5. Add the failing option and test again.
6. Add related options individually until the problem returns.

The exact path syntax depends on your shell, so quote paths containing spaces. This procedure distinguishes an installation problem from a conflict inside the regular configuration.

If the minimal directory works, your mpv executable can load configuration correctly. The conflict is in an option, profile, include, script, or path from the original setup. If it does not work, inspect the command, executable path, temporary filename, permissions, and log before proceeding.

6.2 Test One Representative Media File

Use a short, known-good local file first. Online URLs add network and extractor variables, while unusual HDR or high-bitrate files add hardware and format variables. After the basic setting works locally, test a representative subtitle file, HDR video, playlist, stream, or URL relevant to your actual problem.

Stop changing settings as soon as the desired behavior works and the log is clean enough to explain why. Save a copy of the working minimal configuration before adding optional refinements.

7. Quick Fix Checklist

• Confirm the file is named exactly mpv.conf, not mpv.conf.txt.
• Use ~/.config/mpv/mpv.conf on Linux or macOS unless the config directory was changed.
• Use %APPDATA%\mpv\mpv.conf for a normal Windows user configuration.
• Check for portable_config\mpv.conf beside the Windows executable.
• Verify that a shortcut, alias, or frontend is launching the executable you inspected.
• Remove --no-config from launch commands when configuration should load.
• Check whether command-line options override values from the file.
• Keep key bindings in input.conf, not mpv.conf.
• Use --show-profile to inspect named profiles.
• Use --log-file and verbose messages to identify the loaded config path and parsing errors.
• Test local media before troubleshooting yt-dlp, network streams, or expiring URLs.
• Use a separate temporary config directory instead of deleting the existing one.
• Reintroduce scripts, shaders, hardware decoding, and advanced output options one at a time.

8. Frequently Asked Questions

8.1 Why Is mpv.conf Ignored on Windows?

The usual causes are a hidden .txt extension, editing %APPDATA%\mpv\mpv.conf while the launched executable uses a neighboring portable_config directory, or launching a different mpv executable than expected. Generate a verbose log and search for the configuration path before moving files.

8.2 Does --no-config Disable mpv.conf?

Yes. The --no-config option disables normal configuration loading for that run. It is useful as a comparison test, but it should not remain in a shortcut or file association when you expect mpv.conf to apply.

8.3 Can Command-Line Options Override mpv.conf?

Yes. A value supplied later on the command line can supersede a value from the configuration. Launchers and frontends may add arguments without making them obvious. Test directly from a terminal with only the media filename, then add arguments back gradually.

8.4 How Do I Know Which mpv.conf Was Loaded?

Run mpv with --log-file=mpv.log --msg-level=all=v, then inspect the log for configuration-reading messages and paths. The correct outcome is a log entry referring to the exact file you edited, followed by no parsing error for the option under investigation.

8.5 Why Does a Setting Work for One File but Not Another?

The setting may be inside a conditional profile, depend on a particular track, require a supported codec or output path, or have no effect on that media type. Compare track lists, profile activation, decoder selection, and output information between the two files.

8.6 Should I Reinstall mpv or Delete the Config Folder?

Not as a first step. Reinstallation does not fix a file placed in the wrong user directory, a hidden extension, or a command-line override. Deleting the folder can destroy useful scripts and bindings. Use a separate temporary configuration directory, prove that a minimal file loads, and then isolate the conflicting option safely.