How to Set Up Multiple Monitors on Linux

Multiple monitors on Linux work reliably across both X11 and Wayland, but the tooling differs between the two display systems. On X11 you have xrandr for both detection and configuration; on Wayland that role is split between your compositor or desktop environment's settings panel and—where automation is needed—tools like wlr-randr or kanshi. This guide covers both paths and every practical variable: physical arrangement, scaling, refresh rates, and persistence across reboots.

Identify Your Display Server

Before touching any configuration, confirm which display server you are running. The method and tools differ completely.

echo $XDG_SESSION_TYPE

Output will be x11 or wayland. If it prints nothing, you may be in a TTY or an unusual session. You can also check loginctl show-session $(loginctl | awk 'NR==2{print $1}') -p Type.

X11: Configure Monitors with xrandr

xrandr ships with virtually every X11 desktop. No installation is needed on most systems, but if it is missing:

# Debian / Ubuntu
sudo apt install x11-xserver-utils

# Fedora / RHEL family
sudo dnf install xrandr

# Arch
sudo pacman -S xorg-xrandr

Detect Connected Displays

xrandr --query

This lists every output (HDMI-1, DP-1, eDP-1, etc.) with its current resolution, supported modes, and whether a monitor is connected. Note the exact output names—they vary by GPU and driver.

Set Arrangement, Resolution, and Refresh Rate

The core flags are --output, --mode, --rate, --pos (pixel position), and --primary. Place your secondary monitor to the right of the primary:

xrandr \
  --output eDP-1 --mode 1920x1080 --rate 60 --pos 0x0 --primary \
  --output HDMI-1 --mode 2560x1440 --rate 144 --pos 1920x0

The --pos values are pixel coordinates of the top-left corner of each screen. For a monitor above the primary use a negative or zero Y value accordingly. To place a monitor below, set its Y to the primary height (e.g., --pos 0x1080).

Scaling on X11

Scaling on X11 is awkward—it applies globally or per-output with --scale, but true per-monitor HiDPI mixing requires the --scale and --panning workaround. For a 4K monitor at 2× logical scaling alongside a 1080p display:

xrandr \
  --output eDP-1 --mode 1920x1080 --rate 60 --pos 0x0 --primary \
  --output DP-1  --mode 3840x2160 --rate 60 --scale 1x1 --pos 1920x0

Many users find it simpler to run the 4K panel at a lower resolution (e.g., 1920x1080) or use a desktop environment that handles DPI per-monitor in its own layer, such as GNOME or KDE on X11.

Make xrandr Settings Persistent

xrandr changes are session-only. To apply them on every login, add the command to your desktop autostart. The portable method is an autostart .desktop file:

mkdir -p ~/.config/autostart
cat > ~/.config/autostart/monitors.desktop << 'EOF'
[Desktop Entry]
Type=Application
Name=Monitor Setup
Exec=xrandr --output eDP-1 --mode 1920x1080 --rate 60 --pos 0x0 --primary --output HDMI-1 --mode 2560x1440 --rate 144 --pos 1920x0
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
EOF

Alternatively, place the xrandr call in ~/.xprofile (sourced by most display managers before the session starts) or ~/.xinitrc if you use startx.

Wayland: Configure Monitors in GNOME and KDE

On Wayland, compositors own the display stack. Direct hardware access from user-space tools like xrandr is not possible without compositor cooperation. Use the desktop settings panels for GUI configuration—these write persistent compositor configuration automatically.

GNOME (Mutter compositor)

Open Settings → Displays. Drag monitors to match physical layout. Set resolution and refresh rate per display. The "Scale" dropdown offers 100 %, 125 %, 150 %, 200 %. Fractional scaling (e.g., 125 %) must be enabled separately:

gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"

After setting this, the scale slider in Displays will show fractional steps. Restart the session for it to take effect. GNOME writes monitor configuration to ~/.config/monitors.xml—do not edit this by hand unless you know the schema.

KDE Plasma (KWin compositor)

Open System Settings → Display and Monitor. Drag and arrange monitors, set resolution, refresh rate, and per-display scale independently. KDE supports fractional scaling without extra flags. Settings are stored in ~/.config/kscreen/ as JSON. Changes apply immediately and persist across reboots.

Wayland: CLI Tools for Automation

If you run a tiling compositor (Sway, Hyprland, River) or need scripted display changes, GUI panels are unavailable. Use compositor-native config or standalone tools.

Sway (wlroots-based)

Declare outputs in ~/.config/sway/config:

output eDP-1 resolution 1920x1080 position 0,0 scale 1
output HDMI-A-1 resolution 2560x1440 position 1920,0 scale 1.25

Run swaymsg -t get_outputs to list output names under Sway. Reload with swaymsg reload.

wlr-randr (generic wlroots helper)

# Arch
sudo pacman -S wlr-randr

# Query outputs
wlr-randr

# Apply settings
wlr-randr --output HDMI-A-1 --mode 2560x1440@144Hz --pos 1920,0 --scale 1.25

kanshi (profile-based autoswitch)

kanshi watches for display hotplug events and applies the correct profile automatically—useful on laptops that dock and undock frequently.

# Arch
sudo pacman -S kanshi

# Debian / Ubuntu (may need backports or manual build)
sudo apt install kanshi

Create ~/.config/kanshi/config:

profile docked {
  output eDP-1 enable mode 1920x1080 position 0,0 scale 1
  output HDMI-A-1 enable mode 2560x1440@144Hz position 1920,0 scale 1.25
}

profile laptop {
  output eDP-1 enable mode 1920x1080 position 0,0 scale 1
}

Enable kanshi as a systemd user service so it starts with the session:

systemctl --user enable --now kanshi

Refresh Rates: What to Watch For

Both xrandr and Wayland tools only allow refresh rates the monitor reports as supported. If your target rate does not appear, check:

• Cable bandwidth: DisplayPort 1.2+ handles 4K@144 Hz; HDMI 2.0 caps at 4K@60 Hz; HDMI 2.1 raises that limit.
• GPU output capability: verify with xrandr --verbose (X11) or wlr-randr (Wayland) that the mode is listed.
• Custom modelines: On X11, add a mode not in the EDID with cvt and xrandr --newmode / --addmode. This is advanced and outside the scope of normal setups.

Verify the Configuration

On X11, confirm current state after applying settings:

xrandr --query

Each active output shows a * next to the current mode and a + next to the preferred mode. On Wayland/Sway:

swaymsg -t get_outputs

For GNOME Wayland, gnome-randr (install separately on older versions) or the Displays panel reflects live state. Check that each monitor reports the expected resolution, rate, and scale.

Troubleshooting

Monitor Not Detected

• Reseat the cable. Try a different port on the GPU.
• On X11: run xrandr --auto to force detection.
• On Nvidia proprietary driver + X11: use nvidia-settings GUI—xrandr may have limited write access depending on driver configuration.
• Check kernel messages for HPD (hot-plug detect) errors: sudo dmesg | grep -i drm.

Wrong Resolution or Blank Screen After Applying

• xrandr changes take effect immediately and can blank the screen if a mode is unsupported. Recovery: switch to another TTY (Ctrl+Alt+F3), log in, and run xrandr --auto or your working command.
• On Wayland/Sway, a bad output stanza in config prevents the compositor from starting; edit the config from a TTY.

Scaling Looks Blurry

• Non-integer scale factors (125 %, 150 %) require applications to support Wayland natively. XWayland clients are scaled by the XWayland server and can look soft. Set GDK_SCALE, QT_SCALE_FACTOR, or per-app environment variables if native scaling is unavailable.
• On X11, --scale uses bilinear interpolation and will look blurry. A native-resolution panel is always sharper than a scaled one.