mpv File Specific Config Not Loading: How to Fix It

When an mpv file-specific config is not loading, the problem usually falls into one of a few categories: mpv never discovered the intended configuration file, the option was overridden later, the setting is not valid for that media or output path, or the test is being confused by watch-later state, scripts, profiles, or shell parsing. The fastest solution is not to rewrite your entire mpv setup. Instead, prove that the option works, confirm how the file is being matched, and then add complexity back one layer at a time.

This guide focuses specifically on per-file behavior for local media, playlists, online URLs, and network streams. It covers file-local configuration, command-line markers, conditional profiles, watch-later files, special paths, logs, and clean temporary tests on Windows, Linux, and macOS.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before inspecting scripts, shaders, HDR settings, or hardware decoding, establish whether mpv can apply one obvious option to the affected file. Choose an option whose effect is easy to see and does not depend heavily on the media format.

For example, open a terminal and temporarily run mpv without the normal configuration:

mpv --no-config --pause=yes "path/to/video.mkv"

On Windows PowerShell, a typical command might look like this:

mpv --no-config --pause=yes "C:\Videos\Test File.mkv"

If the file opens paused, the option works and mpv is receiving the intended file path. That success tells you to stop investigating basic command execution. The remaining problem is likely configuration discovery, profile matching, option precedence, or a later component overriding the setting.

If the file does not open or the command behaves unexpectedly, inspect the terminal output before changing any configuration. Confirm that the executable being launched is the mpv installation you expect:

mpv --version

On Linux and macOS, you can also use which mpv. In Windows PowerShell, use Get-Command mpv. Multiple installations can make you edit one configuration directory while launching another mpv binary.

1.1 Test the exact option directly

After the paused-start test succeeds, replace it with the setting that is actually failing. Examples include:

• --sid=2 for a specific subtitle track
• --aid=1 for a specific audio track
• --hwdec=no to disable hardware decoding for a problematic file
• --vf=format=yuv420p to test a video-filter requirement
• --screenshot-format=png to test screenshot configuration
• --profile=profile-name to apply a named profile explicitly

Use only one diagnostic option at first. Success means the option works when supplied directly, so you should stop changing the underlying decoder, output driver, or operating system. Move on to discovering why the per-file mechanism did not supply the same option.

2. Verify the Per-File Configuration Method

mpv supports several mechanisms that can appear to be per-file configuration, but they do not behave identically. A same-name sidecar file, a conditional profile, command-line grouping, and watch-later state solve different problems. Confirm which mechanism you intended to use.

2.1 Enable file-directory configuration when using sidecar files

mpv does not normally trust and load configuration files beside arbitrary media without being told to use file-directory configuration. If you expect a configuration beside the media file to load, test with:

mpv --no-config --use-filedir-conf=yes "path/to/video.mkv"

A file-specific configuration uses the media filename with .conf appended. For a media file named video.mkv, the corresponding filename is:

video.mkv.conf

Place a conspicuous test option in that file:

pause=yes

Then launch the media with --use-filedir-conf=yes. If it starts paused, mpv found and loaded the sidecar configuration. Remove the test option and add the real settings one at a time.

Be careful with hidden extensions. Windows File Explorer may display video.mkv.conf.txt as though it were video.mkv.conf. Enable filename extensions and verify the complete name. Also check capitalization on case-sensitive Linux filesystems.

Loading configuration from a media directory has security implications because the directory can influence playback options. Use this feature only for directories and files you trust. A conditional profile in your main configuration is often safer for content arriving from untrusted locations.

2.2 Use conditional profiles for filenames and paths

A conditional profile is usually the cleanest method when one file, directory, extension, URL, or path needs special behavior. Profiles belong in your normal mpv.conf and can use profile-cond to decide when they apply.

A simplified filename-based profile can look like this:

[special-video]
profile-cond=filename == "video.mkv"
pause=yes

A path-based condition can inspect path. Exact expressions depend on what you are matching, so begin with a simple exact comparison before attempting pattern matching or multiple conditions. Paths may differ from what you typed because mpv can normalize local paths, and URLs can include query strings.

Test the profile explicitly first:

mpv --profile=special-video "path/to/video.mkv"

If explicit activation works but automatic activation does not, the options inside the profile are valid. Stop editing those options and correct only the condition. Use logs to see the filename or path mpv actually recognizes.

2.3 Understand profile restoration and file-local resets

Some mpv options are file-local. They can reset when mpv advances to another playlist entry rather than remaining globally changed for the rest of the process. Conditional profiles may also restore previous values when their conditions stop matching, depending on profile behavior and restoration settings.

This matters when you test several files in one mpv instance. An option working on the first entry and disappearing on the second may be expected scope behavior, not a failed configuration. Conversely, a script or input command can change an option after the profile is evaluated.

Test the target as the only playlist entry. If that works, build a two-file playlist containing one matching and one nonmatching file. Success means the special behavior appears only on the matching entry and returns to normal on the other file. Once that happens, stop changing restoration settings.

2.4 Use per-file command-line markers correctly

mpv provides --{ and --} markers for options that should apply locally to grouped playlist entries. A command can conceptually take this form:

mpv normal.mkv --{ --pause=yes special.mkv --} another.mkv

Options inside the markers apply to the enclosed playlist entries and are reset outside that group. These markers must reach mpv as literal arguments. Some shells interpret braces, so quoting may be necessary:

mpv normal.mkv "--{" --pause=yes special.mkv "--}" another.mkv

Shell behavior varies, so inspect errors and try the quoted form if mpv reports an unknown argument or the shell transforms the command. Success means only special.mkv receives the local option.

3. Separate Configuration Problems From Media and Component Limitations

An option can load correctly yet have no visible effect. Check the subsystem directly related to the symptom rather than treating every failure as a general mpv player issue.

3.1 Subtitle and audio track settings

A configured sid or aid value works only if that track exists for the current file. Track numbers and language metadata can differ between releases, encodes, and streaming manifests. Use mpv's track list in the terminal or open the interactive track list through your configured interface.

For language-based selection, verify that the media actually contains language tags. A preference such as slang=eng cannot reliably select an untagged subtitle track. External subtitle discovery also depends on filenames, directories, and subtitle-related options.

Success means the expected track is visibly selected for the target file. Stop modifying file-local loading once the profile or sidecar setting appears in logs and the correct existing track is active.

3.2 HDR, shaders, output drivers, and hardware decoding

HDR output and shader behavior depends on the video output, GPU context, operating system, display server, graphics driver, display capabilities, and media metadata. A per-file profile may load while the requested output path remains unavailable.

Test the profile with an unmistakable neutral option such as pause=yes. If that works but the HDR or shader result does not, configuration discovery is fixed. Investigate the video chain separately. Temporarily test --hwdec=no to determine whether a hardware decoder is bypassing or conflicting with a filter requirement.

Do not install random codec packs or unofficial binaries as a first response. mpv commonly uses its own supported decoding stack, and an unrelated codec pack is unlikely to fix a profile condition or sidecar filename.

3.3 Scripts and input bindings

Lua or JavaScript scripts can change properties after file loading. Input bindings can also run commands that override a profile. If the option briefly applies and then changes, test without scripts or with an isolated configuration directory.

Remember that --no-config disables normal user configuration, which can include expected scripts and bindings. It is a diagnostic control, not necessarily the final setup. Reintroduce the profile first, then scripts one at a time. Stop when the behavior changes because the last component added is the likely conflict.

3.4 yt-dlp, URLs, playlists, and network streams

For online media, filename may not equal the page URL you entered. A resolver such as yt-dlp can produce direct media URLs or separate audio and video streams. Conditions based on an exact local filename may therefore never match.

First confirm that the URL works without the profile. Then explicitly activate the profile. If explicit activation succeeds, inspect the recognized path and use a stable condition that matches the original URL or relevant media property. Ensure yt-dlp is installed through a trusted source and visible to the same environment that launches mpv.

Network failures, authentication requirements, expired signed URLs, and unsupported DRM are not file-specific configuration failures. If the stream itself does not open in a clean test, fix access to the stream before revisiting per-file options.

3.5 Screenshot settings

If only screenshot options appear broken, confirm that the screenshot command is actually being triggered and that the destination directory exists and is writable. A profile can successfully set the format or template while file creation fails because of permissions, an invalid path, or forbidden filename characters.

Test with a simple writable directory and a basic filename template. Success means a screenshot is created in that location with the expected format. At that point, restore the desired template carefully.

4. Check Paths, Permissions, and Shell Quoting

Per-file setups rely heavily on exact paths. Spaces, apostrophes, brackets, ampersands, backslashes, dollar signs, and shell metacharacters can alter a command before mpv receives it.

Quote every media and configuration path. On Windows, use quoted paths such as "C:\Media Files\Movie [HDR].mkv". In POSIX shells, single quotes usually preserve a literal path, but a path containing a single quote needs special handling. Avoid manually escaping a path differently in several layers of a launcher script.

Verify permissions by reading the configuration file as the same user running mpv. Also verify write access when testing logs, screenshots, or watch-later state. On macOS, app launchers can have different filesystem access or environment variables from Terminal. On Linux, sandboxed packages can see different paths than system packages. On Windows, a GUI shortcut may use a different working directory than PowerShell.

Success means the same quoted command works repeatedly from the intended launcher. Once confirmed, stop changing decoder and media options because they cannot repair a path that never reached mpv.

5. Use mpv Diagnostics to Find the Override

Terminal output is often enough to identify a misspelled option, unreadable file, failed script, unavailable output driver, or unmatched profile. Increase detail only as needed.

5.1 Create a focused log

Run the affected file with a log file:

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

If that is excessively noisy, target relevant modules or use a lower verbosity. Search the log for the profile name, sidecar filename, option name, script errors, track selection, hardware decoding, video output, and audio output.

Write the log to a known writable location. Logs can contain local paths and URLs, including sensitive query parameters, so redact them before sharing.

5.2 Inspect profiles with show-profile

Use the profile inspection option to confirm that a named profile exists and contains the expected settings:

mpv --show-profile=special-video

If mpv cannot find the profile, you are probably editing the wrong configuration file, using the wrong profile name, or launching another installation. If the profile is displayed correctly, stop rewriting it and investigate its condition or a later override.

5.3 Use the stats overlay and track list

The stats overlay can reveal the active decoder, hardware decoding state, video output information, frame timing, and other playback details. The track list confirms which audio, video, and subtitle tracks exist and which are selected.

These tools distinguish an option-loading problem from a media limitation. For example, requesting subtitle track 3 cannot succeed when the file has only two subtitle tracks.

5.4 Compare normal startup with no-config startup

Run the same file twice:

1. Launch normally and record the result.
2. Launch with --no-config and the failing option supplied directly.

If the clean command works, something in the normal configuration, scripts, bindings, or profiles is interfering. If both fail in the same way, examine option validity, media capabilities, output drivers, external tools, and operating system support.

6. Distinguish Watch-Later State From Configuration Files

Watch-later files are playback-state records, not general-purpose replacements for mpv.conf or per-file sidecar configuration. They commonly preserve information used to resume a file, and their names may be derived from a hash rather than the visible media filename.

A watch-later entry can make playback appear file-specific because reopening one file restores saved state. That does not prove that video.mkv.conf or a conditional profile loaded. Conversely, a saved property can make a new profile seem ineffective if restored state changes the same behavior.

Test with --no-resume-playback when resume state may be interfering:

mpv --no-resume-playback "path/to/video.mkv"

Do not delete the entire configuration directory. If a watch-later entry is clearly implicated, back up and isolate only the relevant state entry, or temporarily disable resume behavior for the test. Success means the intended option applies consistently when resume restoration is disabled.

7. Run a Clean Temporary Test Before Making Permanent Changes

A controlled test prevents several unrelated variables from moving at once. Create a temporary directory containing one small, known-good media file and, if testing file-directory configuration, its correctly named .conf sidecar.

1. Start with --no-config and verify that the file plays.
2. Add one obvious command-line option such as --pause=yes.
3. Test the sidecar with --use-filedir-conf=yes, or test a named profile explicitly.
4. Replace the obvious option with the real subtitle, audio, video, screenshot, or decoder setting.
5. Add scripts, shaders, input bindings, and resume behavior individually.
6. Finally, retest the original path, URL, playlist, or network location.

After each successful step, preserve that known-good command. If the next addition breaks playback, undo only that addition. This is faster and safer than deleting configuration folders, reinstalling mpv, or changing multiple GPU and audio settings simultaneously.

8. Quick Fix Checklist

• Confirm the correct mpv executable is being launched.
• Test the affected file with --no-config --pause=yes.
• Supply the real failing option directly on the command line.
• For sidecars, use the exact name filename.ext.conf.
• Enable trusted file-directory configuration with --use-filedir-conf=yes.
• Check for hidden .txt extensions and case mismatches.
• Activate a named profile explicitly before debugging its condition.
• Use --show-profile=NAME to verify profile contents.
• Quote paths and command-line grouping markers for your shell.
• Test the target as the only playlist entry.
• Remember that file-local options reset outside their intended scope.
• Use the track list before forcing subtitle or audio track numbers.
• Disable resume temporarily when watch-later state may interfere.
• Check logs for later scripts or bindings that overwrite properties.
• Stop changing settings as soon as the expected behavior is reproducible.

9. Frequently Asked Questions

9.1 Does mpv automatically load a config named after the media file?

File-directory configuration must be enabled for mpv to use trusted directory-specific or file-specific configuration files. For a file named movie.mkv, check for the exact sidecar name movie.mkv.conf and test with --use-filedir-conf=yes. Because local configuration can influence playback, enable it only for directories you trust.

9.2 Why does an option work for one playlist item and reset on the next?

The option may have file-local scope, be enclosed by --{ and --} markers, or belong to a profile whose condition no longer matches. Test each item separately, then use a two-item playlist to verify that the option activates and restores at the intended boundaries.

9.3 Are watch-later files the same as per-file config files?

No. Watch-later files store resume-related playback state, while per-file configuration deliberately supplies options for a file. Disable resume temporarily with --no-resume-playback if saved state appears to override or imitate your configuration.

9.4 Why does my filename-based profile not match an online URL?

An online page can be resolved into different media URLs, and the recognized filename may not equal the URL you typed. First activate the profile explicitly to prove its options work. Then inspect logs and match a stable property or path associated with the original input.

9.5 How can I tell whether the profile loaded but the option failed?

Put an obvious temporary option such as pause=yes in the profile. If the file starts paused, the profile loaded. Remove that test and investigate the specific subsystem, such as track availability, hardware decoding, HDR output, shader compatibility, screenshot permissions, or external-tool access.

9.6 Should I reinstall mpv or delete its configuration folder?

Not initially. A direct --no-config test, profile inspection, and focused log usually isolate the problem without destroying working settings. If isolation is necessary, use a temporary setup or move one suspected file at a time while keeping backups. Reinstall only after confirming that the executable itself is missing or damaged, and obtain software from a trusted official or platform-maintained source.