Back to Commands

xrandr

systemLinux/Unix
The xrandr command is one of the most frequently used commands in Linux/Unix-like operating systems. xrandr Command line interface to X RandR extension for screen resolution and display configuration
See ExamplesView Syntax

Quick Reference

Command Name:

xrandr

Category:

system

Platform:

Linux/Unix

Basic Usage:

xrandr [options] [arguments]

Common Use Cases

    Syntax

    xrandr [options] [--output output] [output-options]

    Options

    General Options

    Option Description
    --verbose Display detailed information
    --dryrun Test the configuration without applying it
    --screen <screen> Select which X screen to use
    --q, --query Display current state (the default)
    --version Display the version of xrandr

    Output Options

    Option Description
    --output <output> Specify which output to configure
    --auto Automatically configure the specified output with preferred mode
    --mode <mode> Specify the mode (resolution) to use
    --rate <rate>, --refresh <rate> Specify the refresh rate to use
    --pos <x>x<y> Specify absolute position of the output
    --rotate <rotation> Specify the rotation (normal, left, right, inverted)
    --reflect <reflection> Specify the reflection (normal, x, y, xy)
    --primary Set this output as the primary display
    --off Disable the specified output
    --crtc <crtc> Specify the CRTC to use
    --panning <w>x<h>[+<x>+<y>[/<track:w>x<h>+<x>+<y>[/<border:l,t,r,b>]]] Set panning parameters
    --scale <x>x<y> Set output scaling factors
    --transform <a,b,c,d,e,f,g,h,i> Set transformation matrix
    --filter <nearest|bilinear> Set scaling filter

    Relative Position Options

    Option Description
    --left-of <output> Place this output to the left of another output
    --right-of <output> Place this output to the right of another output
    --above <output> Place this output above another output
    --below <output> Place this output below another output
    --same-as <output> Make this output a clone of another output

    Mode Management Options

    Option Description
    --fb <width>x<height> Set screen size (framebuffer)
    --fbmm <width>x<height> Set physical screen size in mm
    --dpi <dpi> Set screen DPI
    --newmode <name> <clock> <hdisp> <hsync-start> <hsync-end> <htotal> <vdisp> <vsync-start> <vsync-end> <vtotal> [flags...] Add a new mode (custom resolution)
    --rmmode <name> Remove a mode
    --addmode <output> <name> Add a mode to an output's available modes
    --delmode <output> <name> Remove a mode from an output's available modes

    Examples

    How to Use These Examples

    The examples below show common ways to use the xrandr command. Try them in your terminal to see the results. You can copy any example by clicking on the code block.

    # Basic Examples Basic
    # Show current state of displays xrandr
    # Show verbose information xrandr --verbose
    # Set a specific resolution for a display xrandr --output HDMI-1 --mode 1920x1080
    # Change screen orientation to landscape xrandr --output HDMI-1 --rotate normal
    # Advanced Examples Advanced
    # Set up dual monitors, with one to the right of the other xrandr --output HDMI-1 --auto --output DP-1 --auto --right-of HDMI-1 # Set up a display with a specific refresh rate xrandr --output HDMI-1 --mode 1920x1080 --rate 60 # Configure a display as primary xrandr --output HDMI-1 --primary # Mirror displays xrandr --output HDMI-1 --auto --output DP-1 --auto --same-as HDMI-1 # Disable a display xrandr --output DP-1 --off # Set custom resolution xrandr --newmode "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync xrandr --addmode DP-1 "1920x1080_60.00" xrandr --output DP-1 --mode "1920x1080_60.00"

    Try It Yourself

    Practice makes perfect! The best way to learn is by trying these examples on your own system with real files.

    Understanding Syntax

    Pay attention to the syntax coloring: commands, options, and file paths are highlighted differently.

    Notes

    The `xrandr` command is a powerful utility for managing displays and screen configurations in the X Window System. It provides a command-line interface to the RandR (Resize and Rotate) extension, which allows for dynamic configuration of outputs, resolutions, orientations, and positioning without restarting the X server. **Core Functionality:** 1. **Display Information**: xrandr provides detailed information about connected displays, available resolutions, refresh rates, and current configurations. 2. **Resolution Management**: It allows changing screen resolutions on the fly, both with standard modes and custom resolutions. 3. **Multi-monitor Setup**: xrandr excels at configuring multiple displays, including their relative positions, mirroring, and extended desktop arrangements. 4. **Rotation and Reflection**: It can rotate or reflect displays to accommodate various monitor orientations. 5. **Primary Display Configuration**: xrandr allows designating a primary display for application windows and panels. **Common Use Cases:** 1. **Basic Display Information**: Running `xrandr` without arguments shows all connected displays and their capabilities: ``` $ xrandr Screen 0: minimum 320 x 200, current 3840 x 1080, maximum 8192 x 8192 HDMI-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 520mm x 290mm 1920x1080 60.00*+ 59.94 50.00 1680x1050 59.88 1280x1024 75.02 60.02 DP-1 connected 1920x1080+1920+0 (normal left inverted right x axis y axis) 520mm x 290mm 1920x1080 60.00*+ 59.94 50.00 1680x1050 59.88 1280x1024 75.02 60.02 ``` 2. **Changing Resolution**: ```bash # Set monitor to 1920x1080 resolution xrandr --output HDMI-1 --mode 1920x1080 ``` 3. **Setting Refresh Rate**: ```bash # Set monitor to 1920x1080 at 60Hz xrandr --output HDMI-1 --mode 1920x1080 --rate 60 ``` 4. **Multiple Monitors - Extended Desktop**: ```bash # Configure two monitors side by side xrandr --output HDMI-1 --auto --output DP-1 --auto --right-of HDMI-1 ``` 5. **Rotating a Display**: ```bash # Rotate a display 90 degrees clockwise xrandr --output HDMI-1 --rotate right ``` 6. **Mirroring Displays**: ```bash # Make both displays show the same content xrandr --output HDMI-1 --auto --output DP-1 --auto --same-as HDMI-1 ``` 7. **Setting Primary Display**: ```bash # Designate a display as primary xrandr --output HDMI-1 --primary ``` 8. **Disabling a Display**: ```bash # Turn off a display xrandr --output DP-1 --off ``` **Advanced Features:** 1. **Custom Resolutions**: xrandr can create and use custom resolutions that might not be advertised by the display: ```bash # Create a custom 1920x1080 mode xrandr --newmode "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync xrandr --addmode DP-1 "1920x1080_60.00" xrandr --output DP-1 --mode "1920x1080_60.00" ``` 2. **Display Scaling**: ```bash # Scale a display by 1.5x in both directions xrandr --output HDMI-1 --scale 1.5x1.5 ``` 3. **Panning/Viewport**: ```bash # Set up panning (virtual desktop larger than physical display) xrandr --output HDMI-1 --mode 1920x1080 --panning 2560x1440 ``` 4. **Transform Matrix**: For advanced transformations beyond simple rotation and reflection: ```bash # Apply a custom transformation matrix xrandr --output HDMI-1 --transform 1.1,0.1,-50,0,1.1,0,0,0,1 ``` **Integration with Desktop Environments:** While modern desktop environments like GNOME, KDE, and XFCE provide graphical tools for display configuration, xrandr remains valuable for: 1. **Scripting**: Creating shell scripts to quickly switch between different display configurations 2. **Remote Administration**: Configuring displays on headless or remote systems 3. **Boot-time Configuration**: Setting up displays during system startup 4. **Custom Configurations**: Implementing setups that might not be available through GUI tools **Making Changes Persistent:** Changes made with xrandr are temporary and reset after a system reboot or X server restart. To make them permanent: 1. Add xrandr commands to your X startup scripts (e.g., `~/.xinitrc` or `~/.xprofile`) 2. Use desktop environment-specific tools to save configurations 3. Create an X11 configuration file in `/etc/X11/xorg.conf.d/` 4. Use tools like `autorandr` to automatically detect and apply saved configurations **Limitations:** 1. **X11 Only**: xrandr works only with the X Window System, not with Wayland 2. **Driver Dependence**: Some features depend on the capabilities of the graphics driver 3. **Hardware Limits**: Custom resolutions and features are constrained by hardware capabilities 4. **Complex Syntax**: The command-line syntax can be verbose for complex configurations **Tools That Complement xrandr:** 1. **arandr**: A graphical frontend for xrandr 2. **autorandr**: Tool to automatically select configurations based on connected displays 3. **xdpyinfo**: Provides additional display information 4. **cvt** and **gtf**: Calculate VESA CVT/GTF mode lines for use with --newmode 5. **disper**: Display switching utility focused on laptops with external monitors xrandr remains one of the most versatile and powerful tools for X11 display management, especially for users who need precise control over their display configuration or need to script display changes.

    Related Commands

    These commands are frequently used alongside xrandr or serve similar purposes:

    arandr
    xdpyinfo
    cvt
    gtf
    autorandr
    xorg
    Explore All Commands

    Use Cases

    Learn By Doing

    The best way to learn Linux commands is by practicing. Try out these examples in your terminal to build muscle memory and understand how the xrandr command works in different scenarios.

    See ExamplesTry Lab Exercises
    $ xrandr
    View All Commands