i3 Screen Layout Profiles with xrandr Refresh Rates

Create reusable screen layout profiles for an i3 setup on Arch. This workflow keeps display switching separate from the main i3 setup by using xrandr scripts for laptop-only, external 1K, external 2K, and mirror modes. Each profile sets the expected refresh rate and can be checked with xrandr --current after switching.

Install required tools

Install xrandr for display detection and layout changes. Install xsetroot only if the main i3 setup has not already installed it for root background color.

sudo pacman -S xorg-xrandr xorg-xsetroot

Identify display outputs

Run xrandr from the current i3 session and note the connected output names. These names are used directly in the screen layout scripts.

xrandr | grep " connected"
xrandr

On this setup, the laptop panel appears as DP-2 when only the laptop screen is active. External outputs can appear as HDMI-0, DP-0, DP-1, or another driver-specific name depending on the cable, dock, GPU path, and monitor.

# Example laptop-only result
DP-2 connected primary 1920x1080+0+0

• connected means the output is detected by xrandr.
• primary means the output is the main screen for panels, bars, and workspace placement.
• The laptop panel name is not universal. On this machine it is DP-2, but other laptops may use eDP-1, eDP-1-1, or LVDS-1.
• Always confirm the external output name after connecting a new monitor or projector.

Create screen layout directory

Keep display profile scripts in ~/.screenlayout so they are easy to find, test, and bind from i3.

mkdir -p ~/.screenlayout

Create the laptop-only profile

The laptop-only profile is the safe default and recovery mode. It makes the DP-2 laptop panel primary at 1920x1080 and 144 Hz, then turns off known external outputs.

nano ~/.screenlayout/laptop-only.sh

#!/bin/bash

xrandr \
  --output DP-2 --primary --mode 1920x1080 --rate 144 \
  --output HDMI-0 --off \
  --output DP-0 --off \
  --output DP-1 --off

Create the external 1K profile

The external 1K profile is for normal 1920x1080 external monitors on HDMI-0 at 60 Hz. If HDMI-0 is not connected, it falls back to laptop-only.

nano ~/.screenlayout/external-1k-only.sh

#!/bin/bash

if xrandr | grep -q "^HDMI-0 connected"
then
    xrandr \
      --output HDMI-0 --primary --mode 1920x1080 --rate 60 \
      --output DP-2 --off
else
    ~/.screenlayout/laptop-only.sh
fi

Create the external 2K profile

The external 2K profile is for the office desk monitor on HDMI-0 at 2560x1440 and 74.93 Hz. If HDMI-0 is not connected, it falls back to laptop-only.

nano ~/.screenlayout/external-2k-only.sh

#!/bin/bash

if xrandr | grep -q "^HDMI-0 connected"
then
    xrandr \
      --output HDMI-0 --primary --mode 2560x1440 --rate 74.93 \
      --output DP-2 --off
else
    ~/.screenlayout/laptop-only.sh
fi

Create the mirror profile

The mirror profile is for presentations. Mirroring uses 1920x1080 at 60 Hz on both screens because projectors, TVs, meeting-room screens, and capture devices are more likely to support it.

nano ~/.screenlayout/mirror-1k.sh

#!/bin/bash

if xrandr | grep -q "^HDMI-0 connected"
then
    xrandr \
      --output DP-2 --primary --mode 1920x1080 --rate 60 \
      --output HDMI-0 --mode 1920x1080 --rate 60 --same-as DP-2
else
    ~/.screenlayout/laptop-only.sh
fi

Make profiles executable and test

Make all profile scripts executable. Run a profile, then use xrandr --current to verify the active mode and refresh rate. The active refresh rate is marked with *.

chmod +x ~/.screenlayout/laptop-only.sh
chmod +x ~/.screenlayout/external-1k-only.sh
chmod +x ~/.screenlayout/external-2k-only.sh
chmod +x ~/.screenlayout/mirror-1k.sh

~/.screenlayout/laptop-only.sh
xrandr --current

~/.screenlayout/external-1k-only.sh
xrandr --current

~/.screenlayout/external-2k-only.sh
xrandr --current

~/.screenlayout/mirror-1k.sh
xrandr --current

• If the external monitor is not connected, the external scripts fall back to laptop-only.
• If the external monitor appears under a different output name, replace HDMI-0 in the scripts with the detected output.
• Keep laptop-only as the default because it is the safest recovery mode after hibernate or monitor disconnects.

Check active refresh rates

Use focused checks when confirming a known profile. These commands show the connected output and the mode line where xrandr marks the active refresh rate.

# Laptop-only expected active marker:
# 1920x1080     60.00 + 144.00*
~/.screenlayout/laptop-only.sh
xrandr --current | grep -A1 "DP-2 connected"

# External 2K expected active marker:
# 2560x1440     59.95 +  74.93*
~/.screenlayout/external-2k-only.sh
xrandr --current | grep -A1 "HDMI-0 connected"

# External 1K expected active marker:
# 1920x1080     60.00*
~/.screenlayout/external-1k-only.sh
xrandr --current | grep -A1 "HDMI-0 connected"

# Mirror mode check
~/.screenlayout/mirror-1k.sh
xrandr --current | grep -E "DP-2 connected|HDMI-0 connected|1920x1080"

Add i3 startup and screen shortcuts

Add the laptop-only startup profile and screen profile shortcuts to ~/.config/i3/config. This keeps i3 startup safe while allowing manual switching to external-only or mirror mode.

nano ~/.config/i3/config

# Safe default display profile
exec --no-startup-id ~/.screenlayout/laptop-only.sh

# Recommended single-screen workspace mapping
workspace 1 output primary
workspace 2 output primary
workspace 3 output primary
workspace 4 output primary
workspace 5 output primary
workspace 6 output primary

# Screen profile shortcuts
bindsym $mod+Control+1 exec --no-startup-id ~/.screenlayout/laptop-only.sh
bindsym $mod+Control+2 exec --no-startup-id ~/.screenlayout/external-1k-only.sh
bindsym $mod+Control+3 exec --no-startup-id ~/.screenlayout/external-2k-only.sh
bindsym $mod+Control+4 exec --no-startup-id ~/.screenlayout/mirror-1k.sh

• No shortcut change is required if these bindings already exist.
• Mod+Control+1 forces laptop-only mode and is useful as a recovery shortcut after a bad resume or disconnected monitor.
• Mod+Control+2 switches to a 1920x1080 external-only profile at 60 Hz.
• Mod+Control+3 switches to a 2560x1440 external-only profile at 74.93 Hz.
• Mod+Control+4 switches to 1920x1080 mirror mode at 60 Hz for presentations.
• Avoid Mod+Shift+J, Mod+Shift+K, and Mod+Shift+L for screen modes because default i3 uses them for moving windows.

Reload i3 and verify keybindings

Reload i3 after editing the config. If i3 reports duplicate keybindings, search for the conflicting bindsym line and keep only one binding for that key combination.

i3-msg reload

grep -nE 'screenlayout|Control\+[1234]' ~/.config/i3/config

Daily screen profile shortcuts

Debug commands

# Monitor names, positions, modes, and refresh rates
xrandr --current
xrandr --current | grep " connected"

# Confirm screen layout scripts exist
ls -l ~/.screenlayout

# Test the safe laptop profile
~/.screenlayout/laptop-only.sh
xrandr --current | grep -A1 "DP-2 connected"

# Test an external profile after connecting the monitor
~/.screenlayout/external-1k-only.sh
xrandr --current | grep -A1 "HDMI-0 connected"

~/.screenlayout/external-2k-only.sh
xrandr --current | grep -A1 "HDMI-0 connected"

# Test mirror mode after connecting the monitor
~/.screenlayout/mirror-1k.sh
xrandr --current | grep -E "DP-2 connected|HDMI-0 connected|1920x1080"

# Check screen profile keybindings
grep -nE 'screenlayout|Control\+[1234]' ~/.config/i3/config

# Find duplicate keybindings manually if i3 reports a conflict
grep -n '^bindsym' ~/.config/i3/config

File locations

• i3 window manager config: ~/.config/i3/config
• Screen layout directory: ~/.screenlayout
• Laptop-only profile: ~/.screenlayout/laptop-only.sh
• External 1K profile: ~/.screenlayout/external-1k-only.sh
• External 2K profile: ~/.screenlayout/external-2k-only.sh
• Mirror presentation profile: ~/.screenlayout/mirror-1k.sh