The xrandr command fails to add new resolutions primarily because the display server (X11 or Wayland) lacks the necessary mode definitions in its configuration, or because the graphics driver is not generating them automatically. To resolve this, you must manually generate a valid modeline using the cvt utility and then apply it via xrandr, ensuring your hardware supports the requested timing parameters.
Understanding Why xrandr Fails
When you attempt to use
xrandr --addmode, the system rejects the request if the specified resolution and refresh rate combination does not exist in the current list of supported modes for that output. This often happens with custom resolutions, non-standard aspect ratios, or when connecting monitors that do not report their Extended Display Identification Data (EDID) correctly. The error message typically states that the mode is unknown or that the output does not support the given resolution.
Before attempting complex fixes, verify that your X server is actually running. If you are on a modern Linux distribution using Wayland by default,
xrandr may not have direct control over the display compositor. In such cases, you might need to switch to an X11 session temporarily to test if the issue persists, or use tools specific to your desktop environment. For more details on basic monitor management, see
How to Use xrandr Command to Turn On Your Monitor in Linux.
Generating the Correct Modeline
The most common reason for failure is providing an invalid or malformed modeline. You should never guess the timing values. Instead, use the
cvt (Coordinated Video Timings) tool to calculate the correct parameters based on your desired resolution and refresh rate.
Open a terminal and run the following command, replacing
1920x1080 and
60 with your target values:
cvt 1920 1080 60
The output will look something like this:
# 1920x1080 59.96 Hz (CVT 2.07M9) hsync: 67.16 kHz; pclk: 173.00 MHz
Modeline "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
Copy everything after the word
Modeline, excluding the word itself. This string contains the pixel clock, horizontal sync, vertical sync, and other timing flags required by
xrandr. Using hardcoded values from old tutorials often leads to black screens because these numbers vary significantly between different monitor panels and cable bandwidths.
Applying the New Resolution
Once you have the modeline, you can create the new mode and assign it to your display output. It is crucial to identify the correct output name dynamically rather than assuming it is always
HDMI-1. Run the following command to list all connected outputs:
xrandr | grep connected
Look for the line ending in
connected. The identifier before it (e.g.,
HDMI-1,
DP-1,
VGA-1) is what you must use. Assume your output is named
HDMI-A-1 for this example.
First, create the new mode using the modeline you copied earlier:
xrandr --newmode "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
Next, add this mode to your specific output:
xrandr --addmode HDMI-A-1 "1920x1080_60.00"
Finally, apply the resolution:
xrandr --output HDMI-A-1 --mode "1920x1080_60.00"
If the screen goes black or becomes unusable, wait ten seconds, as most window managers will revert to the previous safe state. If it does not revert, press
Ctrl+Alt+F2 to switch to a TTY, log in, and restart your display manager with
sudo systemctl restart gdm (or
sddm/
lightdm).
Ensuring Persistence Across Reboots
The commands above are temporary and will be lost upon reboot. To make the changes permanent, you need to integrate them into your startup process. The method varies depending on your desktop environment.
For GNOME users, creating a custom script and adding it to the "Startup Applications" is a reliable approach. Create a shell script containing the three
xrandr commands mentioned above. Make it executable with
chmod +x ~/fix-resolution.sh. Then, add it to your autostart directory at
~/.config/autostart/ or use the graphical startup application manager.
For KDE Plasma, you can use the built-in KScreen settings to save configurations, or add the script to
~/.profile. Note that some modern desktop environments manage displays via D-Bus interfaces rather than raw
xrandr calls, which might cause conflicts. If you experience screen glitches after applying custom resolutions, refer to
Resolving Screen Glitch on Linux Distro: Using Particular Output Display Size for troubleshooting steps related to tearing and synchronization issues.
Troubleshooting Driver Issues
If
xrandr refuses to accept the new mode even with a valid modeline, the issue likely lies with the graphics driver. Proprietary drivers for NVIDIA cards sometimes require specific kernel module parameters to enable higher resolutions. Ensure that your kernel headers match your running kernel version, as mismatched modules can prevent dynamic mode creation.
Additionally, check your EDID data. Sometimes monitors send incorrect EDID blocks that limit available resolutions. You can force the system to ignore EDID limitations by adding
nvidia-drm.modeset=1 to your GRUB boot parameters (for NVIDIA users) or by using
edid-decode to analyze the raw EDID data. If you are dealing with multi-monitor setups where one display appears zoomed or distorted, ensure that scaling settings are consistent across all outputs. See
Fix Display Appearing Zoomed With Multi-Monitor Setup Using xrandr for advanced scaling adjustments.
Frequently Asked Questions
Why does my screen go black after running xrandr?
This usually indicates that the applied mode is unsupported by your monitor's physical panel or the cable bandwidth is insufficient. Wait ten seconds for the auto-revert feature to kick in. If it fails, switch to a TTY and restart your display manager to restore the default configuration.
Can I use xrandr on Wayland sessions?
Standard
xrandr commands generally do not work on Wayland compositors like Mutter or KWin because they use different protocols for display management. You may need to switch to an X11 session to test if the resolution issue is driver-related, or use the native settings tools provided by your desktop environment instead.
How do I find the correct output name if HDMI-1 doesn't exist?
Always run
xrandr | grep connected to see the actual identifiers assigned by your system. These names can change between boots depending on cable insertion order. Common alternatives include
DP-1,
eDP-1 for laptop screens, or
VGA-1 for older connections.
What should I do if cvt generates a mode that xrandr rejects?
If
xrandr rejects the modeline, try reducing the refresh rate (e.g., from 60Hz to 59Hz or 50Hz) or lowering the resolution slightly. Some monitors have strict timing tolerances. You can also try removing the
-hsync +vsync flags and replacing them with
+hsync +vsync to see if positive sync signals are preferred by your hardware.
Does this fix apply to external monitors only?
No, the same principles apply to internal laptop screens (
eDP-1) and any connected display. However, modifying internal screen timings carries a higher risk of causing flickering or blanking if the panel cannot handle the generated signal. Always test with external displays first if possible.