Display resolution and refresh rate on Linux: Xorg and Wayland

Updated November 2026

You rarely need to write video timings by hand any more. The monitor describes its own modes (EDID), the kernel's graphics driver sets them (kernel mode setting, KMS), and your desktop offers a list to pick from. When a mode is missing, you can calculate one with cvt and add it with xrandr on Xorg, force it with the video= kernel parameter on Wayland, or replace a broken EDID. This page shows each method and when to use it.

What changed since XFree86

In the XFree86 days you looked up your monitor's horizontal and vertical sync ranges in its manual and calculated "modelines" yourself; a wrong value could damage an old CRT. Today:

Check your session and outputs

First find out whether you are on X11 or Wayland:

echo $XDG_SESSION_TYPE

The answer is x11 or wayland. Next, list the connectors the kernel knows about and whether a monitor is attached:

ls /sys/class/drm/
cat /sys/class/drm/card*-*/status

Entries look like card1-HDMI-A-1 or card1-eDP-1. The part after card0- or card1- is the connector name the kernel uses (for example in video=). Xorg may name the same port differently (HDMI-1 or HDMI-A-0, depending on the driver), so always copy names from the tool you are using.

The easy way: desktop settings

If the mode you want is in the list, stop here. The rest of this page is for missing or wrong modes.

Xorg: xrandr

Show outputs and the modes each one offers (the current mode is marked *, the preferred one +):

xrandr -q

Set a mode and refresh rate, or let xrandr pick the preferred mode:

xrandr --output HDMI-1 --mode 1920x1080 --rate 60
xrandr --output HDMI-1 --auto

Two monitors side by side, with the laptop panel as primary:

xrandr --output eDP-1 --primary --auto --output HDMI-1 --auto --right-of eDP-1

Changes last only for the current session. Put the command in your session's autostart, or use the configuration file shown below.

Add a mode the monitor does not report

Calculate timings with cvt (VESA Coordinated Video Timings; on Debian 13 it is in the xcvt package). The third argument is the refresh rate; the default is 60 Hz:

$ cvt 1280 1024
# 1280x1024 59.89 Hz (CVT 1.31M4) hsync: 63.67 kHz; pclk: 109.00 MHz
Modeline "1280x1024_60.00"  109.00  1280 1368 1496 1712  1024 1027 1034 1063 -hsync +vsync

For flat panels, cvt -r calculates reduced blanking timings: shorter gaps between lines, so the same mode needs a lower pixel clock. This helps when a cable or adapter cannot carry a high resolution at full timings. Do not use reduced blanking on a CRT. The older gtf tool (gtf 1280 1024 60) uses the earlier GTF formula and can also print timings for fbset with -f.

Copy everything after the word Modeline into xrandr --newmode, attach the mode to an output, and switch to it:

xrandr --newmode "1280x1024_60.00"  109.00  1280 1368 1496 1712  1024 1027 1034 1063 -hsync +vsync
xrandr --addmode VGA-1 1280x1024_60.00
xrandr --output VGA-1 --mode 1280x1024_60.00

If you are testing a risky mode, chain a fallback so you get a picture back after a few seconds: xrandr --output VGA-1 --mode 1280x1024_60.00 && sleep 10 && xrandr --output VGA-1 --auto. Remove a test mode with xrandr --delmode VGA-1 1280x1024_60.00 and then xrandr --rmmode 1280x1024_60.00.

Make it permanent on Xorg

Create /etc/X11/xorg.conf.d/10-monitor.conf with a Monitor section whose Identifier is the Xorg output name:

Section "Monitor"
    Identifier "VGA-1"
    Modeline "1280x1024_60.00"  109.00  1280 1368 1496 1712  1024 1027 1034 1063 -hsync +vsync
    Option "PreferredMode" "1280x1024_60.00"
EndSection

Restart the X server (log out and in again, which closes your programs) to apply it.

What the numbers mean

A modeline lists the pixel clock in MHz, then four horizontal values (visible width, sync start, sync end, total width) and four vertical values (visible height, sync start, sync end, total height), then sync polarities. The totals include the invisible blanking interval. Refresh rate = pixel clock ÷ (total width × total height).

Example: standard 1920×1080 at 60 Hz has a total of 2200 × 1125 pixels per frame. 2200 × 1125 = 2,475,000 pixels, × 60 frames per second = 148,500,000 pixels per second, which is the familiar 148.5 MHz pixel clock. A 144 Hz mode needs more than twice that, which is why old cables, KVM switches and adapters limit high refresh rates.

Wayland: wlr-randr and video=

Wayland has no common tool like xrandr: each compositor has its own settings, and GNOME, for example, offers only the modes the kernel reports. On compositors that support the wlr output management protocol (Sway and other wlroots-based compositors), wlr-randr works much like xrandr:

wlr-randr
wlr-randr --output HDMI-A-1 --mode 2560x1440@59.951Hz
wlr-randr --output HDMI-A-1 --custom-mode 1280x1024@60Hz
wlr-randr --output eDP-1 --scale 1.5 --transform 90

For any compositor, including GNOME and KDE, you can make the kernel itself offer a mode with the video= kernel parameter, because Wayland compositors choose from the kernel's mode list. The desktop may still start in the mode saved in its own display settings, so pick the new mode there once it appears.

The video= kernel parameter

The format is video=<connector>:<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]. The useful letters are:

M
Calculate the mode with CVT instead of looking it up in the built-in table.
R
Use CVT reduced blanking (for digital displays).
e
Force the output on even if no monitor is detected; D also forces a digital signal on dual-signal ports.
d
Disable the output.

Examples:

video=HDMI-A-1:1920x1080@60
video=DP-1:2560x1440MR@60
video=eDP-1:d
video=HDMI-A-1:1920x1080@60,rotate=90

Options such as rotate=, panel_orientation= and margin_left= (for TV overscan) follow the mode after a comma. To test, press e in the GRUB menu and add the parameter to the linux line. To keep it on Debian and Ubuntu, add it to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub and run sudo update-grub; on Arch run sudo grub-mkconfig -o /boot/grub/grub.cfg. Fedora and RHEL use grubby. The kernel command-line HOWTO covers every boot loader.

Xorg makes its own choice. The Xorg server picks its starting mode itself, so on an X session use the xrandr or xorg.conf.d method above even if video= is set.

When the EDID is wrong

Cheap adapters, KVM switches, long cables and some TVs send no EDID or a damaged one. Symptoms: only 1024×768 is offered, the native resolution is missing, the kernel log says EDID checksum is invalid, or xrandr --addmode fails with BadMatch. Check the log first:

sudo journalctl -k | grep -i edid

The fix is to give the kernel a good EDID file:

  1. Get a correct EDID: copy /sys/class/drm/card1-HDMI-A-1/edid while the monitor is connected directly (without the faulty adapter), or from an identical working monitor.
  2. Save it as /usr/lib/firmware/edid/monitor.bin.
  3. Add drm.edid_firmware=HDMI-A-1:edid/monitor.bin to the kernel command line (without the connector prefix, the file applies to every connector).
  4. If the graphics driver loads from the initramfs (early KMS), include the file there too, for example with FILES=(/usr/lib/firmware/edid/monitor.bin) in /etc/mkinitcpio.conf on Arch or install_items+=" /usr/lib/firmware/edid/monitor.bin " in a file under /etc/dracut.conf.d/ on Fedora, then rebuild the initramfs.

For quick tests without rebooting, a kernel that is not in lockdown mode lets root write an EDID to the connector's edid_override file in debugfs, for example /sys/kernel/debug/dri/0/HDMI-A-1/edid_override (the directory name under dri/ varies by kernel and card), and trigger a re-probe with echo 1 > /sys/kernel/debug/dri/0/HDMI-A-1/trigger_hotplug. On many distributions, booting with Secure Boot turns lockdown on, which blocks this.

Mistakes to avoid

The classic XFree86 Video Timings HOWTO, written for CRT monitors, is kept by the Linux Documentation Project at tldp.org.

Sources