mpv Screensaver Not Disabled: How to Fix It

If the screensaver starts, the display blanks, or the computer begins an idle power transition while mpv is playing, mpv's normal screensaver inhibition has failed somewhere between the player, video output, desktop environment, compositor, and operating system. The most common causes are a disabled stop-screensaver option, an overriding profile or script, audio-only playback, unsupported desktop inhibition, or a Wayland compositor that does not honor the mechanism mpv uses. Start with a short clean test, identify which layer is responsible, and stop troubleshooting as soon as continuous playback keeps the display awake.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing configuration files, verify that the problem occurs without your normal mpv configuration. This separates an mpv or operating-system integration problem from a setting, profile, script, shader, or input binding you added.

1.1 Run a short no-config test

Choose a local video that plays reliably and is long enough to exceed your screensaver timeout. If possible, temporarily set the operating system's screensaver or display-blanking timeout to one or two minutes. This produces an answer quickly without waiting through a long movie.

On Linux or macOS, open a terminal and run:

mpv --no-config --stop-screensaver=yes "/path/to/test-video.mkv"

In Windows PowerShell, run a command such as:

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

Keep the video actively playing. Do not pause it, minimize it, switch to audio-only mode, or close the video window during this test. A paused player may not be treated as active playback by every inhibition implementation.

Success means the screensaver and automatic display sleep do not activate after their normal idle timeout. If that happens, stop investigating the operating system for now. Your regular configuration, a profile, an input binding, or a script is the likely cause.

1.2 Distinguish display sleep from system suspend

Screen blanking, a graphical screensaver, monitor power-off, lock-screen activation, and full system suspend are related but distinct behaviors. mpv's stop-screensaver feature is intended to inhibit screensavers and display power management during playback. It is not a universal promise that every operating system will block every suspend policy.

• If only the image disappears but audio continues, investigate screensaver and display power management.
• If the entire computer suspends, inspect the operating system's sleep policy and idle inhibitor support.
• If the video turns black while the mpv window remains visible, investigate decoding, HDR, shaders, or video output instead.
• If playback itself stops or buffers, investigate the file, stream, network, or external downloader rather than screensaver inhibition.

This distinction prevents an unrelated mpv player issue from being mistaken for failed idle inhibition.

2. Check the mpv Option and Configuration Overrides

mpv normally attempts to stop the screensaver during video playback. The relevant option is stop-screensaver. An explicit negative setting, a profile, or a runtime command can reverse that behavior.

2.1 Inspect mpv.conf

Open the mpv.conf file used by your installation. Common locations include ~/.config/mpv/mpv.conf on Linux, a portable portable_config directory beside mpv on Windows, and the applicable mpv configuration directory on macOS.

Search for these forms:

stop-screensaver=no

no-stop-screensaver

Remove or comment out the disabling line, or set:

stop-screensaver=yes

Do not delete the whole configuration folder. Make one reversible edit, save the file, restart mpv completely, and repeat the short timeout test. Success means ordinary video playback now keeps the display awake. Once it does, stop changing settings.

2.2 Examine profiles and conditional profiles

A global setting can be overridden later by a profile. Search every loaded configuration file for stop-screensaver, including profiles for fullscreen playback, HDR, high-bitrate video, particular protocols, or specific file extensions.

Conditional profiles deserve special attention because they can make the problem appear inconsistent. For example, local files may work while online URLs fail, or HDR media may behave differently from standard video.

Use the following command to display the contents of a named profile:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the actual profile name. If the profile disables inhibition, correct that line and test only the affected media type again.

2.3 Review input bindings and scripts

Search input.conf and custom Lua or JavaScript files for stop-screensaver, set, cycle, or commands that change video output behavior. An accidental key binding can alter the property during playback. A script may also invoke operating-system power tools or respond incorrectly to pause and resume events.

Temporarily disable scripts individually by moving one suspect script out of the scripts directory, then restart mpv. Do not remove all customization at once unless the individual test is impractical. If removing one script fixes the symptom, inspect or update that script rather than rewriting unrelated mpv settings.

2.4 Avoid changing unrelated playback options prematurely

Subtitle selection, audio tracks, screenshot templates, yt-dlp paths, shaders, and network options do not ordinarily control screensaver inhibition. Hardware decoding and HDR settings can matter indirectly if they cause video output to fail or leave mpv effectively playing audio without an active video window.

Check these settings only when the symptom coincides with visible playback failure:

• Confirm that a video track is selected and producing an image.
• Verify that the video output window remains open and responsive.
• Test --hwdec=no only if hardware decoding errors accompany blank video.
• Disable custom shaders temporarily if the picture itself becomes black.
• Test a local file if the issue occurs with a yt-dlp URL or network stream.
• Confirm that screenshot commands are not being confused with display blanking.

If clean local video displays correctly but the screensaver still activates, subtitle, screenshot, audio backend, yt-dlp, and stream settings are unlikely to be the cause.

3. Check Operating-System and Desktop Inhibition Support

If the minimal --no-config test fails, the next suspect is the operating-system integration layer. mpv can request inhibition, but the desktop environment or compositor must recognize and honor that request.

3.1 Linux desktop environments

Linux desktops vary in how they expose idle inhibition. GNOME, KDE Plasma, Xfce, standalone window managers, and lightweight compositors may use different D-Bus, X11, portal, or native compositor mechanisms. A minimal window-manager session may not provide the screensaver service expected by an application.

Check whether other native video players can prevent blanking. If no player can, focus on the desktop's idle settings and inhibitor support. If another player succeeds while clean mpv does not, collect an mpv log and compare whether mpv is using the expected video output and display backend.

On a system using systemd-logind, a practical diagnostic workaround is:

systemd-inhibit --what=idle --who=mpv --why="Video playback" mpv "/path/to/test-video.mkv"

If this command prevents idle sleep while the direct mpv command does not, playback is functional and the failure is specifically in the normal desktop inhibition path. You can use this wrapper temporarily while correcting the desktop or compositor integration.

3.2 X11, XScreenSaver, and xdg-screensaver

On X11, the active screensaver may be XScreenSaver, a desktop-specific service, or basic X server power management. These layers do not always respond to the same inhibition request.

For XScreenSaver, test whether manually resetting its idle timer works:

xscreensaver-command -deactivate

For desktops implementing the freedesktop utility interface, this command may reset the screensaver timer:

xdg-screensaver reset

Use only utilities supplied by your operating system's trusted package repositories. Do not download replacement binaries from random sites. If a manual reset works, the screensaver is reachable, but mpv's automatic integration is not reaching the correct service.

The xdg-screensaver suspend command is another possible X11 workaround, but it expects a window identifier and should later be paired with xdg-screensaver resume. Because window identifiers and lifecycle handling can be fragile, a desktop-native inhibitor or systemd-inhibit is usually safer.

3.3 Wayland and compositor differences

Wayland delegates substantial display and idle behavior to the compositor. Results can therefore differ between GNOME, KDE Plasma, Sway, Hyprland, and other compositors. X11-oriented tools such as xscreensaver-command generally do not control a native Wayland session.

Confirm the session type with:

echo "$XDG_SESSION_TYPE"

If it prints wayland, consult the compositor's idle-inhibition support and configuration. Some compositors require an idle-inhibit protocol, a desktop portal, or compositor-specific rules. Also determine whether mpv is running natively under Wayland or through XWayland, because the compositor may treat the two windows differently.

A successful fix is demonstrated when the same clean video remains visible beyond the configured idle timeout under your normal Wayland session. Once that test passes, do not compensate by changing codecs or media settings.

3.4 Windows and macOS checks

On Windows, confirm that mpv is not running in a restricted remote, service, kiosk, or unusual session where normal execution-state requests are ignored. Review separate timeouts for screen-off, sleep, battery power, and plugged-in operation. Test while connected to AC power to determine whether a battery-specific policy is responsible.

On macOS, test whether the same behavior occurs in a normal local graphical session. Managed power policies, remote sessions, or third-party screen-lock utilities can override application requests. The built-in caffeinate utility can provide a useful diagnostic wrapper:

caffeinate -d mpv "/path/to/test-video.mkv"

If the wrapper works, mpv playback is not the problem. The unresolved issue is the automatic display-sleep assertion or another utility overriding it.

4. Use mpv Logs and Runtime Information

Terminal output can reveal which configuration files, profiles, scripts, video outputs, and display backends mpv actually loaded. This is more reliable than assuming a particular file or option is active.

4.1 Create a detailed log

Run a short controlled test with:

mpv --no-config --stop-screensaver=yes --msg-level=all=v --log-file=mpv-inhibit.log "/path/to/test-video.mkv"

Let playback continue until just beyond the normal blanking timeout, then exit mpv normally. Search the log for terms such as screensaver, inhibit, wayland, x11, vo, error, and failed.

A log does not always print an explicit success message for every platform-level inhibitor. Its main value is confirming the active video output, detecting initialization errors, and proving that the test was genuinely config-free.

4.2 Compare clean and normal logs

If --no-config works, create a second log without that option:

mpv --msg-level=all=v --log-file=mpv-normal.log "/path/to/test-video.mkv"

Compare loaded configuration files, scripts, profiles, and video output decisions. Change one difference at a time. This method is especially effective when an mpv troubleshooting problem appears only with a large customized configuration.

4.3 Use stats and track information correctly

Open mpv's stats overlay using the configured stats binding, commonly i, to confirm that frames are being presented and playback time advances. You can also inspect the track list from the console or terminal output.

If video frames advance normally while the operating system blanks the display, the decoder, hardware decoder, subtitles, and audio backend are probably healthy. If there is no selected video track, inhibition may behave differently because mpv is effectively operating as an audio player.

5. Run a Clean Temporary Test Before Broad Changes

A disciplined test matrix finds the responsible layer without damaging a working setup. Use the same short local file and the same idle timeout for every test.

1. Run local video with --no-config --stop-screensaver=yes.
2. Repeat with your normal configuration.
3. If only normal mode fails, disable one profile or script at a time.
4. If both fail, test a desktop-native player to assess system-wide inhibition.
5. On Linux, test systemd-inhibit and identify X11 or Wayland.
6. Retest in fullscreen and windowed modes only if one mode consistently fails.
7. Restore the normal idle timeout after reaching a conclusion.

Do not combine a new GPU driver, new mpv build, changed video output, disabled hardware decoding, and rewritten configuration in one attempt. If the issue disappears, you will not know which change mattered.

5.1 Use a Lua workaround only when necessary

On an X11 system where manual XScreenSaver resets work but automatic inhibition remains unavailable, a small Lua script can periodically reset the idle timer during active playback. This is a workaround, not the preferred first fix.

A script can use mpv's subprocess command to call xscreensaver-command -deactivate every 30 seconds while playback is not paused. It should stop acting when playback pauses or mpv exits. Use an absolute path to the trusted system utility, handle subprocess errors, and avoid shell execution when direct argument arrays are available.

Do not use this XScreenSaver workaround on native Wayland. Use the compositor's idle-inhibit support instead. Success means the timer is reset only during active playback and returns to normal after mpv closes.

6. Quick Fix Checklist

• Test a local video with --no-config --stop-screensaver=yes.
• Keep video actively playing through a deliberately short idle timeout.
• Remove stop-screensaver=no or no-stop-screensaver from active configurations.
• Inspect conditional profiles, input bindings, and scripts for property changes.
• Confirm that a real video track and video output window are active.
• Identify whether Linux is using X11, XWayland, or native Wayland.
• Test systemd-inhibit, caffeinate, or a desktop-native inhibitor where appropriate.
• Use XScreenSaver or xdg-screensaver commands only on compatible X11 setups.
• Capture a verbose log and compare clean versus normal runs.
• Stop changing settings immediately after the short repeatable test succeeds.

7. Frequently Asked Questions

7.1 Does mpv normally disable the screensaver?

mpv normally attempts to inhibit the screensaver and display power management during video playback when stop-screensaver is enabled. Actual results depend on the video output, platform, desktop environment, compositor, and whether those components honor the inhibition request.

7.2 Why does the screensaver stay disabled for local files but not online URLs?

The online source may spend time buffering, fail to produce a video track, or be handled by a conditional profile. Test the resolved URL and yt-dlp setup separately, but remember that yt-dlp does not directly control screensaver inhibition. Compare logs from a working local file and the failing URL.

7.3 Can hardware decoding or HDR cause this problem?

Not directly in the usual case. They become relevant if a GPU driver, hardware decoder, HDR path, shader, or video output fails and mpv no longer presents active video. If the image plays smoothly while only the operating system blanks the monitor, changing hwdec or HDR settings is unlikely to help.

7.4 Why does inhibition work on X11 but fail on Wayland?

X11 and Wayland use different mechanisms. An X11 screensaver utility cannot generally control native Wayland idle behavior. Under Wayland, the compositor must support and honor an appropriate idle-inhibition mechanism, and XWayland applications may be treated differently from native Wayland windows.

7.5 Should mpv prevent blanking while paused or playing audio only?

Do not assume it will. Desktop policies and mpv behavior may distinguish active video playback from paused or audio-only operation. Diagnose the issue with visible, unpaused video first. If your goal is to inhibit sleep during audio playback, use a deliberate operating-system inhibitor rather than relying on video-specific behavior.

7.6 When should I use a Lua script?

Use a script only after confirming that clean mpv cannot communicate successfully with the available screensaver service and that a trusted manual reset command works. Prefer a desktop-native fix because scripts can mishandle pause, shutdown, multiple players, or session changes. If you deploy one, test playback, pause behavior, and normal screensaver recovery after mpv exits.