mpv Aspect Ratio Wrong: How to Fix It

When the mpv aspect ratio looks wrong, the visible symptom usually falls into one of four categories: the picture is stretched, squashed, cropped, or surrounded by unexpected black bars. These problems can come from an active aspect-ratio override, runtime pan or zoom changes, crop filters, incorrect display metadata in the media file, anamorphic video, a profile or script, or display-output behavior. The fastest solution is not to change several options at once. First reproduce the problem with a clean command, identify whether mpv is honoring the source geometry, and then isolate the exact setting or media limitation responsible.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by removing your normal configuration from the test without deleting or renaming anything. Open Command Prompt, PowerShell, Terminal, or your preferred shell and run mpv with --no-config.

On Windows, a basic test looks like this:

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

On Linux or macOS, use:

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

Keep the path quoted, especially if it contains spaces, brackets, ampersands, or other characters interpreted by the shell. Dragging the file into a terminal window after typing the command can help insert the correct path.

1.1 Interpret the clean-test result

If the video looks correct with --no-config, the file and mpv's basic aspect-ratio handling are probably working. The cause is likely in mpv.conf, an input binding, a profile, a script, a shader-related configuration, or a command sent through IPC. Stop investigating codecs, GPU drivers, and file metadata for now. Concentrate on configuration isolation.

If the picture remains wrong with --no-config, compare it in another reputable player or inspect the file with a trusted metadata tool such as FFprobe or MediaInfo. A problem that appears consistently across players usually points to incorrect container metadata, anamorphic signaling, hard-coded borders, or an intentionally cropped source.

Success means the picture has natural proportions. Circles should look circular, people should not look unusually wide or narrow, and the image should not lose content at its edges. Black bars can be correct when the video's aspect ratio differs from the window or display. Once the geometry looks natural, stop changing settings merely to eliminate every black bar.

2. Check Aspect Overrides, Pan, Zoom, and Crop Settings

The most common mpv-specific cause is an aspect override that was enabled accidentally or saved in a configuration file. Other frequent causes are panscan, video zoom, and crop filters. These options alter different parts of the presentation, so they should be checked separately.

2.1 Reset the A key aspect override

In mpv's default input configuration, the uppercase A key cycles video aspect-ratio overrides. Because uppercase input normally requires Shift, an accidental key press can make a 4:3 video appear as 16:9 or force another shape onto the image.

Press A repeatedly while watching mpv's on-screen message. Return the aspect setting to its automatic or original state. You can also start a clean test explicitly with:

mpv --no-config --video-aspect-override=-1 "video.mkv"

The automatic value tells mpv not to force a user-selected display aspect ratio. If this fixes the picture, search your configuration and input files for video-aspect or video-aspect-override. Remove or comment out only the responsible line rather than deleting the whole configuration folder.

Success means mpv follows the aspect information supplied by the decoded video and container. Stop after confirming several representative files look correct.

2.2 Distinguish container display aspect ratio from pixel dimensions

A file's stored pixel dimensions do not always equal its intended display shape. For example, standard-definition material may use non-square pixels. The decoder produces a coded frame, while metadata supplies a sample aspect ratio or display aspect ratio that tells the player how wide the image should appear.

This is especially important with anamorphic DVDs, archival transfers, broadcast recordings, and some transcoded files. A 720-by-576 frame is not automatically meant to be displayed as 5:4. Its aspect metadata may instruct the player to present it as 4:3 or 16:9.

If only one file is wrong and clean mpv produces the same result as other players, inspect its sample and display aspect metadata. As a temporary viewing correction, start mpv with an explicit override such as:

mpv --no-config --video-aspect-override=16:9 "video.mkv"

Use the ratio known to be correct for that source. This does not repair the file's metadata. It only changes presentation during playback. If you control the media and need a permanent correction, remuxing with accurate display metadata may be preferable to re-encoding, but confirm the intended ratio before modifying the file.

2.3 Reset panscan and video zoom

Panscan enlarges video to fill more of the window, potentially moving part of the image outside the visible area. Video zoom similarly scales the picture and can crop its edges. These controls are useful intentionally, but they are a common explanation when subtitles, faces, or opening credits are cut off.

Test with neutral values:

mpv --no-config --panscan=0 --video-zoom=0 "video.mkv"

If you want to reset them during a session, use mpv's console or an input binding that sets the properties back to zero. For example, custom bindings can use commands equivalent to setting panscan and video-zoom to 0. Check input.conf for bindings that add to either property, particularly keys you may press while seeking or adjusting subtitles.

Success means the complete intended frame is visible. Letterboxing or pillarboxing may return after the reset, which is expected when preserving the original aspect ratio.

2.4 Find crop filters

A crop filter removes pixels before the image is displayed. It can make the framing appear zoomed even when panscan and video-zoom are zero. Search mpv.conf, profiles, scripts, and launch commands for entries involving vf, vf-add, or crop.

Test the file without a video-filter chain:

mpv --no-config --vf-clr "video.mkv"

With --no-config, filters from your normal configuration are already excluded. The explicit filter reset is most useful when building a controlled command or clearing runtime filters. Be aware that scripts can add filters after playback starts, so observe whether the picture changes a moment after opening the file.

If removing a crop filter restores missing edges, disable that filter only for affected content or place it in a narrowly targeted profile. Stop when the full frame returns and the proportions remain correct.

3. Inspect Configurations, Profiles, Scripts, and Track Behavior

When clean mpv works, reintroduce customization in groups. Start with the main configuration, then input bindings, profiles, scripts, shaders, and external integrations. This is faster and safer than permanently wiping a carefully built setup.

3.1 Search mpv.conf and input.conf

Search configuration files for the following terms:

• video-aspect or video-aspect-override
• panscan
• video-zoom, video-pan-x, or video-pan-y
• video-crop, crop, vf, or lavfi
• video-scale-x or video-scale-y
• video-unscaled
• geometry, autofit, or window-scale

The last group usually changes window size or placement rather than the video's inherent aspect ratio. However, it can create misleading results when combined with unscaled video, forced window dimensions, or a window manager that constrains resizing.

Comment out one suspicious line, restart mpv, and repeat the same test. If the image becomes correct, restore unrelated lines and keep only the problematic option disabled.

3.2 Check conditional profiles

A profile may activate only for certain file extensions, resolutions, protocols, HDR content, or fullscreen states. That explains why local files might look correct while streams look cropped, or why only high-resolution video is affected.

Use the profile inspection option for a named profile:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile you want to inspect. Review auto-profile conditions and any included configuration files. Look for geometry-related options and filter additions.

If disabling one profile fixes the issue, narrow its conditions or remove the geometry option from that profile. There is no need to abandon unrelated hardware-decoding, HDR, shader, or subtitle settings.

3.3 Test scripts and IPC controllers

Lua or JavaScript extensions can change properties after a file loads. Front ends and IPC clients can do the same. Temporarily test without scripts, or move only the suspected script out of the active scripts directory and restart mpv. Do not remove all configuration data as a first step.

Pay attention to scripts that provide automatic cropping, aspect detection, window management, display mode switching, or anime and subtitle profiles. Also inspect IPC automation for commands that set zoom, panscan, aspect override, crop, or video filter properties.

A script-related fix is successful when the file opens with correct geometry and stays correct after startup, seeking, changing tracks, entering fullscreen, and loading the next playlist item.

3.4 Separate subtitles and track selection from geometry

Subtitle placement can make a correct video look cropped. Image-based subtitles may have their own canvas dimensions, while text subtitles can be positioned outside the visible image or within black bars. Disable subtitles temporarily to determine whether the underlying video frame is actually wrong.

Switch among video tracks if the container has more than one. A cover image, alternate-angle track, low-resolution preview, or incorrectly tagged track can produce unexpected dimensions. Audio track selection does not normally change aspect ratio, but a complex edition or playlist may select a different video stream alongside an audio choice.

If the video is correct with subtitles hidden, troubleshoot subtitle positioning, scale, margins, and override behavior rather than forcing a new video aspect ratio.

4. Check Output, Hardware Decoding, Streams, and File Limitations

Aspect metadata and mpv settings are the first places to look. GPU, display-server, and hardware-decoding issues are less common, but they become relevant when the result changes between output paths or appears only on particular systems.

4.1 Compare hardware and software decoding

Run a temporary software-decoding test:

mpv --no-config --hwdec=no "video.mkv"

If software decoding displays correct geometry but hardware decoding does not, capture a log and update the GPU driver through the operating system, computer manufacturer, or GPU vendor's official channel. Avoid random codec packs and unofficial binary bundles. mpv uses its own supported decoding stack, so system codec packs rarely solve this symptom and may introduce unrelated problems.

Also compare your normal video output with a clean default test. Custom GPU contexts, display-server choices, shaders, or output drivers can expose driver-specific scaling problems. On Linux, note whether the issue occurs under Wayland, X11, or both. On macOS and Windows, test windowed and fullscreen playback while keeping aspect overrides disabled.

Success means hardware and software paths preserve the same proportions. If only one path fails, keep the working path temporarily and investigate the driver or output-specific log rather than compensating with a false aspect override.

4.2 Evaluate HDR and shader configurations

HDR tone mapping should affect brightness and color, not the intended display aspect ratio. Shaders normally affect scaling quality, but a complex filter chain or user script can also crop, pad, or resize the frame.

If the problem occurs only with HDR or high-bitrate media, repeat the clean --no-config test before blaming the format. A clean result points to an HDR profile, shader preset, automatic crop script, or hardware-decoding condition. Disable those components individually until geometry remains stable.

4.3 Compare local files with URLs and network streams

For an online URL, mpv may rely on yt-dlp to resolve the playable media. The selected format can differ in resolution or even aspect ratio from the version expected. Network broadcasts may also switch renditions, contain malformed display metadata, or include hard-coded bars.

First determine whether the issue exists in a directly downloaded, legitimately accessible sample or another format from the same authorized source. Then test the resolved stream with --no-config. Confirm that mpv is finding the intended yt-dlp executable and that shell quoting has not truncated a URL at an ampersand or question mark.

Do not use an aspect override to hide a stream-selection mistake. Review the track list and terminal output to verify the selected video resolution. Network access, authentication, and external-tool failures usually prevent playback or force a fallback format rather than directly changing geometry, but the fallback may have different dimensions or baked-in borders.

4.4 Understand screenshots and hard-coded bars

A screenshot can differ from what you perceive in the window depending on whether it captures the source video, subtitles, or the processed output. If the saved image has different framing, inspect your screenshot command and whether filters or subtitles are included. Window-level scaling and unused display space may not be represented in a video-only screenshot.

Some black bars are encoded into the video pixels. mpv cannot remove them while preserving every source pixel because the bars are part of the frame. Cropping them is optional, but it should not be confused with correcting aspect metadata. If circles and faces have natural proportions, the aspect ratio may already be right.

5. Use Logs, Stats, and Track Information

When visual tests are inconclusive, collect evidence from mpv rather than guessing. Run the problematic file from a terminal so startup messages remain visible.

5.1 Create a focused log

Use a log file and increase relevant message detail:

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

A highly verbose log can be large, so reproduce the symptom briefly and close mpv. Search the log for video dimensions, aspect information, selected tracks, filters, hardware decoding, video output, and errors. When testing your normal configuration, remove --no-config and compare the two logs.

Do not publish a log without reviewing it. Commands and URLs may contain private file paths, hostnames, tokens, or authentication information.

5.2 Use the stats overlay and track list

Press i with default bindings to open mpv's statistics overlay. Additional pages or detail may be available depending on your mpv configuration and bindings. Check the displayed source dimensions, output behavior, decoder, frame rate, and selected video track.

Use mpv's track list or on-screen controller to verify that the intended video stream is selected. If a playlist item or network manifest contains several tracks, compare their dimensions and labels.

The evidence should answer a specific question: Is mpv receiving the wrong dimensions, applying an override, processing the frame through a crop, or merely fitting a correct image into a differently shaped window?

6. Run a Clean Temporary Test Before Permanent Changes

Use a small test matrix to avoid changing unrelated settings:

1. Run the file with --no-config.
2. Add --video-aspect-override=-1, --panscan=0, and --video-zoom=0.
3. Test with --hwdec=no only if the first tests still fail.
4. Compare another known-good local file with a clearly recognizable aspect ratio.
5. Compare the affected file in another reputable player or inspect its metadata.
6. Re-enable your main configuration, profiles, scripts, and shaders one group at a time.

Change one variable per run and write down the result. Once a single change consistently restores correct proportions, stop expanding the test. Make the smallest permanent correction, such as removing one override, resetting a binding, or limiting a crop profile.

7. Quick Fix Checklist

• Press uppercase A until the aspect override returns to automatic.
• Test with mpv --no-config "video.mkv".
• Set video-aspect-override to -1 for automatic handling.
• Reset panscan and video-zoom to 0.
• Search configurations and bindings for aspect, zoom, pan, crop, and filter commands.
• Inspect profiles with --show-profile.
• Temporarily disable automatic crop or window-management scripts.
• Verify the selected video track and stream resolution.
• Check anamorphic and display-aspect metadata when only one file fails.
• Compare software decoding with --hwdec=no if output-path behavior differs.
• Use logs and the stats overlay before making permanent changes.
• Accept correct letterboxing or pillarboxing when it preserves the source shape.

8. Frequently Asked Questions

8.1 Why is mpv stretching a 4:3 video to 16:9?

An active aspect override is the most likely cause. Press uppercase A until automatic handling returns, or test with --video-aspect-override=-1. If that works, remove the corresponding option or binding from your configuration.

8.2 Why does mpv show black bars when the video fills another player?

mpv may be preserving the source aspect ratio while the other player is zooming, cropping, or stretching it. Black bars are correct when the video and window have different shapes. Check faces and circular objects before deciding the bars indicate a fault.

8.3 How do I reset accidental zoom and pan changes?

Start a new test with --panscan=0 --video-zoom=0. Also check for nonzero video pan properties and custom input bindings. Restarting mpv resets unsaved runtime changes, but options in configuration files, profiles, scripts, or IPC automation will return until corrected.

8.4 Why is only one video squashed?

The file may contain incorrect or missing display-aspect metadata, or it may be anamorphic. Inspect its sample and display aspect ratios and compare it in another player. Apply a temporary override only after confirming the intended shape.

8.5 Can subtitles cause an apparent aspect-ratio problem?

Subtitles do not normally change video geometry, but incorrect subtitle scaling or placement can make the frame appear cropped or misaligned. Hide subtitles temporarily. If the video itself is correct, adjust subtitle settings rather than the video aspect ratio.

8.6 Should I reinstall mpv when the aspect ratio is wrong?

Usually not. A clean --no-config test is more informative than reinstalling. If clean mpv works, the installation is probably fine and a configuration, profile, binding, or script is responsible. Consider replacement or an official updated build only after logs indicate a binary or output problem.