Safely Inspect and Arrange Displays with xrandr

You will use xrandr to identify the outputs on an X11 session, preview a display layout, then apply a small, reversible arrangement such as putting an external monitor to the right of a laptop panel. The examples use xrandr 1.5.2 from Debian package x11-xserver-utils version 7.7+10build2.

Allow about ten minutes. You need a running X display and permission to use it. These commands normally run as your desktop user; do not use sudo. A root shell usually has the wrong DISPLAY and X authorisation, and it does not make a disconnected monitor appear.

1. Confirm the installed command

Check the binary and version first. This is read-only and does not contact the X server for the query that reports the program version:

$ command -v xrandr
/usr/bin/xrandr
$ xrandr --version
xrandr program version       1.5.2

The package version and program version are different things. Record both when reporting a problem:

$ dpkg-query -W -f='${Package} ${Version}\n' x11-xserver-utils
x11-xserver-utils 7.7+10build2

If xrandr --version prints an X display error before the version, that is still useful: the executable is present, but the current shell cannot reach an X server. Fix the session or DISPLAY before continuing.

2. Inventory outputs and modes

Run the query without changing anything:

$ xrandr --query
Screen 0: minimum 320 x 200, current 3840 x 2160, maximum 16384 x 16384
eDP-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 309mm x 174mm
   1920x1080     60.01*+  48.01
HDMI-1 disconnected (normal left inverted right x axis y axis)

Your names, dimensions and rates will differ. A line containing connected gives an output name. The asterisk marks the current mode and the plus sign marks the preferred mode. A disconnected output can still be named in the output list, but enabling it will fail until hardware and the X driver report it as connected.

For more detail, use --verbose or --prop. The verbose output includes properties and progress information, but gamma and brightness values are only approximations of the complete colour profile:

$ xrandr --current
Screen 0: ...
eDP-1 connected primary ...

--current asks for the current configuration without polling for hardware changes. Use ordinary --query when you have just plugged in a cable and want a fresh view.

3. Prepare a dry run

Choose exact output names from your own query. In the following example, replace eDP-1 and HDMI-1; do not guess names from the connector or laptop model. The --dryrun option performs the requested actions without making changes:

$ xrandr --dryrun \
    --output eDP-1 --auto --pos 0x0 \
    --output HDMI-1 --auto --right-of eDP-1

There may be no output on success. Check the exit status immediately:

$ printf 'dry-run status: %s\n' "$?"
dry-run status: 0

A zero status means xrandr accepted the request as a dry run. It does not prove that the physical monitor is connected or that every driver will accept the real change. A non-zero status is a reason to stop and inspect the output name, connection state and requested mode.

4. Apply a basic two-display layout

When the dry run is sensible, repeat the command without --dryrun. This changes the live X screen but does not edit a persistent configuration file:

$ xrandr \
    --output eDP-1 --auto --pos 0x0 \
    --output HDMI-1 --auto --right-of eDP-1

--auto enables a connected but disabled output at its first preferred mode, or a mode near 96 DPI if no preferred mode exists. It disables an output that is enabled but now disconnected. The relative placement options include --left-of, --right-of, --above, --below and --same-as.

Verify the resulting geometry rather than trusting the command's lack of output:

$ xrandr --query
Screen 0: ...
eDP-1 connected primary 1920x1080+0+0 ...
HDMI-1 connected 2560x1440+1920+0 ...

The position after the mode, such as +1920+0, is the output's top-left coordinate in the X screen. The second output can be taller or shorter; xrandr is arranging pixels, not making physical monitor edges line up automatically.

5. Select a known mode or refresh rate

Use a mode printed under the output you are changing. For example, if the query lists 2560x1440, request it explicitly and optionally prefer a nearby refresh rate:

$ xrandr --output HDMI-1 --mode 2560x1440 --rate 60

The mode name can be a name or XID. The rate is a preference when several modes have the same name, so the selected rate may be the nearest available value rather than an exact match. Confirm it with a new query and look for the asterisk on the selected line.

If a requested mode is absent, do not immediately invent a modeline. A modeline supplied with --newmode is interpreted using Xorg ModeLine syntax and must then be attached with --addmode; it can be rejected by the output, driver or monitor. Restore the previous layout first, then investigate the monitor's documented timings.

6. Recover from a bad layout

Keep the original query output or note the old positions and modes before changing them. A simple recovery is to put the primary output back at 0x0, select its preferred mode, and disable the external output:

$ xrandr \
    --output eDP-1 --auto --pos 0x0 \
    --output HDMI-1 --off

Replace those names with the outputs from your machine. --off is a live change, so do not use it on an output that is carrying the only screen you can currently see unless you have another route back in. If the command makes the desktop hard to use, wait for the display manager or desktop environment to restore its policy, switch to a local text console, or reconnect through an already authorised session and run the recovery command.

Do not confuse this runtime arrangement with persistence. xrandr changes the current X server state. A desktop environment, login session, display manager or a user startup script may apply a different layout later. Find that policy only after the manual command works and you are ready to change the correct session configuration.

Common traps

• No display: "Can't open display" means the shell cannot reach the X server. Check printf '%s\n' "$DISPLAY" and run as the logged-in desktop user.
• Wrong protocol assumptions: the older --size, --rate and orientation options are RandR 1.1 options. Do not mix them with RandR 1.2 output options in one command.
• Unexpected screen size: without --fb, xrandr computes the smallest framebuffer that contains the configured outputs. Use an explicit framebuffer only when you understand the required panning or desktop area.
• Brightness confusion: --brightness is a software multiplication of gamma values, not necessarily a hardware backlight setting. It is also not a colour-profile editor.
• Position cycles: do not express a circular relationship such as output A left of B and B left of A. Relative positions are computed against the other output's new position.