mpv Window Border Missing: How to Fix It

When the mpv window border is missing, the video may still play normally, but the title bar, close button, maximize button, or resize edges are gone. This symptom usually comes from one of four places: mpv was started with window borders disabled, a configuration or script changed the setting, a graphical frontend controls decorations differently, or the Linux display server and compositor did not negotiate server-side decorations. The steps below isolate those causes without deleting your configuration or changing unrelated playback settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by determining whether vanilla mpv can create a decorated window when it ignores your normal configuration. This is faster and safer than editing several files at once.

1.1 Run mpv without your configuration

Open a terminal, Command Prompt, or PowerShell window and run mpv with a local video file:

mpv --no-config --border=yes "path/to/video.mkv"

On Windows, you may need to run the command from the directory containing mpv.exe or provide its full path. In PowerShell, a typical command is:

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

On Linux or macOS, the command name is normally mpv. Quote any path containing spaces. Use a known-good local video rather than an online URL for this first test. Doing so removes yt-dlp, authentication, network access, and stream behavior from the investigation.

Success means the title bar and expected window controls return, or the window at least gains a usable resize border appropriate to your desktop. If that happens, stop changing operating system or GPU settings. The cause is almost certainly in your normal mpv configuration, profile, input binding, script, or launch command.

1.2 Verify that the problem is really window decoration

Do not confuse missing window decorations with these different symptoms:

• A black window indicates a video output, decoding, HDR, shader, or GPU problem.
• No video window may mean audio-only playback, forced video suppression, or no selected video track.
• A hidden on-screen controller concerns the OSC, not the operating system title bar.
• A window that cannot be resized may be fixed-size or controlled by a frontend.
• Exclusive fullscreen intentionally removes normal desktop decorations.

Press f once to leave fullscreen if necessary. If the title bar returns after leaving fullscreen, mpv is behaving normally and no border repair is required.

2. Check the Options and Customizations Directly Related to the Border

2.1 Inspect the border option

The mpv option that directly controls standard window decorations is border. In mpv.conf, either of these lines can remove decorations:

border=no

no-border

Change the active setting to:

border=yes

Alternatively, comment out the unwanted line and let mpv use its default behavior. Configuration comments begin with #. Check for duplicate entries because a later applicable setting can override an earlier one.

Success means a newly opened mpv window has its native title bar or border. Restart mpv after saving the file. If the decoration returns, stop there. Subtitle, audio, HDR, decoding, and network options do not need adjustment.

2.2 Look for profiles that override the setting

An apparently correct global setting can be overridden by a profile in mpv.conf. Search the file for border and inspect profiles that are enabled automatically or passed on the command line. Pay special attention to profiles associated with fullscreen playback, particular protocols, file extensions, displays, or conditional auto profiles.

If your launcher includes an argument such as --profile=name, test the same launch without it. You can also ask mpv to display a profile definition:

mpv --show-profile=profile_name

This prints the options associated with that profile. It does not prove that every conditional profile is active, but it helps identify an explicit border=no entry.

2.3 Check input bindings and scripts

mpv can change options while running. Search input.conf and script configuration files for terms such as border, cycle border, set border, and fullscreen. A custom key may toggle the border accidentally, while a Lua or JavaScript extension may set the property when a file loads.

A binding might resemble:

b cycle border

That binding is not inherently wrong, but pressing the key can leave the current window undecorated. Temporarily remove or comment out the binding, restart mpv, and test again. For scripts, move only the suspected script out of the scripts directory for one test. Do not delete the entire configuration folder.

Success means the border remains present after files load and after your normal keyboard workflow. Once the responsible binding or script is identified, keep the rest of your setup intact.

2.4 Distinguish OSC pseudo-decorations from native borders

mpv's on-screen controller, commonly called the OSC, can display playback controls over the video. Some OSC designs or third-party scripts also draw controls that resemble a title bar, including close, minimize, maximize, or drag areas. These are pseudo-decorations inside the video window, not native decorations supplied by Windows, macOS, or a Linux compositor.

Turning off the OSC can therefore make a borderless window appear to lose its controls:

osc=no

Restoring osc=yes may bring back pseudo-controls, but it does not repair a missing native border. Conversely, enabling border=yes can produce native decorations even if the OSC remains disabled. Decide which interface you expect before troubleshooting further.

2.5 Separate frontend behavior from vanilla mpv

Applications built around libmpv may own the top-level window themselves. Their title bars, resize handles, and close buttons are controlled by the frontend, not necessarily by mpv's border option. A frontend may use client-side decorations, a custom title bar, or a frameless window by design.

Run the standalone mpv executable with --no-config --border=yes. If vanilla mpv is decorated but the frontend is not, stop editing mpv.conf unless that frontend explicitly documents support for the option. Check the frontend's appearance, frameless-window, title-bar, or window-decoration preference instead.

2.6 Avoid changing unrelated media options

Subtitle settings, selected audio and video tracks, screenshot templates, HDR tone mapping, hardware decoding, shaders, and yt-dlp paths do not normally control native window decorations. The same is true of most output-driver and audio-backend choices. Do not change them merely because they appear in a large configuration.

They become relevant only when the symptom is broader than a missing frame. For example, a video output failure can prevent a normal window from appearing at all, and an audio-only file may not create the window you expected. When video is visible and only the title bar or resize frame is absent, stay focused on border, fullscreen state, scripts, the frontend, and the window system.

3. Check the Operating System and Display Server

3.1 Understand Wayland xdg-decoration support

On Wayland, an application and compositor can negotiate window-decoration behavior through the xdg-decoration protocol. If the compositor does not provide server-side decorations, a client must supply suitable client-side decorations to show a conventional frame. mpv's behavior can therefore differ between compositors and between Wayland and X11 sessions.

This is especially important when --no-config --border=yes still produces an undecorated window on Linux. The option expresses the requested mpv behavior, but the final appearance also depends on the active window-system backend and compositor capabilities.

Check the session type with:

echo $XDG_SESSION_TYPE

If it reports wayland, compare the result under an X11 session when one is safely available. You can also compare mpv's Wayland and X11 behavior without treating an X11 fallback as the only permanent solution. Success means the clean test receives usable decorations under one backend, confirming that the issue is in decoration negotiation rather than media decoding.

3.2 Account for GNOME Wayland limitations

GNOME's Wayland environment generally expects applications to provide client-side decorations rather than relying on traditional server-side title bars. An application that requests server-side decorations may consequently appear borderless. This can affect vanilla mpv even when border=yes is present.

Practical choices include using mpv's OSC or a trusted OSC script with pseudo-decorations, launching through a frontend that supplies its own client-side title bar, or using an X11 session or XWayland path when appropriate for your system. Avoid installing random patched binaries merely to obtain a title bar.

If pseudo-decorations provide close and drag controls, or an X11 comparison produces native decorations, you have identified the limitation. Stop changing codecs, hardware decoding, and media options because they cannot add compositor decorations.

3.3 Review launch permissions and shell quoting

Permissions rarely remove only a title bar, but launch context can cause mpv to read a different configuration. Running mpv as another user, through sudo, from a desktop launcher, or through a media manager may select another home directory or add arguments such as --no-border.

Inspect the actual shortcut, desktop entry, shell alias, or wrapper script. On Linux, commands such as type mpv can reveal an alias or wrapper. On Windows, review the shortcut's Target field. On macOS, distinguish a command-line mpv build from a separate app bundle or frontend.

Correct quoting also matters. Keep each option separate and quote only paths that require it. Success means launching from the corrected shortcut produces the same decorated window as the terminal test.

3.4 Know when GPU and backend checks are justified

A GPU driver or video output problem is worth investigating only if the window is blank, crashes, never appears, or logs errors while creating a rendering context. It is not a likely explanation when video renders correctly inside a stable but borderless window.

Likewise, the audio backend, media bitrate, network protocol, external subtitle file, and screenshot directory do not create title bars. A high-bitrate local file, HDR stream, playlist, or online URL can expose playback problems, but window decorations should first be tested with a simple local file and a clean configuration.

4. Use mpv Diagnostics Without Drowning in Logs

4.1 Capture focused terminal output

Run a clean test from a terminal so startup messages remain visible:

mpv --no-config --border=yes --msg-level=all=info "video.mkv"

For more detail about window creation and video output, increase verbosity temporarily:

mpv --no-config --border=yes --msg-level=all=v "video.mkv"

Look for the selected video output, whether Wayland or X11 is being used, fullscreen-related behavior, and errors creating a window. Do not assume every warning causes the missing border.

4.2 Save a reproducible log

Use --log-file when terminal output scrolls too quickly:

mpv --no-config --border=yes --msg-level=all=v --log-file=mpv-border.log "video.mkv"

The log may contain file paths, URLs, or system details, so review it before sharing. If the clean log shows successful video output and the only problem is decoration under Wayland, that supports a compositor or frontend explanation.

4.3 Use other diagnostic features only when relevant

The stats overlay is useful for decoding, dropped frames, rendering, and performance, but it does not diagnose native window borders. The track list helps when no video window appears because the file has no selected video track. These tools become useful only if the initial symptom was misidentified.

• Use the stats overlay when video rendering or performance is also broken.
• Inspect the track list when mpv is playing audio without expected video.
• Check yt-dlp only when an online URL fails before playback begins.
• Check hardware decoding only when logs show decoder or rendering failures.
• Check screenshot settings only when taking screenshots fails.

For a stable window that simply lacks decorations, these subsystems are distractions.

5. Run a Clean Temporary Test Before Making Permanent Changes

A controlled comparison is the safest mpv troubleshooting method. Change one variable at a time and record the result.

1. Choose a short, known-good local video.
2. Exit every running mpv or frontend instance.
3. Run mpv --no-config --border=yes "video.mkv".
4. Confirm that mpv is not fullscreen by pressing f once if needed.
5. If decorations appear, restore your normal configuration and search for border settings, profiles, bindings, and scripts.
6. If decorations remain absent, test standalone mpv instead of a frontend.
7. On Linux, identify whether the session uses Wayland or X11.
8. Compare another supported session or frontend only after preserving the clean test result.

Do not move or delete the whole configuration directory as the first step. The --no-config option provides the same isolation without risking your profiles, shaders, scripts, input bindings, IPC settings, or carefully tuned playback options.

Stop when one controlled change restores the expected title bar, buttons, or resize behavior. Additional changes make the cause harder to identify and may introduce unrelated playback problems.

6. Quick Fix Checklist

• Leave fullscreen mode before diagnosing a missing border.
• Test --no-config --border=yes with a local video.
• Remove or override border=no and no-border.
• Search profiles, launch arguments, input bindings, and scripts for border changes.
• Determine whether controls came from the OSC rather than the operating system.
• Test standalone mpv if a frontend has a frameless window.
• On Wayland, consider compositor and xdg-decoration support.
• On GNOME Wayland, use pseudo-decorations, a suitable frontend, or an X11 comparison.
• Inspect terminal output before changing GPU or video settings.
• Stop once the clean window has usable decorations.

7. FAQ

7.1 How can I close mpv when there is no close button?

Press q to quit mpv normally. On Windows, Alt+F4 usually closes the active window. Many Linux desktops use Alt+F4, while macOS applications commonly use Command+Q. These shortcuts are useful while you repair the decoration setting.

7.2 How can I move a borderless mpv window?

On many Linux desktops, holding Alt and dragging with the left mouse button moves a window from anywhere inside it. Some Wayland compositors use the Super key instead. Windows users can press Alt+Space, choose Move, and use the arrow keys when the system menu is available. Desktop-specific shortcuts may vary.

7.3 Why does border=yes work on X11 but not Wayland?

The two systems handle window decorations differently. Under Wayland, xdg-decoration negotiation and compositor policy determine whether server-side decorations are available. If the same clean command gains a title bar under X11, mpv's configuration is probably not the root cause.

7.4 Can the OSC replace the missing title bar?

Yes, in practical terms, if your OSC or an established interface script provides dragging and window buttons. It remains an in-window control layer rather than a native title bar. This is often a workable approach on environments where server-side decorations are unavailable.

7.5 Why does vanilla mpv have a border while my frontend does not?

A libmpv frontend usually creates and manages its own window. Its frameless mode or custom title bar can override expectations from standalone mpv. Change the frontend's window setting rather than repeatedly editing mpv's playback configuration.

7.6 Should I reinstall mpv or update codecs?

Not for a border-only symptom. First prove the behavior with --no-config --border=yes and identify the display server or frontend. Codec packs affect media decoding, not desktop title bars, and unsafe third-party downloads can create larger problems. Reinstallation is reasonable only when trusted package files are damaged or mpv cannot start, not when video plays normally in a borderless window.