A simple, reliable bash script to manage dual-monitor configurations using xrandr.

This script automatically detects connected displays (for example, a laptop’s internal screen and an external monitor) and lets you switch between multiple layout modes: primary, secondary, clone, and various dual configurations (left, right, top, bottom).

You can install this script system-wide or in your home directory.

curl -o ~/bin/monitors \
  https://raw.githubusercontent.com/sepen/monitors/refs/heads/main/monitors
chmod +x ~/bin/monitors
export PATH="$HOME/bin:$PATH"

sudo curl -o /usr/local/bin/monitors \
  https://raw.githubusercontent.com/sepen/monitors/refs/heads/main/monitors
sudo chmod +x /usr/local/bin/monitors

• Automatically detects connected monitors via xrandr
• Supports multiple configurations:
  • primary – use internal screen only
  • secondary – use external screen only
  • clone – mirror displays
  • dual-left / dual-right / dual-top / dual-bottom – position screens relative to each other
• Checks for required dependencies before running
• Includes dry-run mode (--dry-run) for safe testing
• Automatically reloads wallpaper if using feh
• Handles missing or single-monitor setups gracefully

• Linux with xrandr (part of xorg-xrandr)
• bash 4 or newer
• Optional:
  • feh for reloading wallpapers after screen layout changes

monitors [config] [--dry-run]

Available configurations:
  internal      Use only the internal display as primary.
  external      Use only the external display as primary.
  clone         Mirror internal and external displays.
  dual-left     Place external display to the left of internal.
  dual-right    Place external display to the right of internal.
  dual-top      Place external display above internal.
  dual-bottom   Place external display below internal.

Options:
  --dry-run     Show xrandr commands without executing them

Extend display to the right:

monitors dual-right
[+] Detected monitors:
    internal = eDP-1
    external = HDMI-1
[+] Selected mode: dual-right
[+] Applying display configuration...
[+] Reloading wallpaper...
[+] Done!

Test without applying:

monitors dual-right --dry-run
[+] Detected monitors:
  internal = LVDS1
  external = VGA1
[+] Selected mode: dual-right
Dry run: xrandr --output LVDS1 --primary --auto --output VGA1 --auto --right-of LVDS1
[+] Reloading wallpaper...
[+] Done!

• The first connected output is treated as the internal display (e.g., eDP-1).
• The second output is the external display (e.g., HDMI-1).
• If only one display is detected, the script automatically falls back to primary mode.
• If more than two displays are connected, only the first two detected are used.

• Uses standard Linux CLI tools: xrandr, grep, awk.
• Uses set -euo pipefail for safety (exits on errors, undefined variables, or failed pipes).
• Uses clear logging with colored output for better readability.
• Compatible with most desktop environments (GNOME, XFCE, i3, sway-xwayland, etc.).
• Does not persist configuration changes; settings last until reboot or logout.

If you use feh to manage wallpapers, the script automatically reloads your previous wallpaper from ~/.fehbg after changing the monitor layout.

To set up feh initially:

feh --bg-scale ~/Pictures/wallpaper.jpg

Possible future additions:

• Configuration caching (for example, remembering the last used layout).
• Automatically switch between internal-only and dual-monitor when a monitor is plugged in or unplugged.
• notify-send support – show a desktop notification when mode changes.

MIT License
© 2025 Jose Beneyto

Pull requests and suggestions are welcome.
If you find a bug or have an idea for improvement, please open an issue or submit a contribution.