mpv Windows Config Path Wrong: How to Fix It

When the mpv Windows config path is wrong, mpv may still launch and play media, but your custom settings appear to be ignored. Key bindings stop working, scripts do not load, shaders disappear, hardware decoding changes, screenshots go somewhere unexpected, or subtitle and audio preferences revert to defaults. The usual causes are a misplaced configuration folder, an unexpected portable installation, an MPV_HOME environment variable, duplicate configuration files, or a shortcut that launches a different mpv executable. The safest approach is to identify the executable and configuration source before editing playback settings.

1. Confirm the symptom with a minimal clean mpv command

Start by separating a configuration-path problem from a media, graphics, audio, network, or external-tool problem. On Windows, use mpv.com rather than mpv.exe for this test. Both normally start the player, but mpv.com keeps a console available so that you can read diagnostic messages.

Open Command Prompt or PowerShell in the folder containing mpv.com, then test a known-good local file:

.\mpv.com --no-config "C:\Media\test.mp4"

In Command Prompt, you can instead use:

mpv.com --no-config "C:\Media\test.mp4"

The --no-config option tells mpv not to load normal configuration files. It is temporary and does not delete or modify anything.

• If the file works with --no-config but fails during an ordinary launch, a configuration option, profile, script, shader, or input binding is probably responsible.
• If the same failure occurs with --no-config, the cause is less likely to be the config path. Check the file, URL, permissions, output driver, hardware decoder, external tools, or operating-system environment.
• If your custom behavior disappears with --no-config, that is expected. It confirms that an ordinary launch had loaded at least some customization.

Success means a known-good local file opens and plays normally in the clean test. Once you establish that the normal configuration is the difference, stop changing unrelated GPU, audio, subtitle, or network settings until you locate the active config directory.

2. Check the Windows configuration locations

The expected per-user Windows location is usually the mpv folder inside the roaming application-data directory. Enter the following directly into File Explorer's address bar:

%APPDATA%\mpv

For a typical account, that expands to a path resembling C:\Users\YourName\AppData\Roaming\mpv. The primary settings file is normally mpv.conf, while input bindings belong in input.conf. Common subdirectories include scripts, script-opts, shaders, and other resources used by specific customizations.

2.1 Verify names and file extensions

Windows may hide known file extensions. A file displayed as mpv.conf could actually be mpv.conf.txt, which mpv will not treat as the intended configuration file. In File Explorer, enable file-name extensions from the View menu and check the complete name.

Also confirm that mpv.conf is a regular text file rather than a directory. Save it as plain text. Rich-text formatting from a word processor is unsuitable.

For a harmless detection test, add a visible option to the suspected mpv.conf:

osd-playing-msg=CONFIG TEST LOADED

Close every running mpv process, launch mpv normally, and play a file. Success means the message appears on screen when playback begins. Remove the test line afterward. If nothing appears, continue checking portable mode, MPV_HOME, duplicate files, and the executable being launched.

2.2 Understand the portable mpv folder layout

mpv supports a portable configuration layout on Windows. Create a directory named exactly portable_config beside the mpv executable. Put mpv.conf, input.conf, and relevant subdirectories inside it:

mpv-folder\
  mpv.exe
  mpv.com
  portable_config\
    mpv.conf
    input.conf
    scripts\
    script-opts\
    shaders\

When this portable configuration directory is used, it becomes the important location for that executable. This is useful for a self-contained installation on a removable drive or in a tools folder, but it can also explain why edits under %APPDATA%\mpv appear to do nothing.

A plain mpv.conf placed directly beside mpv.exe should not be confused with the documented portable_config\mpv.conf layout. If you want portable behavior, use the named directory rather than relying on an adjacent loose file.

Success means changes made inside portable_config affect the matching executable after a complete restart. Stop moving files once the test option is detected consistently.

2.3 Check the MPV_HOME environment variable

The MPV_HOME environment variable can direct mpv to another configuration directory. A variable created months ago, inherited from a launcher, or set by a custom script may make the standard AppData location appear broken.

In Command Prompt, inspect it with:

echo %MPV_HOME%

In PowerShell, use:

$env:MPV_HOME

If the result contains a path, inspect that directory for mpv.conf, input.conf, scripts, and shaders. Remember that environment variables are inherited when a program starts. A terminal, file manager, or launcher that was already open may retain an older value.

For a temporary PowerShell test, remove the variable only from the current process and start mpv from that same window:

Remove-Item Env:MPV_HOME -ErrorAction SilentlyContinue
.\mpv.com "C:\Media\test.mp4"

This does not permanently erase a user or system environment variable. Success means mpv begins reading the expected configuration after the temporary variable is absent. If you permanently change MPV_HOME through Windows settings, restart the launcher or sign out and back in before judging the result.

2.4 Find duplicate executables and configuration files

A common mpv troubleshooting trap is editing the correct file for the wrong copy of mpv. You may have one build in a downloads folder, another on PATH, and a shortcut pointing to a third location.

In Command Prompt, run:

where mpv
where mpv.com

In PowerShell, run:

Get-Command mpv -All
Get-Command mpv.com -All

Check desktop shortcuts, file associations, batch files, terminal aliases, media-library applications, and launchers. Review each shortcut's Target and Start in fields. Search likely directories for mpv.conf, but do not delete duplicates yet. Rename one test file temporarily or add a unique visible test message to determine which copy is active.

Success means the command, shortcut, and file association all launch the intended executable, and you know which configuration directory belongs to it.

3. Check the setting directly related to the mpv player issue

After locating the active configuration, inspect only the option associated with the symptom. A correctly discovered config can still contain an invalid option, an obsolete customization, or a profile that applies only under certain conditions.

3.1 Configuration syntax and profiles

Use one option per line in mpv.conf. Options normally omit the leading command-line double hyphens. For example, the command-line option --hwdec=auto-safe becomes:

hwdec=auto-safe

Profile sections use bracketed names, such as [movie]. Options beneath a profile header apply to that profile until another profile begins. If a setting works globally but not inside a profile, verify that the profile is actually selected.

To inspect a named profile from the terminal, use:

mpv.com --show-profile=movie

Replace movie with the real profile name. This helps reveal inherited or included options. Success means the displayed profile contains the settings you intended and the launch command activates that profile when required.

3.2 Input bindings, scripts, shaders, and screenshots

If playback works but custom keys do not, check input.conf rather than mpv.conf. Test the command from mpv's console or simplify the binding to determine whether the problem is the key name or the command itself.

For scripts, confirm that script files are in the active config's scripts directory. Script-specific settings usually belong in script-opts and must use the filename expected by that script. Read terminal output for load errors instead of repeatedly reinstalling the script.

For shaders, verify that every configured path exists and is quoted when it contains spaces. Relative paths can behave differently depending on how mpv was launched, so an absolute path is useful for diagnosis.

If screenshots are missing, inspect screenshot-directory and screenshot-template. Confirm the destination exists and is writable. A successful test produces a screenshot in the explicitly selected folder and reports no write error.

3.3 Subtitles, tracks, output, and hardware decoding

A config-path problem may look like a subtitle or audio failure when a preferred language or track rule is no longer loading. Use mpv's track list or cycle through tracks interactively. Confirm that the media actually contains the expected subtitle or audio stream and that an external subtitle filename matches the video closely enough for automatic loading.

For black video, HDR problems, stuttering, or hardware-decoding failures, first compare normal playback with --no-config. Then override one option at a time, such as the configured vo, gpu-api, gpu-context, or hwdec. Do not install an unrelated codec pack. mpv's normal playback architecture does not require random third-party codec bundles.

Success means a single override identifies the setting responsible. Stop there, correct or remove that line in the active config, and avoid changing several video options simultaneously.

3.4 yt-dlp, online URLs, and network streams

If local files work but online URLs fail, the config path may be unrelated. Confirm that the URL is supported and reachable, and check whether mpv can find an appropriate yt-dlp executable when one is required. Use a trusted installation source and verify the executable from the same shell that launches mpv.

A proxy, firewall, expired stream URL, authentication requirement, certificate problem, or unsupported site change can also cause failure. Test a direct, lawful media URL when possible. Success means mpv resolves the URL and begins reading media data without an external-tool discovery error.

4. Use terminal output and logs to identify the active cause

Launch mpv.com from a terminal so that startup messages remain visible. For more detail, increase message verbosity and write a log:

mpv.com --msg-level=all=v --log-file="%TEMP%\mpv-test.log" "C:\Media\test.mp4"

PowerShell does not expand %TEMP% in the same way as Command Prompt. In PowerShell, use:

.\mpv.com --msg-level=all=v --log-file="$env:TEMP\mpv-test.log" "C:\Media\test.mp4"

Search the resulting log for terms such as config, script, error, failed, shader, audio, video, or ytdl. Logs can expose unrecognized options, missing scripts, inaccessible paths, and failed external programs. Review logs before sharing them because paths and URLs may contain usernames, tokens, or other private information.

The stats overlay can help diagnose playback performance after configuration loading is fixed. It can show dropped frames, timing, and decoding information, but it does not by itself prove which config directory was loaded. Likewise, the track list is useful for subtitle and audio diagnosis, not for locating mpv.conf.

Success means the log identifies a specific file, option, script, or subsystem instead of leaving you with a general mpv not working symptom.

5. Check Windows paths, permissions, and shell quoting

Configuration files and resource paths must be readable by the account running mpv. Screenshot and cache destinations must also permit writing. Protected directories such as locations under Program Files can create avoidable permission problems for portable configurations that need to write files.

Quote command-line paths containing spaces:

mpv.com --config-dir="C:\Users\Your Name\Desktop\mpv test" "C:\Media Files\clip.mkv"

The --config-dir option is useful for a controlled diagnosis because it tells that invocation to use a specific configuration directory. Create the directory first and place a minimal mpv.conf inside it.

Be careful when moving commands between Command Prompt, PowerShell, batch files, and shortcuts. Each environment has its own quoting and variable-expansion rules. A command that contains %APPDATA% in Command Prompt may need $env:APPDATA in PowerShell.

Also check whether security software has quarantined a script or external tool. Do not disable security protections broadly. Review the alert, verify the file's trusted source, and create a narrow exception only when justified.

6. Run a clean temporary test before changing many options

Create an empty temporary directory, such as C:\Temp\mpv-clean. Add a minimal mpv.conf containing only:

osd-playing-msg=CLEAN CONFIG LOADED

Then run:

mpv.com --config-dir="C:\Temp\mpv-clean" "C:\Media\test.mp4"

If the message appears, mpv can read an explicitly selected configuration directory. Add your settings to this temporary file in small groups. Test core playback options first, followed by profiles, input bindings, shaders, and scripts. Restart mpv after each group.

When the failure returns, examine the most recently added group. This is safer than deleting the existing configuration folder. Keep the original config intact or make a backup copy before editing it.

Success means you can reproduce both the working and failing states by adding or removing a small, known set of lines. At that point, stop testing unrelated options and repair the identified setting.

7. Quick fix checklist

1. Run mpv.com --no-config with a known-good local media file.
2. Open %APPDATA%\mpv and verify that the file is truly named mpv.conf.
3. Look beside the intended executable for a portable_config directory.
4. Check MPV_HOME in the same environment that launches mpv.
5. Use where mpv or Get-Command mpv -All to find duplicate executables.
6. Inspect shortcuts and file associations for a different mpv installation.
7. Add a temporary on-screen test message to the suspected config.
8. Use mpv.com, verbose messages, and a log file to find parsing or loading errors.
9. Test a clean directory with --config-dir.
10. Restore options in small groups and stop once the responsible line is identified.

8. Frequently asked questions

8.1 Where is mpv.conf on Windows?

The usual per-user location is %APPDATA%\mpv\mpv.conf. A portable installation can instead use portable_config\mpv.conf beside mpv.exe. MPV_HOME or an explicit --config-dir can direct mpv elsewhere.

8.2 Can mpv.conf sit directly beside mpv.exe?

For a deliberate portable layout, create portable_config beside the executable and place mpv.conf inside it. Do not assume that a loose config file beside the executable is equivalent to the documented portable layout.

8.3 Why does mpv load settings in a terminal but not from File Explorer?

The terminal and File Explorer may launch different executables or inherit different environment variables. Compare executable paths, MPV_HOME values, shortcuts, and file associations. Restart applications after changing environment variables.

8.4 Why do settings work with one video but not another?

A conditional profile, file-specific option, protocol-specific profile, or script may apply only to certain media. The file may also have different tracks, codecs, HDR metadata, or stream characteristics. Inspect the active profile and compare terminal logs.

8.5 Does --no-config permanently disable my settings?

No. It affects only that mpv invocation. Your files remain unchanged, and normal launches can continue loading them.

8.6 Should I delete the entire mpv config folder?

No. First test with --no-config or an empty directory selected through --config-dir. Back up the existing folder and isolate individual settings. Deleting everything can destroy useful scripts, bindings, profiles, and carefully tuned options without proving the cause.

The key to an mpv Windows config path wrong fix is to establish which executable starts, which environment it inherits, and which configuration directory it reads. Once a visible test option loads from a known location, stop moving files and troubleshoot only the setting connected to the remaining symptom.