xrandr

Related articles
Xorg
xrandr(1)
is an official configuration utility to the
RandR
(
Resize and Rotate
)
X Window System
extension. It can be used to set the size, orientation or reflection of the outputs for a screen. For configuring multiple monitors see the
Multihead
page.
Installation
Install
xorg-xrandr
.
Graphical front-ends
ARandR
— Simple visual front end for XRandR. Relative monitor positions are shown graphically and can be changed in a drag-and-drop way.
https://christian.amsuess.com/tools/arandr/
||
arandr
LXRandR
— Screen resolution and monitor position tool for LXDE. Also works in
Openbox
.
https://github.com/lxde/lxrandr
||
lxrandr
CLI front-ends
autorandr
— Automatically select a display configuration based on connected devices.
https://github.com/phillipberndt/autorandr
||
autorandr
xlayoutdisplay
— Detects and arranges displays. Handles: laptop lid state, highest available refresh rates, calculating and applying the actual DPI. Best used in .xinitrc, then can be invoked when plugging/unplugging monitors or closing laptop lid.
https://github.com/alex-courtis/xlayoutdisplay
||
xlayoutdisplay
AUR
Testing configuration
When run without any option,
xrandr
shows the names of different outputs available on the system (
VGA-1
,
HDMI-1
, etc.) and resolutions available on each, with a
*
after the current one and a
+
after the preferred one:
xrandr
Screen 0: minimum 320 x 200, current 3200 x 1080, maximum 8192 x 8192
VGA-1 disconnected (normal left inverted right x axis y axis)
HDMI-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 531mm x 299mm
   1920x1080     59.93 +  60.00*   50.00    59.94  
   1920x1080i    60.00    50.00    59.94  
   1680x1050     59.88  
…
Note
If your resolution is not present in the above list, see
#Adding undetected resolutions
You can use
xrandr
to set different resolution (must be present in the above list) on some output:
$ xrandr --output HDMI-1 --mode 1920x1080
When multiple refresh rates are present in the list, it may be changed by the
--rate
option, either at the same time or independently. For example:
$ xrandr --output HDMI-1 --mode 1920x1080 --rate 60
The
--auto
option will turn the specified output on if it is off and set the preferred (maximum) resolution:
$ xrandr --output HDMI-1 --auto
It is possible to specify multiple outputs in one command, e.g. to turn off
HDMI-1
and turn on
HDMI-2
with preferred resolution:
$ xrandr --output HDMI-1 --off --output HDMI-2 --auto
Note
Changes you make using
xrandr
will only last through the current session.
xrandr
has a lot more capabilities - see
xrandr(1)
for details.
Configuration
xrandr
is just a simple interface to the RandR extension and has no configuration file. However, there are multiple ways of achieving persistent configuration:
The RandR extension can be configured via
X configuration files
, see
Multihead#RandR
for details. This method provides only static configuration.
If you need dynamic configuration, you need to execute
xrandr
commands each time X server starts. See
Autostarting#On Xorg startup
for details. This method has the disadvantage of occurring fairly late in the startup process, thus it will not alter the resolution of the
display manager
if you use one.
Custom scripts calling
xrandr
can be bound to events (for example when external monitor is plugged in), see
udev
or
acpid
for details. The
#Scripts
section provides you with some example scripts that might be useful for this purpose.
Tip
Some display managers have startup scripts that are executed when X is initiated. For
SDDM
, this is done at
/usr/share/sddm/scripts/Xsetup
. This method requires root access and mucking around in system configuration files, but will take effect earlier in the startup process than using xprofile.
Scripts
Toggle external monitor
This script toggles between an external monitor (specified by
$extern
) and a default monitor (specified by
$intern
), so that only one monitor is active at a time.
The default monitor should be connected when running the script, which is always true for a laptop.
#!/bin/sh
intern=LVDS1
extern=VGA1

if xrandr | grep "$extern disconnected"; then
    xrandr --output "$extern" --off --output "$intern" --auto
else
    xrandr --output "$intern" --off --output "$extern" --auto
fi
Note
To leave the default monitor enabled when an external monitor is connected, replace the
else
clause with
xrandr --output "$intern" --primary --auto --output "$extern" --right-of "$intern" --auto
.
Manage 2-monitors
mons
AUR
is a POSIX-compliant shell script to quickly manage 2-monitor displays.
It provides well-known modes like computer, duplicate, extend and projector mode as well as selecting and positioning one or two monitors among those plugged in (for more details, see
mons
).
Avoid X crash with xrasengan
Use this workaround to turn on connected outputs that may be in suspend mode and hence shown as disconnected, as is often the case of DisplayPort monitors:
declare -i count=2
declare -i seconds=1

while ((count)); do
    xrandr >/dev/null
    sleep $seconds
    ((count--))
done
xrasengan
AUR
is an xrandr wrapper with this workaround built in.
$ xrasengan --force -on DisplayPort-0 -off HDMI-0
With the
--force
option,
xrasengan
will update status of all outputs before HDMI-0 is turned off, avoiding an X crash if they were the only connected/active outputs.
To force reload current settings,
xrasengan
provides a
--try-reload-active-layout
option, which uses
--force
and
unxrandr
from the
arandr
package to assemble the command line:
$ xrasengan --try-reload-active-layout
This can be used in systemd unit or in a keyboard binding to avoid blank screen when resuming DisplayPort monitors from suspend.
Configuration using arandr
arandr
can graphically arrange your monitors, change resolutions, and save a script to duplicate your setup. By default, if you "Save As" it will be saved in
~/.screenlayout/
. These files can then be
autostarted
. Sometimes problems arise from running the arandr script too soon after login, add a
sleep
command if needed.
Troubleshooting
Screen blinking
For some LCD screens (e.g. Samsung 2343NW, Acer XB280HK and Iiyama ProLite XUB3490WQSU-B1) the command
cvt -r
can be used to calculate standardized modelines with reduced blanking, allowing for higher frequency signals.
For example: an external monitor ProLite XUB3490WQSU-B1 connected to a Dell laptop through a Thunderbolt-HDMI 2.0 adapter, using 59.97Hz refresh rate with a blinking problem:
Calculating the reduced modelines for the desired resolution 3440x1440 gives:
cvt -r 3440 1440
# 3440x1440 59.97 Hz (CVT) hsync: 88.82 kHz; pclk: 319.75 MHz
Modeline "3440x1440R"  319.75  3440 3488 3520 3600  1440 1443 1453 1481 +hsync -vsync
With this information we can use xrandr to create a new mode:
$ xrandr --newmode "3440x1440R"  319.75  3440 3488 3520 3600  1440 1443 1453 1481 +hsync -vsync
And add it to the set of valid modes for the corresponding output to make it selectable:
$ xrandr --addmode DP1 3440x1440R
Adding undetected resolutions
Due to buggy hardware or drivers, your monitor's correct resolutions may not always be detected by xrandr. For example, the EDID data block queried from the monitor may be incorrect. To fix this at a low level, see
Kernel mode setting#Forcing modes and EDID
. This section will describe how to address this at a higher level by adding the desired resolutions to xrandr. This same procedure can be used to add refresh rates you know are supported, but not enabled by your driver.
First we run
gtf
or
cvt
to get the
Modeline
for the resolution we want:
$ 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
Tip
If you find that the screen goes blank when the modeline is applied, try lower refresh rate (e.g. 30 or 45 instead of 60). The refresh rate should be passed as the third argument:
cvt 2560 1440 45
.
Note
If the Intel video driver (
xf86-video-intel
) is used, it may report the desired resolution along with its properties in
/var/log/Xorg.0.log
— use that first if it is different from the output of
gtf
or
cvt
. For instance, the log and its use with xrandr:
[    45.063] (II) intel(0): clock: 241.5 MHz   Image Size:  597 x 336 mm
[    45.063] (II) intel(0): h_active: 2560  h_sync: 2600  h_sync_end 2632 h_blank_end 2720 h_border: 0
[    45.063] (II) intel(0): v_active: 1440  v_sync: 1443  v_sync_end 1448 v_blanking: 1481 v_border: 0
$ xrandr --newmode "2560x1440" 241.50 2560 2600 2632 2720 1440 1443 1448 1481 -hsync +vsync
An example for the AMDGPU video driver (
xf86-video-amdgpu
):
[    95.798] (II) AMDGPU(0): Printing DDC gathered Modelines:
[    95.798] (II) AMDGPU(0): Modeline "1920x1080"x0.0  148.50  1920 2008 2052 2200  1080 1084 1089 1125 +hsync +vsync (67.5 kHz eP)
$ xrandr --newmode "1920x1080"x0.0  148.50  1920 2008 2052 2200  1080 1084 1089 1125 +hsync +vsync
Then we create a new xrandr mode. Note that the Modeline keyword needs to be omitted.
$ xrandr --newmode "1280x1024_60.00"  109.00  1280 1368 1496 1712  1024 1027 1034 1063 -hsync +vsync
Tip
Some programs have trouble recognizing modes labeled with "_60.00" see
[1]
After creating it we need an extra step to add this new mode to our current output (VGA1). We use just the name of the mode, since the parameters have been set previously.
$ xrandr --addmode VGA1 1280x1024_60.00
Now we change the resolution of the screen to the one we just added:
$ xrandr --output VGA1 --mode 1280x1024_60.00
Note that these settings only take effect during this session. See
Autostarting#On Xorg startup
for a way to automatically apply them on startup.
If you are not sure about the resolution you will test, you may add a
sleep 5
and a safe resolution command line following, like this:
$ xrandr --output VGA1 --mode 1280x1024_60.00 && sleep 5 && xrandr --newmode "1024x768-safe" 65.00 1024 1048 1184 1344 768 771 777 806 -HSync -VSync && xrandr --addmode VGA1 1024x768-safe && xrandr --output VGA1 --mode 1024x768-safe
Also, change
VGA1
to correct output name.
EDID checksum is invalid
If the previous method results in an
*ERROR* EDID checksum is invalid
error during boot, see
KMS#Forcing modes and EDID
and
[2]
.
Or
xrandr --addmode
might give you the error
X Error of failed request: BadMatch
. NVIDIA users should read
NVIDIA/Troubleshooting#xrandr BadMatch
.
BadMatch
could indicate an invalid EDID checksum. To verify that this is the case, run X in verbose mode (e.g.
startx -- -logverbose 6
) and check your Xorg log for messages about a bad EDID.
Screen resolution reverts back after a blink
If you use
GNOME
and your monitor does not have an EDID, above
#Adding undetected resolutions
might not work, with your screen just blinking once, after
xrandr --output
.
Poke around with
~/.config/monitors.xml
, or delete the file completely, and then reboot.
It is better explained in
this
article.
Permanently adding undetected resolutions
Once a suitable resolution is found using
xrandr
, the mode can be permanently added by creating an entry in
/etc/X11/xorg.conf.d/
:
/etc/X11/xorg.conf.d/10-monitor.conf
Section "Monitor"
    Identifier "VGA1"
    Modeline "1280x1024_60.00"  109.00  1280 1368 1496 1712  1024 1027 1034 1063 -hsync +vsync
    Option "PreferredMode" "1280x1024_60.00"
EndSection

Section "Screen"
    Identifier "Screen0"
    Monitor "VGA1"
    DefaultDepth 24
    SubSection "Display"
        Modes "1280x1024_60.00"
    EndSubSection
EndSection

Section "Device"
    Identifier "Device0"
    Driver "intel"
EndSection
Replace
intel
with the right driver, e.g.
nvidia
. When the X server is restarted, you should be able to set the new resolution.
If this does not work for you, try removing the Screen and Device sections and just leaving the Monitor section.
[3]
Resolution lower than expected
Tip
Try
#Adding undetected resolutions
first, if it does not work, you may try this method.
If your video card is recognized but the resolution is lower than you expect, you may try this.
Background: ATI X1550 based video card and two LCD monitors DELL 2408(up to 1920x1200) and Samsung 206BW(up to 1680x1050). Upon first login after installation, the resolution default to 1152x864. xrandr does not list any resolution higher than 1152x864. You may want to try editing /etc/X11/xorg.conf, add a section about virtual screen, logout, login and see if this helps. If not then read on.
Change xorg.conf
/etc/X11/xorg.conf
Section "Screen"
        ...
        SubSection "Display"
                Virtual 3600 1200
        EndSubSection
EndSection
About the numbers: DELL on the left and Samsung on the right. So the virtual width is of sum of both LCD width 3600=1920+1680; Height then is figured as the max of them, which is max(1200,1050)=1200. If you put one LCD above the other, use this calculation instead: (max(width1, width2), height1+height2).
Setting resolution from .xinitrc doesn't work
DDX
drivers other than that of the
modesetting(4)
driver may take time to properly enumerate the modes of attached devices, to where xrandr may not work right away. This seems to be the case for the
xf86-video-intel
driver, with which using xrandr early in the startup sets the incorrect resolution. Possible remedies include:
Waiting for a couple of seconds before invoking xrandr:
~/.xinitrc
...
{ sleep 2; xrandr
xrandr_parameters
} &
...
This does the waiting in the background, as to not block the rest of the startup. If this not desirable, e.g. your window manager configuration depends on the display being arranged correctly, you can execute the commands in the foreground:
~/.xinitrc
...
sleep 2
xrandr
xrandr_parameters
...
Setting the mode in a later part of the desktop startup. Refer to your window manager documentation for details on startup script functionality.
Switching to the generic modesetting driver. This is most easily done by uninstalling the device specific DDX driver. In the case of
xf86-video-intel
, the driver has other deficiencies that may benefit from this; see
Intel graphics#Installation
for more information.
Correction of overscan tv resolutions via the underscan property
With a flat panel TV,
overscan
looks like the picture is "zoomed in" so the edges are cut off.
Check your TV if there is a parameter to change. If not check if the output has support for the underscan property (xrandr --prop), if so apply an
underscan
and change border values. 
The required
underscan vborder
and
underscan hborder
values can be different for you, just check it and change it by more or less.
$ xrandr --output HDMI-0 --set underscan on --set "underscan vborder" 25 --set "underscan hborder" 40
Correction of overscan tv resolutions via --transform
If underscan is not available another solution is using
xrandr --transform
a,b,c,d,e,f,g,h,i
, which applies a transformation matrix on the output. See the
xrandr(1) § RandR_version_1.3_options
manual page for the explanation of the transformation.
For example, the transformation scaling horizontal coordinates by
0.8
, vertical coordinates by
1.04
and moving the screen by 35 pixels right and 19 pixels down, is:
$ xrandr --output HDMI1 --transform 0.80,0,-35,0,1.04,-19,0,0,1
Disabling phantom monitor
In some cases, a non-existent monitor may be detected by the system. To disable it, find the name of the phantom output, e.g. VGA1, and turn it off with
$ xrandr --output VGA1 --off
To make this permanent, add the following to an entry in
/etc/X11/xorg.conf.d/
:
/etc/X11/xorg.conf.d/10-monitor.conf
Section "Monitor"
    Identifier "VGA1"
    Option "Ignore" "true"
EndSection
Dynamic interlace pattern artifacts with AOC G2590PX
If you are seeing very prominent
interlace pattern artifacts
(mesh or grid) when you see movement on the screen with this monitor, it might be happening because of a low refresh rate. Switching to a higher refresh rate (from 60 Hz to 119.98 Hz and perhaps even higher) might help reduce the effect.
Sample xrandr output for this monitor over HDMI:
HDMI-1 connected 1920x1080+0+0 (normal left inverted right x axis y axis) 544mm x 303mm
   1920x1080     60.00 + 119.98*   99.93    50.00    59.94
As can be seen in the output above, the preferred refresh rate reported by xrandr is 60.00, but the artifacts are very visible with this refresh rate. Switching to 119.98 should help reduce the effect considerably.
$ xrandr --output HDMI-1 --mode 1920x1080 --rate 119.98
See also
https://wiki.ubuntu.com/X/Config/Resolution
Debian Wiki - RandR 1.2 tutorial
Xorg RandR 1.2 on ThinkWiki
Obtaining modelines from Windows program PowerStrip