mpv Default App Association Not Working: How to Fix It

When the mpv default app association is not working, double-clicking a media file may open another player, display an application chooser, produce an error, or appear to do nothing. The most likely causes are an incorrect operating system association, a Linux desktop entry or MIME mismatch, confusion between mpv.exe and mpv.com, interference from an mpv frontend, or a command that fails to pass the selected file correctly. An mpv configuration problem is less likely if files play when opened directly from a terminal. The steps below separate these failure categories so you can fix the association without unnecessarily resetting your scripts, shaders, profiles, HDR settings, or other customizations.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before changing the operating system default, confirm that mpv itself can open the affected file. This distinction matters: if a direct command works, mpv is operational and the association is the likely problem. If the direct command fails, repair that playback problem first.

1.1 Test the exact file from a terminal

Open Command Prompt, PowerShell, Terminal, or your preferred shell and run mpv with the full path to a local media file. Always quote paths containing spaces.

• Windows with the console executable: "C:\Path\To\mpv.com" "C:\Media\Test Video.mkv"
• Windows with the graphical executable: "C:\Path\To\mpv.exe" "C:\Media\Test Video.mkv"
• Linux: mpv --no-config "/home/user/Videos/Test Video.mkv"
• macOS application bundle: /Applications/mpv.app/Contents/MacOS/mpv --no-config "/Users/user/Movies/Test Video.mkv"

On Windows, PowerShell may require its call operator when an executable path is quoted: & "C:\Path\To\mpv.com" "C:\Media\Test Video.mkv".

Success means the selected file begins playing in mpv. If it does, stop investigating codecs, GPU drivers, subtitles, and network tools. Move directly to the operating system association steps. If neither mpv.com nor mpv.exe opens the file, test another known-good local file before concluding that the association is responsible.

1.2 Compare normal and clean launches

Run the same file once normally and once with --no-config. This temporarily prevents mpv from loading the normal user configuration, scripts, and related customizations.

• mpv "test-file.mkv"
• mpv --no-config "test-file.mkv"

If both commands work but double-clicking fails, the evidence points strongly to the desktop association. If only the clean command works, a configuration or script is affecting startup. Do not delete the entire configuration directory. Narrow the problem down using the later diagnostic steps.

2. Check the Association Command and mpv Target

A file association does more than name a preferred application. It tells the operating system which executable to start and how to supply the selected filename. An old path, missing filename placeholder, malformed quotation mark, or frontend registration can make a valid mpv installation appear broken.

2.1 Understand mpv.com versus mpv.exe on Windows

Some Windows mpv distributions include both mpv.exe and mpv.com. They launch the same player core, but their Windows subsystem behavior differs. mpv.com is useful in Command Prompt or PowerShell because terminal messages remain visible. mpv.exe is generally the more appropriate target for Explorer file associations because it does not create or retain a console window in ordinary graphical use.

For troubleshooting, use mpv.com in a terminal so you can read errors. For the final double-click association, select mpv.exe unless your particular package or workflow documents another arrangement. Success means double-clicking starts mpv without an unwanted terminal window and opens the selected file.

2.2 Check whether a frontend owns the association

Applications built around mpv, such as graphical frontends, may register themselves as handlers for media extensions. Installing, updating, or uninstalling a frontend can leave the operating system pointing at the frontend rather than standalone mpv. Decide which program you actually want to launch.

If you want standalone mpv, select its real executable or application bundle again. If you want a frontend, select the frontend and verify that it passes the filename to its mpv backend. Do not alternate between handlers while testing, because that makes the result difficult to interpret.

2.3 Preserve quoted file paths

A custom Windows association command must quote both the executable path and the file argument. Conceptually, it should resemble "C:\Apps\mpv\mpv.exe" "%1". The %1 placeholder represents the file selected in Explorer. Without quotes, filenames containing spaces can be split into several arguments.

Linux desktop entries typically use a field code such as %F for multiple local files or %U for multiple URLs. A malformed Exec line can launch mpv without passing the media item. Avoid editing system-wide launchers first. If a user-level desktop entry is responsible, correct that copy and refresh the desktop database where required.

3. Repair the Default Application in Your Operating System

3.1 Windows default apps

On current Windows versions, the safest method is to use the supported Default Apps interface rather than importing registry fragments from an unknown source.

1. Open Settings, then find Apps and Default apps.
2. Search for the affected extension, such as .mkv, .mp4, .webm, .flac, or .m3u.
3. Select the current handler and choose mpv. If necessary, browse to the actual mpv.exe.
4. Repeat the process only for file types you want mpv to own.
5. Close Settings and double-click one representative file.

You can also right-click a file, choose Open with, select Choose another app, select mpv, and enable the option to use it for that file type when Windows offers it. Exact labels vary between Windows releases.

Success means the file icon may update and a double-click opens that exact file in mpv. Once this works, stop changing settings. Associations are extension-specific, so a successful .mkv test does not automatically set .mp4 or playlist formats.

If mpv does not appear in the application list, browse to a stable installation path. Associations break when a portable folder is renamed, moved, or deleted. Reassociate affected extensions after moving mpv, and avoid pointing the association at a temporary extraction directory.

3.2 macOS Open With

On macOS, use Finder to set the application for a particular file type.

1. Select a representative media file in Finder.
2. Choose File, then Get Info.
3. Expand Open with and select mpv.
4. Choose Change All if every file of that type should use mpv.
5. Confirm the change, close the information window, and double-click the file.

If mpv is unavailable in the menu, confirm that mpv.app is in a stable location such as /Applications and can be opened directly. Moving or replacing an application bundle can invalidate a previous Launch Services association.

Success means Finder launches the chosen mpv application and passes it the selected file. Stop after confirming the result. Repeat the procedure separately for other extensions only when needed.

3.3 Linux desktop files and MIME associations

Linux desktop environments generally associate MIME types with applications through desktop entries. The executable may work perfectly in a shell while the graphical file manager uses an outdated or incorrect .desktop file.

First identify the file's MIME type:

• xdg-mime query filetype "/home/user/Videos/test.mkv"

Then inspect the current default handler, replacing the example MIME type with the reported value:

• xdg-mime query default video/x-matroska

Find the installed mpv desktop entry. A common name is mpv.desktop, but verify what is actually installed under locations such as /usr/share/applications or ~/.local/share/applications. Set the verified entry as the default:

• xdg-mime default mpv.desktop video/x-matroska

You may also use the file manager's Open With or file properties interface. If a user-level desktop entry overrides the system entry, inspect its Exec line and confirm that it points to the installed mpv binary and includes a suitable field code. Do not blindly create duplicate desktop files.

Success means xdg-mime query default returns the intended desktop entry and the file manager opens the selected file in mpv. Desktop environments can maintain their own caches, so sign out and back in only if the correct setting is visible but the file manager still uses stale information.

4. Check mpv Options Only When Direct Playback Also Fails

File associations operate before most playback options become relevant. A subtitle preference, HDR profile, shader, audio track selection, or hardware decoder cannot normally cause Explorer, Finder, or a Linux file manager to choose the wrong application. Investigate these settings only if mpv launches but closes, remains blank, or fails to play the supplied file.

4.1 Isolate configuration and profile problems

Test with --no-config. If that works, inspect mpv.conf, input.conf, scripts, and profiles incrementally. Temporarily comment out recently added lines rather than deleting the configuration directory.

Pay particular attention to conditional profiles that match a file extension, protocol, display, or filename. Use --show-profile=PROFILE_NAME to print the contents of a named profile. This helps confirm what a profile contains, although it does not by itself prove that every condition matched during startup.

An input.conf binding is unlikely to prevent the initial file from opening, but scripts can run startup commands, modify playlists, or quit on errors. Temporarily move one suspect user script out of the scripts directory, retest, and restore it if nothing changes.

4.2 Distinguish track and output failures

If mpv opens but appears to have no picture or sound, inspect the track list in terminal output or use mpv's interactive track controls. A forced audio, video, or subtitle track ID may not exist in every file. Test without forced track selections.

For a black window, test without custom shaders and with hardware decoding disabled temporarily: mpv --no-config --hwdec=no "test.mkv". If this works, investigate the GPU driver, video output, HDR configuration, or hardware decoder separately. Do not alter file associations again because the operating system has already launched mpv successfully.

For missing sound, test a clean launch and review the selected audio track and backend messages. For subtitle failures, confirm that the video itself opens before examining subtitle paths, encoding, style overrides, or external subtitle permissions.

4.3 Separate local files from URLs and external tools

Default file associations mainly concern local files and registered playlist or URL types. Opening an online video URL can additionally depend on network access and an external tool such as yt-dlp. A local file working on double-click while an online URL fails is not evidence of a broken media-file association.

Likewise, a playlist can reference missing files, relative paths, inaccessible network shares, or unsupported URLs. Test one local file directly before debugging the playlist. Screenshot directory settings are relevant only after playback begins and a screenshot command is used.

5. Use Logs to Identify What the Desktop Actually Launched

When the graphical launch produces no visible error, capture mpv's own diagnostic output. Run the exact file from a terminal with increased logging:

• mpv --no-config --msg-level=all=v "test-file.mkv"
• mpv --no-config --log-file="mpv-test.log" "test-file.mkv"

Use a writable log location if the current directory is protected. Review the beginning and end of the log for the executable version information, loaded configuration files, supplied filename, access errors, and output initialization failures. Logs may expose local usernames, paths, URLs, or network addresses, so remove sensitive information before sharing them.

If terminal playback succeeds but double-clicking creates no log, the desktop handler may not be launching the expected mpv binary. If a log appears and contains the correct filename, the association is doing its job and the failure has moved into mpv startup or playback.

5.1 Use overlays only after a file has opened

The stats overlay and track list are useful for playback diagnostics, including decoder, frame timing, output, and selected-track questions. They cannot diagnose an association that never launches mpv. Use them only when an mpv window opens and the symptom concerns missing video, audio, subtitles, HDR behavior, or performance.

6. Run a Clean Temporary Test Before Changing Multiple Settings

A controlled test prevents unrelated customizations from obscuring the result. Use this sequence:

1. Choose a small, known-good local media file with a simple path.
2. Open it with mpv --no-config from a terminal.
3. If it works, set only that extension's operating system association to the verified mpv executable or desktop entry.
4. Double-click the same file.
5. If successful, repeat with normal configuration enabled.
6. Only then test complex files, external subtitles, HDR media, playlists, network shares, or URLs.

This sequence changes one variable at a time. Success at step four proves that the operating system can launch mpv and pass the local filename. Success at step five proves that the normal configuration does not break startup. Stop at the first stable result instead of applying speculative fixes.

7. Quick Fix Checklist

• Confirm the exact file opens from a terminal with a quoted path.
• Repeat the test with --no-config.
• On Windows, troubleshoot with mpv.com but associate files with mpv.exe.
• Use Windows Default Apps for each required extension.
• Use Finder's Get Info, Open with, and Change All on macOS.
• On Linux, query the MIME type and verify the selected .desktop entry.
• Check that mpv was not moved after the association was created.
• Check whether an mpv frontend replaced the standalone player association.
• Verify that custom commands quote filenames and include the required placeholder.
• Use a log only if mpv launches and then fails or closes.
• Do not reset scripts, shaders, or the entire config folder when direct playback works.

8. Frequently Asked Questions

8.1 Why does mpv work in a terminal but not when I double-click a file?

The operating system is probably using the wrong handler, an outdated executable path, or a malformed desktop command. Repair the association for that extension or MIME type. Because direct playback works, changing decoders or installing codec packs is unnecessary.

8.2 Should Windows file associations use mpv.com or mpv.exe?

Use mpv.com during terminal troubleshooting because it exposes console output. For normal Explorer double-click behavior, mpv.exe is usually the appropriate graphical target. Both must come from the trusted mpv installation you already use.

8.3 Why does one media type open in mpv while another opens elsewhere?

Associations are commonly stored per extension or MIME type. Setting mpv for .mkv does not necessarily set it for .mp4, .webm, audio files, subtitles, or playlists. Configure only the types you intend mpv to handle.

8.4 Can mpv.conf cause a default app association failure?

It cannot normally make the operating system choose another application. However, a bad option, profile, or script can make mpv close after it has been launched. Compare normal playback with --no-config to distinguish these cases.

8.5 Why did the association break after updating or moving mpv?

Portable installations are often associated by their full executable path. Moving, renaming, or replacing that folder can leave the operating system pointing to a path that no longer exists. Select the executable or application bundle in its new stable location.

8.6 Does a yt-dlp or network-stream error mean the file association is broken?

Not if local files open correctly. Online URLs and network streams add external-tool, protocol, authentication, certificate, firewall, and connectivity requirements. Confirm local double-click playback first, then troubleshoot the URL or external tool as a separate issue.