mpv Keybindings Not Working: How to Fix It

When mpv keybindings are not working, the cause is usually not video decoding itself. The mpv window may lack keyboard focus, the active keyboard layout may produce a different key name, a frontend may intercept the shortcut, or a later entry in input.conf may replace an earlier binding. Profiles, Lua scripts, JavaScript scripts, and launch options can also disable or override input behavior. The safest approach is to prove that a basic shortcut works in a clean mpv session, identify the exact key name mpv receives, and then restore custom settings one layer at a time. Stop troubleshooting as soon as the expected action works consistently in your normal launch method.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a local media file that mpv can already play. A short, ordinary video or audio file is better than an HDR title, network stream, playlist, or online URL because it removes unrelated variables. Open a terminal and run mpv without loading your normal configuration.

1.1 Launch mpv without user configuration

On Linux or macOS, run:

mpv --no-config /path/to/test-video.mkv

On Windows Command Prompt, run:

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

On PowerShell, use the call operator when invoking an executable through a quoted path:

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

Click inside the mpv window and test standard bindings such as Space for pause, the Left and Right arrow keys for seeking, and f for fullscreen. Success means the on-screen state changes immediately and repeatedly when the relevant key is pressed. If these controls work with --no-config, mpv input is functioning and the problem is probably in your configuration, profiles, scripts, or frontend. Stop changing operating system and GPU settings at this point.

If no standard key works, confirm that you are testing the actual mpv window rather than a terminal, playlist panel, browser, or graphical frontend control. If only one shortcut fails, treat it as a binding-specific problem instead of resetting unrelated playback options.

1.2 Test one simple custom binding

Create a small temporary input file containing one unambiguous binding:

F8 show-text "KEY TEST WORKED"

Save it as a separate file, such as test-input.conf, and launch mpv with that file explicitly:

mpv --no-config --input-conf=/path/to/test-input.conf /path/to/test-video.mkv

Press F8 while the mpv window is focused. Success is the appearance of KEY TEST WORKED in the player. This proves that mpv can receive the key, read an input configuration file, parse the command, and display the result. If it works, stop investigating codecs, hardware decoding, HDR, and media compatibility. Those systems are not preventing general keyboard input.

2. Check the Settings Directly Related to the Failed Binding

Once clean input works, inspect the binding and the command it is supposed to trigger. A key can be recognized correctly while its associated action does nothing because the command is invalid, unavailable in the current playback state, or dependent on a missing track or external tool.

2.1 Verify the active input.conf file

mpv normally reads input.conf from its user configuration directory. Common locations include ~/.config/mpv/input.conf on Linux, ~/.config/mpv/input.conf on macOS unless another config directory is selected, and an mpv configuration directory under the Windows user profile. Portable builds may use a configuration directory beside the executable. Because packaging and launch options can change the effective location, terminal output is more reliable than assumptions.

Check the following:

• The filename is exactly input.conf, not input.conf.txt.
• The file is plain text and readable by the account running mpv.
• The key name is separated from the command by whitespace.
• The line is not commented out with #.
• A duplicate binding later in the file is not replacing the intended command.
• A launch option such as --input-conf=... is not selecting another file.
• The binding uses an mpv input command, not a shell command written without the required mpv syntax.

Temporarily comment out duplicate definitions and retry. Success means the intended command runs every time the key is pressed. Once that happens, stop reorganizing the rest of the file.

2.2 Identify the exact key name with input testing

Key labels printed on a keyboard do not always match the names received by mpv. Keyboard layouts, function-key modes, dead keys, AltGr, media keys, and display-server translation can alter the event. Launch a temporary test with:

mpv --no-config --input-test /path/to/test-video.mkv

Run it from a visible terminal so you can inspect reported input events. Press the failing key and note the key name mpv reports. Use that recognized name in input.conf. Pay special attention to uppercase letters, combinations using Shift or Ctrl, keypad keys, punctuation, and non-US layouts.

If no event appears, mpv never received that key. Focus, the desktop environment, a global shortcut, a frontend, accessibility software, or keyboard-remapping software is the likely cause. If the expected event appears, the keyboard and operating system input path are working, so move back to the binding command or an override.

2.3 Check whether the command has something to act on

Some shortcuts only produce a visible result under specific conditions. Subtitle controls need an available subtitle track or external subtitle file. Audio-track cycling needs multiple audio tracks. Video-track controls need a suitable video track. Screenshot commands need a writable output location. Playlist navigation needs another playlist entry. Chapter controls need chapter metadata. Online-video commands may depend on yt-dlp and network access.

For example, a subtitle visibility binding can be valid but appear ineffective when no subtitle track is selected. An audio-cycle binding may do nothing noticeable when the file contains only one audio track. Before rewriting the key, inspect the track list and playback state.

2.4 Separate input failures from playback-option failures

Options involving hwdec, HDR tone mapping, shaders, video output, audio output, subtitle styling, or stream handling generally do not disable keyboard input. They can, however, make the action behind a key appear ineffective. A shader-toggle command cannot load a missing shader file. A screenshot command can fail when its destination is invalid. A script command cannot work if its script failed to load.

Test the same key with show-text "TEST". If the message appears, the keybinding system works. Troubleshoot the original command, file path, track, script, or playback feature instead of treating the symptom as a general mpv player issue.

3. Find Frontend, Script, Profile, and Operating System Conflicts

3.1 Check window focus and frontend interception

Graphical frontends often embed mpv and add their own menus, text fields, playlist views, and global shortcuts. The frontend may consume a key before libmpv receives it. Click directly in the video area, close search or playlist fields, and test again. Then launch the standalone mpv executable with the same file.

If the shortcut works in standalone mpv but not in the frontend, configure the shortcut in the frontend or disable its conflicting action. Changing standalone input.conf repeatedly will not help when the frontend never forwards the event. Success means the key works when the intended video surface has focus.

3.2 Disable scripts temporarily without deleting them

Scripts can add bindings, replace existing bindings, react to key events, or define forced bindings that take priority. Move scripts temporarily to a clearly named backup directory outside the active scripts directory, or launch a clean test with --no-config. Do not delete the entire configuration folder.

If clean mpv works, restore scripts in small groups. Restart mpv after each change because scripts are loaded at startup. When the failure returns, inspect the last restored script and its documentation for configurable keys. Success means both the script and your desired binding operate without collision. Stop once the conflicting script or binding is identified.

3.3 Inspect profiles and launch arguments

A profile in mpv.conf can activate according to file type, protocol, resolution, or another condition. This explains why a shortcut may work for local files but fail for online URLs or only fail with particular media. Launch scripts, desktop shortcuts, file associations, and frontend settings may also append options that differ from your terminal test.

Use --show-profile=PROFILE_NAME to inspect a named profile. Review conditional profiles and compare the exact command used by your desktop launcher with the command that succeeds in a terminal. Look especially for alternate input files, script options, idle behavior, terminal settings, and IPC-related launch arguments.

3.4 Check operating system shortcut ownership

Window managers and desktop environments can reserve combinations for workspace switching, screenshots, accessibility, media control, or application launching. macOS may reserve Command-based combinations, while Linux desktop environments can capture Super, Alt, or multimedia keys. Windows utilities, keyboard vendors, overlay applications, and game tools can install global hotkeys.

Bind the same mpv action to a plain function key as a control test. If F8 works but the original combination does not generate an mpv input event, change or disable the conflicting system shortcut. There is no need to alter mpv decoding or reinstall the player.

3.5 Validate paths, permissions, and external tools

If the key triggers a screenshot, script, external command, shader, subtitle file, or online action, verify every referenced path. Relative paths may resolve differently when mpv starts from a desktop shortcut. Quote paths containing spaces according to mpv command syntax, and avoid copying shell-specific quoting into input.conf without checking it.

For online URLs, confirm that the same URL opens from a direct terminal command. If yt-dlp is required, use a trusted installation source and verify that mpv can locate it. A failed online extraction is not a keyboard failure if the binding itself is being recognized. Similarly, network authentication, expired URLs, unsupported DRM, or server restrictions cannot be fixed by remapping a key.

4. Use mpv Diagnostics to See What Actually Happens

4.1 Increase message detail and save a log

Launch mpv from a terminal and raise input-related logging:

mpv --msg-level=input=trace --log-file=mpv-key-test.log /path/to/test-video.mkv

Reproduce the problem once, close mpv, and search the log for the key, the input command, script errors, profile loading, and configuration paths. Avoid publishing an unreviewed log because it may contain local filenames, URLs, usernames, or tokens.

If the log records the key and command, input delivery succeeded. Focus on the command's error or required playback state. If it records no key event, focus on window focus, keyboard layout, frontend interception, or operating system hotkeys.

4.2 Inspect tracks and playback state

Use mpv's track list or on-screen controls to verify that the media contains the subtitle, audio, or video track targeted by the shortcut. The stats overlay can help confirm playback characteristics and active decoding information, although it is not primarily a keybinding debugger. If the stats key itself fails in normal mode but works with --no-config, a binding override is likely.

For screenshot failures, read terminal output immediately after pressing the shortcut. For script-defined commands, look for script initialization errors. For hardware-decoding or shader toggles, verify that the selected output driver and GPU support the requested operation. A recognized key followed by a specific error is useful progress because it identifies the real subsystem.

5. Run a Clean Temporary Test Before Changing Multiple Options

A controlled test prevents several simultaneous edits from hiding the root cause. Keep your existing configuration intact and use a temporary directory containing only a minimal input.conf. Alternatively, combine --no-config with an explicit temporary input file.

1. Choose a known-good local media file.
2. Launch standalone mpv from a terminal with --no-config.
3. Confirm Space, arrow keys, and fullscreen work.
4. Load a one-line input file using the F8 test binding.
5. Replace the test message with the actual command you want.
6. Add your normal mpv.conf options back in small groups.
7. Restore profiles and scripts one at a time.
8. Test the normal frontend or desktop shortcut last.

After each step, success means the same key reliably triggers the expected visible action. When a step reintroduces the failure, stop adding settings. The most recently restored component is the leading suspect. This method is faster and safer than reinstalling mpv, adding codec packs, or deleting all configuration data.

6. Quick Fix Checklist

• Click the mpv video window and close any focused frontend text field.
• Test standard shortcuts with mpv --no-config.
• Use --input-test to learn the key name mpv receives.
• Try F8 show-text "KEY TEST WORKED" in a temporary input file.
• Check for duplicate or later bindings in input.conf.
• Confirm mpv is loading the configuration directory you edited.
• Test standalone mpv to detect frontend key interception.
• Temporarily remove scripts from the active script path without deleting them.
• Inspect conditional profiles and desktop-launcher arguments.
• Confirm the media contains the required subtitle, audio, video, chapter, or playlist item.
• Verify screenshot and external-file destinations are writable and correctly quoted.
• Capture a focused log with --msg-level=input=trace and --log-file.

7. Frequently Asked Questions

7.1 Why do mpv shortcuts work with --no-config but not normally?

This result strongly indicates a configuration-layer conflict. The likely causes are a duplicate input.conf entry, a different input file selected at launch, a conditional profile, or a script that overrides the key. Restore configuration components gradually and stop when the failure returns.

7.2 Why does mpv recognize the key but perform no action?

The command may be invalid or have nothing to control. Check for an available subtitle or audio track, another playlist entry, a valid screenshot directory, a loaded script, or an accessible external file. Replace the action temporarily with show-text "TEST". If that message appears, the binding works and the action requires troubleshooting.

7.3 Why do keybindings fail only in a graphical frontend?

The frontend may capture shortcuts for its own interface or may not forward every keyboard event to libmpv. Test the standalone player. If it works there, adjust the frontend's shortcut settings or focus behavior rather than repeatedly editing mpv's input file.

7.4 Can scripts override input.conf bindings?

Yes. Scripts can register ordinary or forced keybindings, and collisions may depend on script load order or state. Temporarily test without scripts, then restore them individually. Rename one of the conflicting bindings according to the script's documented configuration options.

7.5 Do GPU drivers, hardware decoding, or HDR cause broken keybindings?

They rarely stop keyboard events globally. They can cause the command attached to a key to fail, particularly for shader, screenshot, video-output, or decoding-related actions. If a simple on-screen test message works on the same key, input is healthy and the video-output feature should be diagnosed separately.

7.6 Should I reinstall mpv or delete its configuration folder?

Not initially. A clean --no-config test provides the same diagnostic separation without destroying settings. Reinstallation also may not remove a conflicting user configuration. Preserve your files, identify the responsible binding, script, profile, or frontend, and change only that component.