mpv Directory Config Not Loading: How to Fix It

When an mpv directory config is not loading, the player may still open the media normally while ignoring the subtitles, shaders, hardware decoding, track selection, output settings, scripts, or other options you expected. The most common explanation is not a broken installation: mpv does not blindly load configuration files from arbitrary media directories by default. Other likely causes include using the wrong configuration directory, launching mpv through a wrapper that changes its arguments, placing commands in the wrong type of file, or testing an option whose external dependency is unavailable. The steps below separate directory-config behavior from unrelated playback problems so you can identify the first failing layer and stop changing settings once it works.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by determining whether mpv itself can play the affected media without your normal configuration. This prevents a shader, script, profile, output driver, or invalid option from being mistaken for a directory-config problem.

1.1 Run mpv without its normal configuration

Open a terminal and run mpv with --no-config, followed by a local file you know should play. Quote the path whenever it contains spaces.

• Windows: mpv.exe --no-config "C:\Media\Test Video.mkv"
• Linux: mpv --no-config "/home/user/Videos/Test Video.mkv"
• macOS: mpv --no-config "/Users/user/Movies/Test Video.mkv"

If the file plays, mpv, the basic demuxer, and the basic decoding path are working. The failure is probably in your configuration assumptions or one of your configured features. If the file does not play, inspect the terminal error before investigating directory-specific settings.

For an online URL, repeat the test with the URL in quotes. A local file succeeding while a URL fails usually points to network access, URL support, authentication, or an external tool such as yt-dlp. It does not prove that directory configuration is broken.

1.2 Test one visible option explicitly

Choose an option with an unmistakable result and pass it on the command line. For example, use --fullscreen, --pause, or a temporary screenshot directory. Avoid beginning with HDR processing or a complex shader chain because several components can affect their results.

Command-line options normally override configuration-file settings. If the explicit option works but the same option in the expected directory config does not, you have isolated the problem to config discovery, config syntax, precedence, or launch behavior. At this point, stop changing GPU and codec settings because they are not relevant to the discovery failure.

2. Understand Why mpv Does Not Load Arbitrary Directory Configs

The key distinction is that mpv has a normal user configuration directory, while media folders are untrusted input locations. Dropping an mpv.conf file beside a movie does not automatically guarantee that mpv will read it. Automatic local configuration can be dangerous because a downloaded or shared directory could alter player behavior without the user deliberately approving those settings.

2.1 Verify the normal user configuration location

Your main mpv.conf, input.conf, scripts, and related files belong in mpv's recognized configuration directory unless you deliberately select another one. Typical locations include the following:

• Windows commonly uses a portable_config folder beside mpv.exe for a portable setup, or mpv's user configuration location under the user profile.
• Linux commonly uses ~/.config/mpv, subject to XDG environment settings.
• macOS commonly uses ~/.config/mpv, although application bundles and launchers can introduce different behavior.

Do not assume that a folder named config beside the executable is equivalent to portable_config. Also do not assume that a package manager build, graphical frontend, or application bundle uses the working directory visible in your file manager.

To remove ambiguity, create a temporary directory containing only a minimal mpv.conf, then launch mpv with --config-dir pointing to it. For example: mpv --config-dir="/tmp/mpv-test" "video.mkv". On Windows, use a path such as mpv.exe --config-dir="C:\Temp\mpv-test" "C:\Media\video.mkv".

Success means the visible test option in that temporary mpv.conf takes effect. If it does, the syntax is acceptable and your ordinary launch is looking somewhere else. Stop editing the option itself and investigate the normal config path or launcher.

2.2 Use local configuration only deliberately

mpv provides file-local configuration behavior that can be enabled deliberately, including the --use-filedir-conf option described in its manual. This behavior should be treated as a trust decision, not as a universal convenience switch. Only enable it for directories whose contents and configuration files you control.

Run a controlled test by placing a minimal local configuration in a trusted test directory and launching mpv from a terminal with --use-filedir-conf. Check the current mpv manual for the supported naming and search behavior of local and file-specific configuration files. Do not infer naming rules from another media player.

If the local test setting takes effect only when --use-filedir-conf is present, nothing is malfunctioning. You have confirmed that the default security-conscious discovery behavior caused the original expectation mismatch. You can then decide whether an explicit trusted launcher or a path-based profile is safer.

2.3 Prefer profiles selected by path

For a permanent library under your control, path-based profiles are often clearer than allowing every media directory to supply configuration. Keep the settings in your trusted main mpv.conf, define a named profile, and apply it conditionally according to mpv's path property or select it explicitly with --profile=NAME.

This approach is useful for an HDR folder, an anime library needing specific subtitle behavior, a network-mounted archive, or a high-bitrate test collection. The configuration remains centralized and reviewable. Path matching must account for the actual path mpv receives, including slash direction, case behavior, mounted paths, and URLs.

Before writing a complicated condition, define a simple named profile with one visible option and launch it explicitly. Use mpv --profile=library-test "file.mkv". If that works, inspect the profile with --show-profile=library-test, then add the path condition. Success means the profile activates only for the intended media. Once that happens, stop enabling broader local-config loading.

3. Check the Exact Setting That Appears to Be Ignored

A loaded config can still appear ineffective when the option is invalid, overridden later, unavailable for the current file, or stored in the wrong file. Test the smallest option directly before blaming directory discovery.

3.1 Separate mpv.conf, input.conf, scripts, and shaders

• Put player options such as hwdec, subtitle preferences, output settings, and profiles in mpv.conf.
• Put key bindings in input.conf, using input-command syntax rather than command-line option syntax.
• Put supported scripts in the appropriate scripts directory, not as lines inside mpv.conf.
• Reference shader files with valid paths and verify that the selected video output supports the intended processing.

An input binding failing while ordinary options load is an input.conf or binding issue, not proof that the entire directory config failed. Likewise, a script can fail during initialization even though mpv found the scripts directory correctly.

3.2 Test subtitle, audio, and video track behavior

Track-selection settings only work when matching tracks exist. Open mpv's track list or use the interactive controls to confirm the available subtitle, audio, and video tracks. Language tags can be absent or inconsistent, and a forced subtitle track may not be labeled as expected.

Test an external subtitle explicitly with --sub-file="path/to/subtitle.srt". If it loads, subtitle rendering works and the remaining issue is autoloading, naming, path discovery, or track preference. For audio and video selection, test a known numeric track temporarily rather than relying immediately on language matching.

Success means the intended track is selected and remains selected when the option is moved into the confirmed main config or profile. Stop changing subtitle fonts, audio backends, or video outputs once selection itself is verified.

3.3 Isolate hardware decoding, HDR, and output settings

Hardware decoding and HDR involve the media codec, GPU driver, mpv build, video output, operating system, display server, and display capabilities. A directory profile may load correctly while its requested hardware path falls back or fails.

First test the file with --no-config. Then add only the relevant hardware-decoding option. Watch terminal output for initialization and fallback messages. If software decoding works but hardware decoding fails, investigate the decoder and driver instead of local config discovery.

For HDR, verify the complete output chain. An HDR file playing does not necessarily mean the display receives the signal or tone mapping you expected. Compare logs and on-screen statistics with and without the profile rather than judging solely by brightness.

3.4 Verify yt-dlp, streams, IPC, and screenshots independently

For web URLs, confirm that the external tool is installed through a trusted source and available to the environment used to launch mpv. A terminal may have a different PATH from a desktop shortcut or graphical frontend. Test the URL from the same launch method that normally fails.

For network streams, check reachability, authentication, protocol support, and quoting. Shell characters inside URLs can be interpreted unless the URL is quoted. For IPC, ensure the socket or named-pipe path is writable and not already held by an incompatible process. For screenshots, verify that the destination exists and is writable, then test an explicit absolute screenshot directory.

If the external tool, stream, IPC endpoint, or screenshot path fails even with an explicit command-line option, directory configuration is not the immediate cause. Fix that dependency first.

4. Check Paths, Permissions, Quoting, and Launcher Behavior

The same mpv executable can behave differently depending on whether it starts from a terminal, desktop shortcut, file association, application bundle, script, or frontend. Each launch path may supply different arguments, environment variables, and working directories.

4.1 Use absolute paths during diagnosis

Relative paths for scripts, shaders, subtitles, logs, screenshots, and external executables can resolve somewhere unexpected. Replace them temporarily with absolute paths. Quote every path containing spaces or shell-sensitive characters.

On Windows, confirm which mpv.exe actually launches. Multiple copies can lead to editing a portable_config folder beside one executable while a file association starts another. On Linux and macOS, use the shell's command-location tool to identify the executable, while remembering that graphical launchers may still use a different binary.

4.2 Inspect wrappers and frontends

A launch script may add --no-config, select a different --config-dir, override an option after your profile, or change the working directory. A frontend may use libmpv rather than invoke the standalone player exactly as your terminal does.

Compare a direct terminal launch with the failing shortcut or wrapper. If direct mpv loads the profile but the wrapper does not, inspect the wrapper's final arguments and environment. Success means both launch methods identify the same executable and config directory, or the difference is intentional and documented.

4.3 Verify read and write permissions

mpv must be able to read configuration files, scripts, shaders, subtitles, and media. Screenshot and log destinations must be writable. Network shares and removable drives can have different permissions or mount options from local storage.

Do not respond by deleting the entire config directory. Instead, check the specific file, its parent directory, ownership, access permissions, and security software events. Copy one test file to a normal local directory if you need to distinguish permissions from media-format limitations.

5. Use Logs and Runtime Information to Prove What Loaded

Terminal output is more reliable than guessing. Launch mpv from a terminal so startup warnings remain visible. Increase detail with --msg-level=all=v when necessary, or narrow the verbosity to a relevant component if the output becomes overwhelming.

5.1 Save a reproducible log

Use --log-file="absolute/path/mpv.log" together with the failing media and the smallest relevant options. Search the log for config paths, unknown options, failed scripts, unavailable decoders, output initialization errors, external tool messages, and file-access failures.

A warning about an unknown option means mpv read a line but could not apply it. That differs from never discovering the file. A script stack trace means script loading occurred but execution failed. A missing shader path indicates path resolution, while a video-output error points to the rendering chain.

5.2 Inspect profiles and playback state

Use --show-profile=NAME to inspect a named profile. During playback, use mpv's statistics overlay to inspect decoding, dropped frames, timing, and other runtime information. Check the track list for the streams mpv actually detected.

These tools answer different questions. Profile output shows what a profile contains. Logs show parsing and initialization. The stats overlay shows runtime behavior. The track list shows available media streams. None should be treated as a substitute for the others.

6. Run a Clean Temporary Test Before Changing Many Options

Create a new empty temporary configuration directory. Add an mpv.conf containing one visible, harmless option. Launch a known-good local file with an explicit --config-dir pointing to that directory.

1. Confirm that the visible option takes effect.
2. Add the profile or setting related to the original symptom.
3. Add required paths using absolute values.
4. Add one script, shader, or external dependency at a time.
5. Retest using the same executable and launch method after every change.

If a newly added line causes the failure, remove only that line and inspect its syntax or dependency. If the minimal temporary config never loads, verify the command's quoting and the selected executable. This controlled test is safer than renaming or deleting your complete configuration.

Success is not merely that the video opens. Success means the test option is visibly active, the log contains no relevant parsing or initialization failure, and the same result repeats under your intended launch method. Once those conditions are met, stop changing unrelated settings.

7. Quick Fix Checklist

• Confirm the file plays with --no-config.
• Test one visible option directly on the command line.
• Remember that arbitrary media-folder configs are not blindly trusted by default.
• Use --config-dir to prove which configuration directory is active.
• Do not confuse portable_config with a casually named config folder.
• Prefer a trusted named profile, optionally selected by path.
• Use local config loading only for directories you trust and control.
• Separate player options, input bindings, scripts, and shaders correctly.
• Use absolute paths while testing scripts, subtitles, shaders, tools, and screenshots.
• Compare terminal launches with wrappers, shortcuts, frontends, and file associations.
• Inspect logs for unknown options, missing files, and unavailable dependencies.
• Change one setting at a time and stop after the failing layer is identified.

8. Frequently Asked Questions

8.1 Why does mpv ignore an mpv.conf beside my video?

mpv does not automatically trust arbitrary media directories in every launch. Local directory configuration must be enabled deliberately using supported behavior such as --use-filedir-conf. This protects users from configuration supplied unexpectedly with downloaded, shared, or network-hosted media.

8.2 Is enabling use-filedir-conf safe?

It is reasonable only when you understand the behavior and trust the relevant directories and their parent paths. For mixed downloads, shared folders, removable media, or network locations, a centralized trusted profile is generally safer and easier to audit.

8.3 How can I test a different config folder without moving my real config?

Create a temporary folder with a minimal mpv.conf, then pass its absolute path through --config-dir. This leaves your existing configuration intact and proves whether mpv can parse and apply the test setting.

8.4 Why does the config work in a terminal but not when I double-click a file?

The file association may launch a different mpv executable, use different arguments, omit your shell environment, or run through a wrapper. Compare executable paths and inspect whether the graphical launch adds --no-config or another --config-dir.

8.5 Can a path-based profile replace directory configs?

Yes. A named profile stored in your trusted main configuration can be applied explicitly or conditionally according to the media path. It offers centralized control without allowing every media directory to introduce its own settings.

8.6 Does no-config disable scripts and input bindings too?

--no-config is intended to suppress normal configuration loading, making it useful for a clean baseline. Features supplied explicitly on the command line may still be tested afterward. Compare the clean run with a minimal explicit config directory to identify exactly which configuration layer changes the result.