autorandr

Save the current screen layout

$ autorandr [[-s|--save]] [profile_name]

$ autorandr

$ autorandr [[-c|--change]]

$ autorandr [[-l|--load]] [profile_name]

$ autorandr [[-d|--default]] [profile_name]

autorandr [OPTIONS] [PROFILE]

-h, --help
    Show help message and exit.

-c, --cycle
    Cycle through available profiles based on the current setup.

-s, --save PROFILE
    Save the current display setup as a new PROFILE.

-l, --load PROFILE
    Load and apply the specified PROFILE.

-d, --detect
    Detect connected outputs and load the most suitable profile. (Default action).

-w, --wait-delay DELAY
    Wait DELAY seconds for outputs to settle before detection.

-m, --match-closest
    Load the closest matching profile, even if output names differ.

-f, --force
    Force application of a profile, even if it seems unnecessary.

-r, --resume
    Resume the last used profile.

-L, --list
    List all saved display profiles.

-D, --delete PROFILE
    Delete the specified PROFILE.

-u, --unplug PROFILE
    Mark a profile as unplugged (relevant for automatic detection logic).

-S, --switch-layout
    Switch keyboard layout using setxkbmap when applying a profile.

-v, --version
    Show program's version number and exit.

--current
    Show the name of the currently active profile.

--default PROFILE
    Set the default profile to be loaded if no match is found.

--change-timeout SECONDS
    Set the detection timeout for display change events.

--dry-run
    Don't apply changes, just show what autorandr would do.

--ignore-lid
    Ignore the laptop lid state when detecting profiles.

--power-on-connected
    Attempt to power on connected but currently off outputs.

--dont-power-off-disconnected
    Do not power off outputs that become disconnected.

--dont-suspend-unconnected
    Do not suspend outputs that are no longer connected.

--dont-change-primary
    Do not alter the primary display setting.

--verbose
    Print verbose output for debugging.

--debug
    Print extensive debug output.

--hook-dir DIR
    Specify an alternative directory for profile hooks.

--run-hooks
    Explicitly run hooks for the current profile without changing the display.

--config-dir DIR
    Specify an alternative configuration directory.

--recurse
    Recursively apply profiles, useful for nested display setups.

--skip-missing-outputs
    Do not fail if some configured outputs are missing.

--skip-unconfigured-outputs
    Do not modify outputs that are not part of the loaded profile.

autorandr is a command-line utility for Linux that intelligently adjusts XRandR display configurations based on connected outputs. It allows users to save various display profiles (e.g., laptop only, external monitor, projector setup) and automatically loads the most suitable one when display hardware changes are detected. This eliminates the need for manual configuration with xrandr every time a monitor is plugged in or unplugged, significantly simplifying multi-monitor management for mobile users. Beyond simple detection, it supports hooks to run custom scripts before or after a profile is applied, enabling further automation like wallpaper changes or keyboard layout adjustments.

autorandr relies on the X server being active and the xrandr utility. It might require integration with system services (e.g., systemd user units) or desktop environment startup scripts for seamless automatic detection and application on display events. Rapid changes in display states can sometimes confuse its detection logic.

autorandr supports powerful pre-switch and post-switch hook scripts, located within profile subdirectories (e.g., ~/.config/autorandr/profiles/PROFILE/pre-switch). These scripts execute before and after a profile is applied, enabling custom actions like setting wallpaper, adjusting keyboard layouts, or launching applications specific to a display setup.

When run without arguments (e.g., simply autorandr), the command automatically attempts to detect the current display hardware and loads the best-matching saved profile. This behavior is crucial for integrating it into system event triggers.

For full automation, autorandr is often integrated with system-level event handling, such as udev rules for display hot-plugging, or configured as a systemd user service that triggers on relevant display changes. Desktop environment startup scripts can also run autorandr --detect.

autorandr emerged to address the common pain point of manual xrandr scripting for mobile Linux users frequently connecting to different display setups. It was developed to automate the detection and application of display configurations, building upon the capabilities of the X RandR extension. Its focus on simplicity and extensibility through hooks has made it a popular choice in the Linux community for dynamic multi-monitor management.

xrandr(1), arandr(1), randr(7)