mpv Portable Config Not Loading: How to Fix It

When an mpv portable config is not loading, the player usually still opens media, but ignores the local options, profiles, input bindings, scripts, shaders, or external tools you expected it to use. The most common causes are a misplaced portable_config folder, launching a different mpv.exe, an MPV_HOME override, a frontend that changes the configuration directory, unreadable files, or an error inside the configuration itself. Start by proving which configuration directory mpv is using. Then test one visible option before troubleshooting subtitles, HDR, hardware decoding, yt-dlp, scripts, or other advanced features.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing files, confirm that mpv itself can play a known-good local file without relying on any configuration. This separates a portable-config problem from a media, graphics, audio, or installation problem.

Open Command Prompt or PowerShell in the directory containing the mpv executable and run:

.\mpv.exe --no-config "C:\path\to\test-video.mp4"

On Linux or macOS, use the actual executable path:

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

The --no-config option tells mpv to ignore normal configuration files. If the file plays in this clean test, the executable and media are basically functional. The fault is probably in configuration discovery or in an option loaded from the configuration. If playback still fails, portable configuration is not the immediate cause. Read the terminal output and investigate the reported decoder, output, permission, path, or media error first.

1.1 Verify That You Are Running the Intended Executable

Portable configurations are associated with a particular executable location. A desktop shortcut, file association, terminal command, or frontend may launch another mpv installation.

On Windows, run:

where mpv

In PowerShell, you can also run:

Get-Command mpv | Format-List Source

On Linux or macOS, run:

command -v mpv

Compare the reported location with the directory containing your intended portable files. If several copies appear, launch the desired executable by its full path. Success means the exact executable beside your intended configuration is running. Stop changing configuration options until this location is confirmed.

2. Check the Portable Configuration Location and Files

For a typical portable Windows setup, the folder must be named portable_config and placed directly beside mpv.exe. It must not be inside another configuration folder or beside only a shortcut.

A correct layout looks like this:

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

Check that Windows has not silently created mpv.conf.txt or input.conf.txt. Enable file-name extensions in File Explorer, or inspect the names from a terminal with dir. The files should be plain text, not rich-text documents.

The adjacent portable_config convention is primarily relevant to Windows portable builds. On Linux and macOS, a portable-style deployment is more reliably created with an explicit configuration directory or the MPV_HOME environment variable. For example:

MPV_HOME="/path/to/mpv-config" /path/to/mpv "/path/to/video.mkv"

You can also test an explicit directory with:

mpv --config-dir="/path/to/mpv-config" "/path/to/video.mkv"

Use an absolute path while troubleshooting. Relative paths depend on the current working directory, which may differ when mpv is opened through a shortcut or frontend.

2.1 Check for an MPV_HOME Override

MPV_HOME changes where mpv looks for its user configuration. A value inherited from an old installation, launcher, shell profile, or frontend can redirect mpv away from the directory you are editing.

On Windows Command Prompt, inspect it with:

echo %MPV_HOME%

In PowerShell, use:

$env:MPV_HOME

On Linux or macOS, use:

printf '%s\n' "$MPV_HOME"

If the variable points elsewhere, either place the intended configuration there, update the variable deliberately, or remove the override from the launcher or shell environment. Do not remove an environment variable blindly if another workflow depends on it. Success means mpv consistently reads the directory you intentionally selected.

2.2 Add a Visible Configuration Test

Test configuration discovery with an option whose effect is unmistakable. Add this temporary line to the candidate mpv.conf:

osd-playing-msg=PORTABLE CONFIG LOADED

Launch a local video with the intended executable. If the message appears when playback begins, that mpv.conf is being read. Remove the marker afterward. If it does not appear, do not start debugging HDR, scripts, or hardware decoding yet. The fundamental directory, filename, launcher, or permission problem remains.

To test input.conf separately, add:

F12 show-text "PORTABLE INPUT CONFIG LOADED"

Play a file and press F12. Seeing the message proves that the binding file loaded. This also distinguishes an input.conf issue from an mpv.conf issue.

3. Check the Exact Feature That Appears to Be Ignored

A loaded configuration can still contain an invalid option, an inactive profile, or a later setting that overrides an earlier one. Once the visible marker confirms loading, isolate the feature that produced the original symptom.

3.1 Options, Profiles, and Input Bindings

Configuration-file options normally omit the leading --. A command-line option such as --hwdec=auto-safe is generally written as hwdec=auto-safe in mpv.conf. Check spelling, values, comments, and duplicate entries. Later settings or command-line arguments can take precedence.

If an option is inside a named profile, it does nothing until that profile is activated. Test it explicitly:

mpv --profile=myprofile "C:\path\to\video.mkv"

To inspect a profile definition, use:

mpv --show-profile=myprofile

If mpv reports that the profile does not exist, the expected configuration was not loaded or the profile name differs. If it prints the profile contents, configuration discovery is working and you should examine activation conditions or overriding arguments.

For an input binding, verify the key name, command syntax, keyboard layout, and whether a script or frontend captures the key first. Test a simple show-text binding before diagnosing a complex command.

3.2 Scripts, Shaders, Screenshots, and Paths

Scripts belong in the active configuration directory's scripts subfolder unless they are loaded explicitly. Script-specific settings commonly belong in script-opts. A script may load while its options fail because the option filename does not match what the script expects.

Shader and screenshot paths often fail because relative paths are resolved in an unexpected context. During testing, use a quoted absolute path and confirm that the current user can read the shader or write to the screenshot destination. A path containing spaces must be quoted correctly on the command line. Configuration-file quoting follows mpv's parser rather than every shell's rules, so avoid copying shell-specific escape characters into mpv.conf.

Success means the terminal reports the script or resource loading without an error and the intended behavior appears. Once that happens, stop changing unrelated playback options.

3.3 Subtitles, Tracks, Audio, Video, HDR, and Hardware Decoding

Some symptoms blamed on portable configuration are actually content-dependent. A preferred subtitle language cannot select a language tag that the file does not contain. An audio track preference cannot create a missing track. HDR output depends on the video, selected output driver, operating system, display path, GPU driver, and display capabilities.

Use mpv's track list or on-screen track controls to verify what the file contains. If a subtitle file is external, confirm its filename, extension, encoding, and path. If a forced track ID points to a nonexistent track, remove that forced selection temporarily.

For hardware decoding, compare a clean run with software decoding:

mpv --no-config --hwdec=no "C:\path\to\video.mkv"

Then test the intended hardware-decoding option explicitly. If software playback works but the hardware-decoded test fails, the portable config is not necessarily missing. The issue may involve the selected decoder API, output driver, GPU driver, codec profile, or unsupported media format.

3.4 yt-dlp, Online URLs, Playlists, and Network Streams

Opening online URLs may require an external tool such as yt-dlp. Confirm that the tool is installed from its official project source and can be found by the process launching mpv. A terminal may have a different PATH from a desktop shortcut or frontend.

Test the exact URL from a terminal and read the output. If a local file works but an online URL fails, configuration discovery is probably not the primary problem. Check yt-dlp availability, URL support, authentication requirements, network access, certificates, and whether the stream is still available. Do not use workarounds intended to bypass DRM or access controls.

4. Check Permissions, Launchers, Frontends, and Operating System Differences

mpv must be able to read its configuration files and any referenced scripts, fonts, shaders, subtitle files, or executables. It also needs write access to screenshot, cache, or watch-later destinations when those features are enabled.

On Windows, files extracted under protected locations such as Program Files may be subject to access restrictions. Test from a normal user-owned directory such as a folder under your profile. Check file Properties for an unblock option if the archive came from the internet, but only use software obtained from a trusted source.

On Linux and macOS, inspect ownership and permissions with ls -l. Configuration files generally need read permission, while directories need traversal permission. Avoid solving a user-level configuration issue by running mpv as root or with administrator privileges. Elevated execution creates security risks and can make mpv use a different home environment.

4.1 Launching Through a Frontend

A frontend may bundle its own mpv library, launch a separate executable, pass --no-config, set --config-dir, define environment variables, or append options that override your file. Some applications use libmpv rather than launching the nearby mpv.exe, so placing portable_config beside the frontend may have no effect.

First launch the intended mpv executable directly with the visible OSD marker. If it works directly but not through the frontend, inspect the frontend's executable path, custom arguments, environment settings, and documentation. Success means both launch methods identify the same configuration directory and produce the same marker. Stop editing mpv.conf once direct mpv works because the remaining issue belongs to the frontend's launch configuration.

5. Use Logs and Runtime Information to Find the Override

Terminal output is often the fastest way to solve an mpv player issue. Launch mpv from a terminal instead of double-clicking it so that warnings remain visible.

Create a detailed log with:

mpv --msg-level=all=v --log-file="C:\path\to\mpv-test.log" "C:\path\to\video.mkv"

On Linux or macOS, choose a writable path such as /tmp/mpv-test.log. Search the log for terms such as config, profile, script, error, failed, vo, ao, hwdec, or ytdl. The log may reveal an unknown option, invalid value, missing script dependency, unreadable file, unavailable audio backend, failed video output, or external program lookup failure.

The built-in stats overlay is also useful during playback. It can expose the active decoder, hardware-decoding state, dropped frames, selected tracks, and output information. Use it to verify the result rather than assuming an option took effect merely because playback opened.

Do not publish a log without reviewing it. Logs can contain local usernames, filesystem paths, network URLs, query tokens, or media names.

6. Run a Clean Temporary Test Before Changing Many Options

Do not delete the existing configuration folder. Rename nothing until you have preserved the current setup. Instead, create a new temporary directory containing only a minimal mpv.conf with the visible OSD marker.

Then run:

mpv --config-dir="C:\path\to\mpv-test-config" "C:\path\to\test-video.mp4"

If the marker appears, explicit configuration loading works. Add the suspected option next and retest. After that, introduce profiles, bindings, scripts, shaders, and external paths one category at a time. This controlled approach identifies the first addition that causes the failure.

1. Create a temporary configuration directory.
2. Add only osd-playing-msg=PORTABLE CONFIG LOADED.
3. Launch a known-good local video with --config-dir.
4. Add one relevant option or one small group of related options.
5. Retest and inspect terminal output after each change.
6. Stop when the failure returns, then examine the last addition.

If the minimal explicit directory does not load, verify the path, quoting, permissions, executable identity, and whether the command is being altered by a wrapper. If it does load, the original folder contains either a path-discovery problem or a configuration error.

7. Quick Fix Checklist

• Confirm the running executable with where mpv, Get-Command mpv, or command -v mpv.
• On Windows, place portable_config directly beside the intended mpv.exe.
• Confirm the files are named mpv.conf and input.conf, not hidden .txt files.
• Check whether MPV_HOME redirects configuration loading.
• Use --config-dir with an absolute path for a controlled test.
• Add a temporary visible OSD message to prove that mpv.conf loaded.
• Add an F12 show-text binding to test input.conf.
• Run --no-config to distinguish configuration failure from playback failure.
• Use --show-profile to confirm that a named profile exists.
• Read terminal output or save a verbose log before changing unrelated options.
• Check frontend arguments for --no-config, --config-dir, or overriding options.
• Test scripts, shaders, yt-dlp, screenshots, subtitles, and network URLs separately.
• Use a user-owned directory and verify read or write permissions.
• Stop changing settings as soon as the intended configuration and feature are confirmed.

8. Frequently Asked Questions

8.1 Where Should portable_config Be Located?

For the usual Windows portable arrangement, portable_config should be directly beside the mpv.exe you actually launch. Placing it beside a shortcut, frontend executable, or different mpv installation will not configure the intended process. On Linux and macOS, use the platform's normal configuration location, MPV_HOME, or an explicit --config-dir for a portable-style setup.

8.2 Does MPV_HOME Override portable_config?

MPV_HOME can redirect mpv's user configuration location and should always be checked when the observed directory differs from the expected one. Environment values may also differ between a terminal, desktop shortcut, service, and frontend. An explicit --config-dir test provides the clearest temporary answer.

8.3 Why Does the Config Work in mpv but Not in My Frontend?

The frontend may use libmpv, a different executable, a custom configuration directory, or additional arguments. It may also suppress normal configuration loading. Verify direct mpv behavior first, then inspect the frontend's mpv path and launch settings rather than repeatedly editing a configuration that already works.

8.4 How Can I Prove That mpv.conf Loaded?

Add osd-playing-msg=PORTABLE CONFIG LOADED temporarily and play a local file. If the message appears, the file loaded. For input.conf, bind F12 to a simple show-text command. Remove these markers after verification.

8.5 Why Does Only One Option Fail?

The configuration may be loading correctly while that option is misspelled, unsupported in the selected context, overridden later, restricted to an inactive profile, or dependent on media and system capabilities. Use terminal output, --show-profile, the stats overlay, and an explicit command-line version of the option to isolate it.

8.6 Should I Delete My Existing Configuration?

No. Preserve it and run a separate temporary configuration using --config-dir. A minimal directory is safer and more informative than deleting scripts, profiles, bindings, and carefully tuned settings. Once you identify the failing line or path, change only that item.