Tutorial on xrandr

The xrandr (short for X Resize, Rotate and Reflect) command is a powerful utility in Linux for managing display outputs on systems using the X Window System. It lets you configure screen resolution, orientation, mirroring, and multi-monitor layouts.

Basic Syntax

xrandr [options] --output <display_name> [commands]

• --output: Specifies which display you're targeting
• commands: Actions like setting resolution, position, turning display on/off, mirroring, etc.

View Connected Displays

xrandr

This will list all available display outputs, their connection status, current resolution, and supported modes.

Example output:

eDP-1 connected primary 1920x1080+0+0
HDMI-1 connected 1920x1080+1920+0
DP-1 disconnected

Common Display Configuration Tasks

Identify Display Names

Run xrandr with no arguments to identify the names of connected displays (eDP-1, HDMI-1, DP-1, etc.).

Enable and Position Displays

Turn On a Display

xrandr --output HDMI-1 --auto

The --auto flag enables the display with its preferred resolution.

Place One Display Relative to Another

Example – Place HDMI-1 to the left of eDP-1:

xrandr --output HDMI-1 --auto --left-of eDP-1

Mirror a Display

To mirror HDMI-1 to show the same content as eDP-1:

xrandr --output HDMI-1 --mode 1920x1080 --same-as eDP-1

Both displays must support the same resolution to mirror successfully. You may need to manually match them.

Manually Set Screen Layout

You can position each display using pixel coordinates with --pos.

xrandr --output eDP-1 --mode 1920x1080 --pos 0x0 \
       --output HDMI-1 --mode 1920x1080 --pos 1920x0

This places HDMI-1 to the right of eDP-1, starting at pixel 1920x0.

Rotate Display Orientation

xrandr --output HDMI-1 --rotate left   # 90 degrees
xrandr --output HDMI-1 --rotate right  # -90 degrees
xrandr --output HDMI-1 --rotate normal # Default
xrandr --output HDMI-1 --rotate inverted

Useful for rotating portrait/landscape external monitors.

Turn Off a Display

xrandr --output HDMI-1 --off

This disables the display entirely.

Set Resolution

List available resolutions:

xrandr

Set a specific resolution:

xrandr --output HDMI-1 --mode 1280x720

Add a Custom Resolution

Sometimes your monitor supports a resolution not detected by xrandr. You can add it manually:

1. Generate a modeline using cvt:

bash cvt 1920 1080

2. Create a new mode:

bash xrandr --newmode "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync

3. Add mode to output:

bash xrandr --addmode HDMI-1 "1920x1080_60.00"

4. Apply it:

bash xrandr --output HDMI-1 --mode "1920x1080_60.00"

Example Multi-Display Setup

xrandr \
  --output eDP-1 --mode 1920x1080 --primary --pos 0x0 \
  --output HDMI-1 --mode 1920x1080 --right-of eDP-1

This sets up a dual-display layout with HDMI-1 to the right of your laptop screen.

Reset to Single Display (Laptop Only)

xrandr --output eDP-1 --auto --primary \
       --output HDMI-1 --off \
       --output DP-1 --off

Helpful Tips

• If your GUI display is messed up, run xrandr from a virtual terminal (Ctrl+Alt+F2) and fix it manually.
• You can create a startup script with your desired layout and set it to run at login.
• Combine with arandr (a graphical frontend to xrandr) to generate scripts.