mpv Watch History Not Saving: How to Fix It

When mpv watch history is not saving, the failure usually belongs to one of four categories: history recording is disabled, mpv cannot write to its state directory, a custom configuration or script changes the expected behavior, or the history selector is being mistaken for the underlying history database. The fastest solution is to test one known local file with a minimal command, quit mpv cleanly, and then determine whether the problem is recording, storage, or menu presentation. This guide walks through that process on Windows, Linux, and macOS without requiring you to erase your configuration or dismantle a working media setup.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing files, establish exactly what is failing. Watch history, resume positions, recently opened menus, and playlist state can look similar in the interface, but they are not necessarily the same feature. A file can appear in watch history without resuming from its previous timestamp, while a third-party recent-files menu can fail even though mpv wrote the underlying history successfully.

1.1 Check Whether Your mpv Build Recognizes the Option

Open Command Prompt, PowerShell, or a terminal and ask mpv whether it exposes the relevant option. On Linux and macOS, run the following command:

mpv --list-options | grep save-watch-history

In Windows Command Prompt, use:

mpv --list-options | findstr save-watch-history

PowerShell users can run:

mpv --list-options | Select-String save-watch-history

If the option appears, continue with the tests below. If mpv reports that the option is unknown when you try to use it, your installed executable does not support it. Stop changing unrelated settings such as hardware decoding or subtitles. First verify which mpv executable your shell or launcher is actually opening, then obtain an appropriate build through the mpv project’s documented installation channels or your operating system’s package manager.

1.2 Test One Ordinary Local File

Choose a small local media file stored in a writable, uncomplicated location. Avoid a network share, removable drive, online URL, playlist, symbolic link, or path with unusual shell characters for this first test. Launch it with all normal configuration disabled while explicitly enabling history:

mpv --no-config --save-watch-history=yes "/path/to/test-video.mkv"

On Windows, a comparable command is:

mpv.exe --no-config --save-watch-history=yes "C:\Videos\test-video.mkv"

Play the file for a short time, close mpv normally with its quit command, and launch the same test again if needed. A clean quit matters because it gives mpv an orderly opportunity to finalize state. Do not judge the test after terminating the process in Task Manager, sending an uncatchable kill signal, losing power, or crashing the display session.

Success means the item becomes available to the supported watch-history interface or the relevant state data changes after a normal exit. Once that happens, stop changing system permissions or reinstalling software. The clean test proves that mpv itself can record history, so the remaining problem is in the normal launch command, configuration, profile, script, path, or menu layer.

2. Check the Options and Components Directly Related to History

2.1 Enable save-watch-history Deliberately

Open the mpv.conf file used by your normal installation and look for the following setting:

save-watch-history=yes

Add it if the option is supported but absent or disabled. Use mpv configuration syntax without the command-line leading dashes. Search the entire configuration for another occurrence such as save-watch-history=no. When an option is assigned more than once in the active configuration context, a later assignment or active profile can override an earlier value.

Also inspect profiles that apply automatically to local files, protocols, codecs, display modes, or particular filename patterns. A profile designed for private playback may intentionally suppress persistent state. Test after changing only this option, then quit normally. If history begins retaining entries, stop there rather than altering playback options that are unrelated to persistence.

2.2 Distinguish History Recording From the History Selector

The history selector is the interface that displays or lets you choose saved entries. Recording history and presenting it are separate jobs. A selector can be unavailable because its script is missing, disabled, incompatible, or not bound to a key even while mpv is successfully writing history.

Check the documentation for the selector supplied by your installed mpv build or by any third-party script you use. Confirm all of the following:

• The watch-history saving option is enabled.
• The selector script or built-in facility required by your setup is available.
• The command is assigned to a valid input binding.
• No later binding replaces the same key combination.
• The script reads the same state location to which this mpv instance writes.

Review input.conf and script configuration files for history-related commands. If a key does nothing, invoke the documented selector command directly from mpv’s console when possible. Success means the selector opens and shows the entry created by the clean local-file test. If the history data exists but the selector remains empty, troubleshoot the selector rather than repeatedly toggling save-watch-history.

2.3 Look for Private and no-config Launches

A desktop shortcut, file association, shell alias, wrapper script, launcher, or front end may add options you did not type. A launch that intentionally uses private behavior may avoid saving state. A launch with --no-config ignores the save-watch-history=yes line in your normal configuration unless the option is also supplied on that command line.

Compare how mpv behaves when started manually from a terminal and when opened through the failing shortcut. Inspect shortcut targets, aliases, desktop entry Exec lines, file-association commands, and front-end preferences. Success means both launch methods save the same test file after a clean quit. If terminal playback works but the launcher does not, the launcher’s arguments or environment are the boundary of the problem.

2.4 Treat Resume State and Watch History Separately

Do not assume that watch history controls every resume feature. mpv has separate state-saving behavior for playback position, commonly associated with watch-later data and commands that quit while saving the position. A file appearing in history does not guarantee that it will reopen at the previous timestamp. Conversely, successful position resumption does not prove that a watched-file selector has recorded the item.

When diagnosing the issue, state the expected result precisely: “the file should appear in the watch-history selector” is different from “the file should resume at 18 minutes.” This distinction prevents an input binding for a quit-and-save command from being misdiagnosed as a history database failure.

3. Verify State Directories, Paths, and Permissions

3.1 Identify the State Location Used by This Instance

mpv separates configuration, cache, and state concepts, and their platform-specific locations can depend on the build, environment, and launch mode. Use mpv’s path documentation and diagnostic output rather than assuming that every file belongs beside mpv.conf. On Unix-like systems, XDG environment variables can redirect state. On Windows, application-data locations and portable configurations can change where files are read or written.

Check whether the expected state directory exists and whether your user account can create and modify files there. Do not solve this by running mpv permanently as administrator or root. Elevated playback can create root-owned or administrator-owned files that later prevent ordinary launches from updating state.

A safe permission test is to create and remove a harmless text file in the state directory while logged in as the same user that runs mpv. On Linux or macOS, inspect ownership and permissions with ls -ld. On Windows, review the folder’s Security properties and check whether ransomware protection or endpoint security has blocked writes.

Success means the normal user can write to the location and its modification time changes after the clean playback test. Once confirmed, stop broadening permissions. There is no reason to make a state directory writable by every account.

3.2 Check Portable Installations and Moved Folders

Portable mpv setups can keep configuration or state relative to the executable or a designated portable directory. Moving the mpv folder, launching a second copy from another location, or replacing a shortcut can silently switch the active path. The result is often two valid but separate histories.

Search for multiple mpv executables and portable configuration markers. In a terminal, use where mpv on Windows or which -a mpv on Linux and macOS. Compare that result with the executable path in your desktop shortcut or front end. Also consider whether an update tool unpacked a new executable into a different directory while the old shortcut remained active.

Success means every launch method resolves to the intended executable and state location. If entries were merely split between two portable paths, choose one installation and update shortcuts rather than deleting either configuration immediately.

3.3 Rule Out Path and Shell Quoting Problems

Shell metacharacters, quotes, percent signs, ampersands, brackets, and URL query strings can alter what reaches mpv. If history works for test-video.mkv but not for one particular file or stream, print or inspect the exact command used by the wrapper. Quote filesystem paths according to the active shell. PowerShell, Command Prompt, Bash, Zsh, and desktop entry files do not all use identical parsing rules.

Canonicalization can also make two apparently identical entries look different. A file reached through a symbolic link, mapped drive, network mount, or differently cased path may be represented differently from a direct local path. Test the same absolute path twice before concluding that retention failed.

3.4 Consider Read-Only and Ephemeral Environments

Sandboxed packages, containers, temporary home directories, kiosk accounts, and live operating systems may expose a writable-looking location that is isolated or discarded between sessions. Network home directories may also be unavailable at logout. Confirm that the directory persists after closing mpv and signing out or restarting only if that is part of the symptom.

If a sandboxed installation cannot access the intended state location, adjust permissions through that packaging system’s supported controls. Do not work around the restriction with random binaries or globally permissive directories.

4. Use mpv Diagnostics to Find the Exact Failure

4.1 Capture a Focused Log

Run the minimal test with a log file:

mpv --no-config --save-watch-history=yes --log-file=mpv-history.log "/path/to/test-video.mkv"

After quitting normally, search the log for terms such as history, state, config, script, permission, denied, failed, and relevant paths. If ordinary logging lacks enough detail, increase only the useful message categories with --msg-level rather than enabling maximum noise indiscriminately. The exact categories available can be checked in the manual and in mpv’s output.

A useful log answers concrete questions: Was the option recognized? Was a script loaded? Which file failed to open? Was a directory unwritable? Success is a clean run followed by a recorded entry. If the log identifies an access error, fix that path and retest before changing anything else.

4.2 Inspect Profiles and Effective Launch Behavior

Use --show-profile=<name> to inspect a named profile you suspect is involved. Also read terminal output at startup for configuration parsing errors and unknown options. A malformed line earlier in a file, an obsolete script option, or an auto profile can make the effective configuration differ from what you intended.

Temporarily rename only the suspected script or remove only the suspected binding from the test path. Avoid deleting the entire configuration directory. The goal is controlled isolation, not a reset that destroys evidence.

4.3 Know Which Playback Diagnostics Are Relevant

The stats overlay and track list are valuable for video, audio, subtitle, HDR, and performance troubleshooting, but they generally do not prove whether history was written. Use them only when the symptom occurs after a playback failure. For example, an online item that never opens may never reach the same lifecycle as a successfully loaded file.

Hardware decoding, GPU drivers, output drivers, display servers, shaders, HDR settings, audio backends, subtitle styling, and selected audio or video tracks do not ordinarily determine whether a successfully played local file can be added to watch history. If the clean file plays and saves history, leave those settings alone. If mpv crashes during GPU initialization or never loads media, solve that playback failure first because no clean history test has occurred.

4.4 Test Online URLs Separately

Online playback introduces yt-dlp, network access, expiring URLs, redirects, authentication, and extractor behavior. First prove that local-file history works. Then test one stable, authorized URL while capturing a log. Confirm that mpv finds the intended yt-dlp executable and that the media actually begins playback.

A playlist page, resolved media URL, and redirected stream can have different identifiers. A selector may display the original page URL, a title, or another representation depending on the implementation. Network streams that fail before loading should not be used as proof that history storage is broken.

If only online entries fail, investigate URL handling, the external tool path, network access, and selector expectations. Do not install untrusted codec packs, download random executables, bypass DRM, or use unauthorized sources as a troubleshooting step.

5. Run a Clean Temporary Test Before Making Broad Changes

Once you have gathered basic evidence, compare a clean launch with your normal launch using the same local file. Keep the tests small and reproducible.

1. Close every running mpv instance.
2. Choose one local file with a simple absolute path.
3. Launch with --no-config --save-watch-history=yes.
4. Play briefly and quit normally.
5. Verify the history result using the supported selector or state evidence.
6. Repeat with your normal configuration.
7. If the clean test works, enable suspected profiles, scripts, and bindings one group at a time.

If both tests fail, focus on executable support, state paths, and operating system permissions. If only the configured test fails, use a binary-search approach: temporarily disable half of the custom scripts or relevant configuration includes, retest, and narrow the set. Preserve backups and change one logical group at a time.

For IPC-controlled mpv instances, inspect the exact arguments used to start the server and the command sent when closing it. A controller that forcibly terminates mpv does not provide the same clean shutdown as mpv’s own quit command. Success means the IPC-managed instance records history after receiving an orderly quit. At that point, stop modifying unrelated client code.

6. Quick Fix Checklist

• Confirm save-watch-history appears in mpv --list-options.
• Add save-watch-history=yes to the active mpv.conf.
• Search later config lines and profiles for an overriding value.
• Test a simple local file with --no-config --save-watch-history=yes.
• Quit through mpv instead of killing the process.
• Verify that the normal user can write to mpv’s active state directory.
• Check whether portable-mode changes or multiple executables split the history.
• Inspect launcher arguments for private behavior or --no-config.
• Confirm that the history selector and its input binding are available.
• Use --log-file and targeted --msg-level output to expose errors.
• Test online URLs only after local-file history works.
• Leave subtitles, tracks, hwdec, HDR, shaders, and output drivers unchanged unless playback fails.

7. Frequently Asked Questions

7.1 Why Does History Work in a Terminal but Not From My File Manager?

The file association, desktop entry, shortcut, or front end probably launches a different executable or supplies different arguments. Compare executable paths and look for --no-config, a private mode, a portable setup, or another state location. Match the launcher to the successful terminal command and retest after a clean quit.

7.2 Does no-config Disable Watch History?

--no-config prevents mpv from reading your normal configuration, so it will ignore a save-watch-history=yes line stored there. For a clean test, pair it with the explicit command-line option: --no-config --save-watch-history=yes. This isolates mpv from custom files without leaving the desired feature implicit.

7.3 Why Is My Watched-File Menu Empty Even Though History Is Enabled?

The menu may depend on a selector script, a built-in script facility, a valid key binding, or a specific history location. Confirm that recording works first, then examine the menu layer. Check script-loading messages and input conflicts. If another binding uses the same key later in input.conf, invoke the selector through mpv’s console or assign a temporary unused key.

7.4 Can Hardware Decoding or HDR Prevent History Saving?

Not directly in a successful playback session. However, a GPU driver, hardware decoder, shader, display server, or HDR output failure can crash mpv before it exits cleanly. Test with a basic local file and normal shutdown. If that saves history, history storage is healthy and the remaining issue is the crashing playback configuration.

7.5 Why Did My History Disappear After Moving a Portable mpv Folder?

The moved installation may now use a different portable state path, or your shortcut may still point to the old executable. Locate all mpv executables, compare their configuration and state locations, and update launchers to use one intended installation. The old history may still exist in the previous location.

7.6 When Should I Stop Troubleshooting?

Stop as soon as the same test item appears after a normal quit using your everyday launch method. That result confirms that option parsing, storage permissions, the active path, and the selector are working together. Further changes to codecs, audio backends, subtitles, yt-dlp, shaders, or GPU settings would add risk without addressing the solved symptom.