How mpv config Files, Profiles, and Precedence Work

Start with the platform directory. mpv normally reads mpv.conf and input.conf from a user configuration directory, although portable mode and an explicit --config-dir can redirect that search before playback begins.

On Linux and other Unix-like systems, the usual directory is ~/.config/mpv/, or $XDG_CONFIG_HOME/mpv/ when that environment variable is set. The main file is therefore commonly ~/.config/mpv/mpv.conf.

Windows has two common arrangements. An installed build can use %APPDATA%\mpv\mpv.conf, while a portable setup uses a folder named portable_config beside mpv.exe. That portable directory takes priority over the normal user location, which is useful for a USB installation but confusing when edits under AppData appear to do nothing.

macOS ordinarily uses ~/.config/mpv/ as well. Package managers may supply system-wide defaults elsewhere, but personal configurations belong in the user directory unless an administrator deliberately wants settings shared across accounts. The configuration file locations↗ are documented with the other files mpv reads.

Keep their jobs separate. Put playback options in mpv.conf, then put key bindings and mouse actions in input.conf, because the two files use different parsers and are not interchangeable.

An mpv.conf line generally contains the long option without its leading --. For example, the command-line option --fullscreen becomes fullscreen=yes, while --sub-auto=fuzzy becomes sub-auto=fuzzy.

An input.conf line starts with a key or input event and follows it with a command. This binding toggles fullscreen mode:

Comments begin with #. Blank lines are harmless, but copied “best quality” configurations often are not: interpolation, HDR content conversion, hardware decoding, subtitle types and video output options all depend on the codecs, display, GPU driver and mpv build actually available.

Later settings usually win. mpv reads configuration files and command-line arguments in an established order, so a later scalar option can replace an earlier default, while list-like options may append or remove entries instead.

The ordinary decision rule is simple: user configuration establishes the baseline, a selected profile changes that baseline, and options written later on the command line normally override both. Do not treat this as a universal merge algorithm, because options such as script lists and playlist entries have operations specifically designed to add, prepend or remove values.

Per-file configuration is the trap. If enabled, a file-specific configuration can be loaded for the currently playing file and applied late enough to defeat an option that looked final on the command line; directory-specific settings can similarly change behavior as playback moves between folders. The option precedence and per-file details↗ explain why a movie can behave differently from every other file in the same media player.

For debugging, inspect the entire launch command as well as the files. Desktop shortcuts, file associations and front ends can pass options directly without displaying them in the visible settings panel.

Profiles are named option bundles. A profile section in mpv.conf remains inactive until --profile=name, another profile, or an automatic profile mechanism applies it, letting one installation carry several configurations without duplicating the whole file.

Launch the first profile with mpv --profile=low-latency file.mkv. Profiles can include other profiles, but nesting makes precedence harder to read because the included options are applied at the point where the profile is expanded.

Order still matters. If interpolation=no appears after --profile=cinema, the explicit option wins; if the profile is selected later, its interpolation=yes wins instead. The profile syntax and automatic profiles↗ also cover conditional profiles, which evaluate properties such as file type or display characteristics and can automatically load settings when their conditions match.

Use profiles for meaningful modes, not every tiny preference. A laptop profile that limits performance costs and a projector profile that handles fullscreen output are understandable six months later; twelve profiles named test2-final-new are merely configuration debt.

Give scripts their own namespace. Place a Lua script in the scripts directory and its persistent options in script-opts/script-name.conf, rather than scattering script-specific settings through the main configuration.

A typical user tree looks like this:

The exact option names come from the script, not from mpv itself. A copied script-opts file therefore has no guaranteed compatibility with a different fork or version, even when both scripts advertise similar functionality such as change notification, subtitle handling or automatic playlist construction.

Scripts can also register key bindings that collide with input.conf. When a key stops performing its expected command, launch without user scripts first, then restore them one at a time; editing the binding repeatedly will not fix a Lua script that claims the same key later.

Remove variables first. Run mpv with --no-config to ignore normal configuration files, then add one option or profile at a time until the failure, dropped frames or altered video playback returns.

Use a terminal so the diagnostic output remains visible. This command starts from mpv defaults while increasing log detail enough to expose unavailable options, script errors and selected codecs:

If the file plays correctly, test the normal configuration without scripts, or temporarily move the scripts directory aside. Next restore mpv.conf, input.conf and each Lua script separately. This takes longer than pasting another high-quality preset, but it identifies the component responsible instead of changing five interacting settings at once.

For an isolated experiment, point mpv at a temporary directory:

Keep the original directory untouched. The documented configuration control options↗ include --no-config and --config-dir, making them safer than deleting a working setup or downloading an unknown replacement file.

Usually, no. Treat a public repository as annotated examples rather than a finished configuration, because its options may target another operating system, GPU, display, mpv version or collection of third-party scripts.

A repository described as “just my personal config files for use in mpv” means exactly that, even when search results present it as the best configuration mpv can run. Read every line before copying it. Obsolete option names may produce errors, aggressive hardware decoding can reduce compatibility, and expensive interpolation or scaling settings can cause dropped frames without improving a small display.

Build the file from defaults instead. Add the behavior you can name, confirm it works with representative file formats, audio tracks and subtitles, then record why unusual settings exist in a comment. Portable setups become much easier to repair when each non-default line has a purpose.