xrandr

Display the current state of the system (known screens, resolutions, ...)

$ xrandr [[-q|--query]]

$ xrandr --auto

$ xrandr --output DP1 --mode 1920x1080 [[-r|--rate]] 60

$ xrandr --output HDMI2 --mode 1280x1024 --right-of DP1

$ xrandr --output VGA1 --off

$ xrandr --output LVDS1 --brightness 0.5

$ xrandr [[-d|--display]] :[0] [[-q|--query]]

xrandr [options]

-q, --query
    Queries the current state of the RandR extension, showing detected outputs, their connected status, and available modes.

--output <output>
    Selects a specific display output to configure (e.g., HDMI-1, DP-1, eDP-1).

--mode <mode>
    Sets the resolution for the specified output (e.g., 1920x1080). The mode must be supported by the output.

--rate <rate>
    Sets the refresh rate in Hz for the specified output and mode (e.g., 60).

--pos <x>x<y>
    Positions the output's top-left corner at the specified pixel coordinates relative to the screen's top-left.

--auto
    Automatically configures the output to its preferred mode and turns it on.

--off
    Turns off the specified output, disabling the display.

--primary
    Designates the specified output as the primary display.

--left-of <other_output>
    Positions the output to the left of other_output.

--right-of <other_output>
    Positions the output to the right of other_output.

--above <other_output>
    Positions the output above other_output.

--below <other_output>
    Positions the output below other_output.

--rotate <normal|left|right|inverted>
    Rotates the display output by 90, 180, or 270 degrees. normal is the default orientation.

--reflect <x|y|xy>
    Reflects the display output along the X, Y, or both axes.

--newmode <name> <modeline>
    Adds a new display mode. modeline values can be generated by tools like cvt or gtf.

--addmode <output> <name>
    Adds a previously defined custom mode (using --newmode) to a specific output.

--delmode <output> <name>
    Deletes a mode from an output. Useful for removing custom modes.

--dryrun
    Performs all actions internally but does not apply them, only prints what would happen.

xrandr is a command-line utility used to query, configure, and manipulate the X server's RandR (Resize and Rotate) extension. It allows users to control various aspects of their display setup, including screen resolution, refresh rate, rotation, reflection, and the arrangement of multiple monitors, all without requiring a restart of the X server. This makes it an indispensable tool for managing external displays, projectors, and adapting to different display modes on Linux desktop environments. Whether you need to connect a second monitor, change your laptop's native resolution, or orient a screen for a specific purpose, xrandr provides the flexibility to achieve these configurations on-the-fly. It queries available outputs (e.g., HDMI-1, DP-1), supported modes, and their current status, then applies desired settings.

xrandr operates on the X server and requires it to be running. Permissions issues can arise if not run with appropriate display access. Not all graphics drivers fully support every RandR feature; some operations (e.g., specific rotations or reflections) might not be available or function correctly depending on your hardware and driver. Changes made with xrandr are typically session-specific and will revert upon restarting the X server or rebooting the system unless persisted through a display manager configuration or startup script.

Changes made with xrandr are generally temporary and only apply to the current X session. To make configuration permanent, commands must be added to a startup script that runs after the X server starts, such as ~/.xprofile, a desktop environment's autostart mechanism, or system-wide Xorg configuration files (e.g., /etc/X11/xorg.conf.d/).

When an unsupported resolution or refresh rate is needed, xrandr allows adding 'modelines' via --newmode. These modelines are precise timing parameters for the display, typically generated by utilities like cvt or gtf. For example, cvt 1920 1080 60 would provide the modeline for a 1920x1080 @ 60Hz display.

The RandR (Resize and Rotate) extension for the X Window System was introduced to provide dynamic configuration capabilities for displays, moving beyond the static xorg.conf setup. xrandr is the command-line interface to this extension, evolving over time with the X.Org server to support more complex multi-monitor setups, hot-plugging, and advanced display manipulations. Its development has focused on enhancing user experience by allowing on-the-fly display adjustments without requiring system restarts.

Xorg(1), cvt(1), gtf(1), xinit(1), randr(3)