How to Configure mpv on Linux: Config Files, Key Bindings, and Scripts

mpv themes work best when you start with the files mpv already reads. Put lasting playback choices in mpv.conf, key bindings in input.conf, and optional Lua scripts in the scripts directory, then change one behavior at a time.

Install mpv and confirm the build

Install mpv from your distribution repository before creating a configuration directory. The package provides the player and the default option set that your files extend.

sudo apt update && sudo apt install mpv

On Fedora, use sudo dnf install mpv. On Arch Linux, use sudo pacman -S mpv. Run the same command your distribution documents rather than mixing package-manager instructions.

mpv --version

The version output confirms that the mpv executable is available, while a file that still will not play calls for a check of format support and your distribution’s multimedia packages before you blame the configuration.

Find the files mpv reads

mpv reads user settings from ~/.config/mpv/ on Linux when XDG_CONFIG_HOME is unset. The mpv manual uses option=value syntax in mpv.conf, while command-line options keep their leading double hyphen and override file settings.

Create the directory only once, then edit existing files with a text editor rather than replacing a working configuration wholesale.

mkdir -p ~/.config/mpv/scripts
nano ~/.config/mpv/mpv.conf

Use the original player interface as a baseline and open a familiar file before and after each change so you can identify the setting that changed the result.

mpv exposes much of its behavior through configuration, while Clapper uses mpv as its playback backend and Haruna adds a feature-rich mpv frontend if you prefer a desktop-style interface.

Start with a small mpv.conf

Start with settings that have a visible purpose, such as keeping the on-screen controller visible while paused and remembering playback position when you close a file normally.

# ~/.config/mpv/mpv.conf
osd-bar=yes
save-position-on-quit=yes

save-position-on-quit stores the position when mpv has time to exit. It cannot save a position after an abrupt system shutdown, so treat it as a convenience rather than crash recovery.

The retained interface capture demonstrates a changed controller state rather than a separate install path.

Use the current mpv reference manual for the full option list, and keep a comment above unusual settings so you can remove them cleanly when they no longer suit your playback setup.

Add key bindings in input.conf

input.conf maps an input to an mpv command. Put bindings you can explain in this file, then restart mpv and test them against a short local video.

# ~/.config/mpv/input.conf
# Reset zoom and pan with Alt+r.
Alt+r set video-zoom 0 ; set video-pan-x 0 ; set video-pan-y 0

The three commands run in sequence. The first clears zoom, then the next two return the image to the center, which makes the binding a useful recovery action after manual pan or zoom changes.

The retained capture shows keyboard-driven control through input.conf, which remains mpv’s user binding file.

Inspect existing bindings with ? in mpv before reusing a shortcut, then compare any advanced command with the manual’s input documentation.

Use scripts for a defined job

Lua scripts belong in ~/.config/mpv/scripts/. A script can add a controller, subtitle helper, file browser, or another focused behavior, but it runs with the player, so only install code from a project you can inspect and keep updated.

The retained Git clone capture shows how you can obtain a script project, but read that project’s current installation instructions before copying files because each script can use a different filename, dependency, or configuration key.

A controller script changes the visible playback controls, unlike mpv.conf, which changes options without necessarily replacing the controller.

Use the file browser script when browsing nearby media matters more than a bare player window, then remove it if it conflicts with your preferred bindings.

Pick the next customization

Choose a configuration file for a stable default, input.conf for a repeated shortcut, and a script for a missing feature, while limiting scripts to one job so a broken update is easy to isolate.

1. Use mpv subtitle automation when subtitle discovery or loading is the next task.
2. Use mpv with yt-dlp when you want to open a supported online video in the player.
3. Read the VLC versus mpv comparison if you are deciding whether a configurable player fits your workflow.
4. Check Linux multimedia codec setup when a file opens without the expected audio, subtitles, or video stream.
5. Install VLC on Linux if you decide a fuller graphical player suits the job better.

Save one change, restart mpv, and play a known local file so the configuration stays understandable and a misbehaving option or script is easy to reverse.