mpv Profile Not Applying: How to Fix It

When an mpv profile is not applying, the problem usually falls into one of a few categories: mpv is reading a different configuration file, the profile header or command is incorrect, a later option is overriding the profile, or the profile changes something that the current media or output path cannot use. Conditional profiles add another possibility because their conditions may never become true. The safest way to troubleshoot this symptom is to prove that mpv can find and apply the named profile, test one unmistakable option, and only then investigate subtitles, HDR, hardware decoding, scripts, streams, or other specialized behavior.

1. Confirm the Symptom With a Minimal mpv Command

Start by removing the playlist, script, stream, and advanced video variables from the test. Choose a small local media file that you know mpv can play, then launch it from a terminal using the profile explicitly:

mpv --profile=my-profile test-video.mkv

Replace my-profile with the exact profile name from your configuration. Profile names are case-sensitive in practice, so copy the name instead of retyping it from memory.

1.1 Verify the profile header syntax

A named profile in mpv.conf uses a section header enclosed in square brackets. Options belonging to that profile appear below the header:

[my-profile]
volume=40
osd-level=3

Do not include -- before option names inside mpv.conf. On the command line, the option is written as --profile=my-profile, but inside the configuration file it is simply profile=my-profile if profile application is being configured there.

Watch for small syntax mistakes such as a missing bracket, an unintended space in the name, or options placed under the wrong section. A subsequent profile header begins a new section, so options below it no longer belong to the earlier profile.

1.2 Test one obvious option

Do not begin with a subtle shader, HDR tone-mapping option, subtitle margin, or decoder choice. Use an option whose effect is immediate and easy to recognize. For example:

[profile-probe]
volume=20
osd-level=3

Run:

mpv --profile=profile-probe test-video.mkv

Success means playback starts at approximately 20 percent volume and normal on-screen messages are visible. Stop changing profile syntax at this point because mpv has demonstrated that it can load the profile. Restore the original options and investigate why the specific target option has no visible effect.

If mpv reports that the profile does not exist, the problem is more fundamental. Concentrate on the configuration location, profile spelling, and startup logs before changing video or audio settings.

2. Check the Configuration and Option Directly Related to the Issue

2.1 Confirm which mpv.conf is being loaded

A correct profile in the wrong file behaves exactly like a broken profile. Typical user configuration locations include ~/.config/mpv/mpv.conf on Linux and macOS, and %APPDATA%\mpv\mpv.conf on Windows. Packaging choices and portable installations can alter the effective location.

On Windows, check whether a portable_config directory exists beside mpv.exe. A portable configuration can take precedence over the normal user configuration location. Also verify that the file is really named mpv.conf, not mpv.conf.txt with the final extension hidden by File Explorer.

If you start different mpv builds from a terminal, desktop shortcut, file association, or media library, confirm that all launch methods execute the same binary. Run mpv --version in the terminal and compare the executable path with the shortcut or application being tested.

2.2 Check profile order and later overrides

mpv options can be set in the main configuration, named profiles, command-line arguments, scripts, and runtime commands. When the same property is changed more than once, the later applicable value commonly wins.

Consider this command:

mpv --profile=low-volume --volume=80 video.mkv

If low-volume contains volume=20, the later command-line value of 80 overrides it. Multiple profiles can also conflict:

mpv --profile=laptop --profile=hdr-display video.mkv

If both profiles set vo, gpu-api, hwdec, or another shared option, the later setting can replace an earlier one. Simplify the command to one profile, remove duplicate options, and retest. Success means the expected behavior appears when the competing value is absent. Once identified, decide deliberately which profile or command-line option should have final control.

2.3 Separate profile failure from option failure

If the obvious volume test works, the named profile is applying. The remaining issue concerns a particular option or media path:

• Subtitle options need an active subtitle track and may have no effect on bitmap subtitles.
• Audio channel, delay, or device options require a compatible active audio track and backend.
• Video filters and shaders may depend on the selected video output and GPU context.
• Hardware decoding depends on the codec, pixel format, platform API, and available decoder support.
• HDR behavior depends on the source metadata, video output, display path, operating system, and display capabilities.
• ytdl options matter for supported online URLs, not ordinary local files.
• Screenshot format and directory options only become visible when a screenshot command is triggered.

Use a test file that actually exercises the option. For subtitle styling, select a text subtitle track. For HDR settings, use a known HDR source and inspect the detected video parameters. For hardware decoding, verify the decoder status rather than judging only by visual quality.

2.4 Inspect input bindings and scripts

A profile might be valid at startup but later changed by input.conf, a script, or a user action. An input binding can apply a profile at runtime with an mpv command such as apply-profile, while scripts can set individual properties after file loading.

Temporarily move only the suspected script out of the scripts directory or disable that script using its documented method. Do not delete the entire configuration folder. Check input.conf for bindings that change the same property, toggle filters, cycle tracks, or apply another profile.

Success means the desired value remains stable after the file loads. Stop disabling components once the conflicting script or binding has been isolated.

3. Check Conditional Profiles and Environment Dependencies

3.1 Understand named and conditional profile differences

A normal named profile does nothing until something applies it, such as --profile=name, an apply-profile command, or another relevant configuration mechanism. Merely defining [name] does not activate it.

A conditional profile is designed to apply automatically when its condition evaluates as true. It normally includes a profile-cond expression and may include restoration behavior. Conditional evaluation can depend on properties that are unavailable until a file has loaded. A condition based on video width, protocol, path, codec, or HDR metadata may therefore behave differently from a profile explicitly requested at startup.

To distinguish these cases, manually run the conditional profile by name using --profile=name. If its options work when explicitly applied, the options are valid and the condition is the likely failure. Inspect spelling, property types, quoting, and whether the tested media supplies the expected property.

Success means the profile works manually and then activates automatically after the condition is corrected. Stop modifying the profile's playback options once manual application has proved they work.

3.2 Check paths, quoting, and permissions

Profiles often reference shaders, scripts, subtitle files, screenshot directories, cookies, or external executables. A profile can apply while one path-dependent option fails.

• Quote shell paths containing spaces according to the rules of PowerShell, Command Prompt, Bash, or Zsh.
• Inside mpv.conf, use mpv's configuration syntax rather than copying shell escape characters blindly.
• Confirm that the current user can read shader and script files.
• Confirm that screenshot and cache destinations exist and are writable.
• Use absolute paths temporarily to rule out an unexpected working directory.
• For external tools such as yt-dlp, verify that the intended executable is installed and discoverable through the environment used to launch mpv.

A terminal may have a different PATH from a desktop launcher. If online playback works in a terminal but not through a graphical shortcut, compare their environments before rewriting the profile.

3.3 Check platform-dependent playback options

Some options are accepted but cannot produce the intended result with the selected output stack. A hardware-decoding profile may require a platform-specific API. A shader profile needs a compatible GPU video output. Audio device names vary between Windows, Linux, and macOS. Linux behavior can also differ between Wayland and X11 sessions.

Test the underlying feature outside the profile. For example, try a hardware-decoding option directly:

mpv --no-config --hwdec=auto test-video.mkv

If the direct option fails, the named profile is not the cause. Examine terminal messages, GPU drivers, codec support, display server, and the media's format. Avoid installing random codec packs because mpv normally relies on its bundled or linked multimedia libraries rather than system-wide consumer codec packs.

4. Use mpv Diagnostics to See What Actually Happened

4.1 Inspect a profile with show-profile

Use mpv's profile inspection option to print a named profile:

mpv --show-profile=my-profile

The output should list the options mpv associates with that profile. If mpv cannot find the profile, check the active configuration directory and exact name. If an expected option is absent, inspect where the profile section ends and whether another header accidentally captured the option.

--show-profile shows the profile definition, but it does not prove that every option will work with a particular file, driver, or output device. It also does not necessarily reveal every later runtime change made by scripts or input commands.

4.2 Increase terminal logging

Launch mpv from a terminal so errors do not disappear when the player closes. Increase relevant logging with --msg-level or save the full output with --log-file:

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

Search the log for the profile name, configuration paths, unknown options, failed file access, shader compilation errors, decoder selection, audio initialization, and script messages. Logs can contain local paths or URL details, so review and redact them before sharing publicly.

4.3 Inspect playback properties and tracks

Use mpv's stats overlay during playback to inspect the active decoder, hardware-decoding status, video output information, frame timing, and other useful properties. The default binding is commonly the i key, although custom input bindings can change it.

For subtitle or audio profiles, inspect the track list and confirm that the intended track is selected. A subtitle profile cannot style a track that is disabled, and options affecting external text subtitles may not change image-based subtitles. Similarly, an audio profile targeting a specific language cannot select a language tag that the file does not contain.

Success means the diagnostic view shows the intended decoder, track, filter, or output state. Once the expected property is visible, stop changing unrelated profile settings.

5. Run a Clean Temporary Test

A clean test is useful, but --no-config disables the configuration that contains your named profile. Running mpv --no-config --profile=my-profile file.mkv will therefore fail unless the profile is supplied explicitly through another configuration source.

Create a temporary file such as profile-test.conf containing only:

[profile-probe]
volume=20
osd-level=3

Then run a test using the temporary file explicitly:

mpv --no-config --include=profile-test.conf --profile=profile-probe test-video.mkv

Use an absolute path to the temporary configuration if mpv cannot find it. This test removes normal scripts, input bindings, and configuration options while preserving the one profile being examined.

If the temporary profile works, the installed mpv binary and basic profile mechanism are functioning. Add the real profile's options to the temporary file one at a time. When the failure returns, the most recently added option or its environmental dependency is the leading suspect.

If the temporary profile does not work, inspect the terminal output for an unsupported option, unreadable include file, misspelled profile, or command-line quoting issue. Do not make broad changes until the minimal test succeeds.

6. Quick Fix Checklist

1. Confirm the profile header is exactly [profile-name].
2. Apply it explicitly with --profile=profile-name.
3. Use --show-profile=profile-name to confirm mpv can find it.
4. Add one obvious test option, such as volume=20.
5. Verify that mpv is reading the intended mpv.conf.
6. Remove later command-line options and additional profiles that override the same setting.
7. Check scripts and input bindings that modify the property after startup.
8. For conditional profiles, prove the profile manually before debugging profile-cond.
9. Test with a suitable local file and the correct subtitle, audio, or video track.
10. Read terminal output and create a log before changing drivers or external tools.
11. Run a minimal --no-config test with a separately included temporary profile.
12. Stop when the expected property is visible or the obvious test option takes effect.

7. Frequently Asked Questions

7.1 Why does mpv say my profile does not exist?

The usual causes are an incorrect profile name, malformed header, wrong configuration directory, hidden .txt extension on Windows, or a different mpv executable loading another configuration. Run mpv --show-profile=name from a terminal and inspect startup logging for configuration paths.

7.2 Does defining a profile in mpv.conf enable it automatically?

No. A standard named profile must be applied explicitly, such as with --profile=name or an appropriate runtime command. Conditional profiles are different because they can activate when their profile-cond expression becomes true.

7.3 Can one profile override another?

Yes. If multiple profiles or command-line arguments set the same option, a later applicable value can replace an earlier one. Test one profile by itself, then restore other profiles in order while watching the affected property.

7.4 Why does show-profile list the right options but playback does not change?

This proves that mpv found the profile definition, not that the media and output environment support every option. A later option, script, unsupported track type, unavailable hardware decoder, incompatible output driver, or missing external file can prevent the expected result.

7.5 Why does my conditional profile work with --profile but not automatically?

The profile's options are probably valid, but its condition is false, mistyped, evaluated before a required property is available, or comparing an unexpected value. Log the relevant properties and simplify the condition until it matches a known test file.

7.6 Should I reinstall mpv or delete the configuration folder?

Not initially. First prove the issue with --show-profile, terminal logging, and a temporary minimal configuration. These checks are faster and preserve scripts, bindings, and carefully tuned settings. Reinstallation is only reasonable after confirming that the same minimal command fails with a trusted build while the configuration and environment are known to be valid.