How to automatically change X11 displays setup with autorandr on Linux

Adding a monitor to a setup is probably one of the most effective and immediate ways to increase productivity. A multi monitor setup can be useful, for example, when we need to consult some kind of documentation and at the same time work on another task full-screen. Autorandr is a free and open source utility able to apply specific X11 configurations depending on the displays connected to our machine.

In this tutorial we learn how use the autorandr utility, and how to install it on some of the most used Linux distributions.

In this tutorial you will learn:

  • How to install autorandr in some of the most used Linux distributions
  • How to create, remove and manually load a profile
  • How to list existing profiles
  • How to get the xrandr settings related to a profile
  • How and where autorandr keeps profile configurations
How to automatically change X11 displays setup with autorandr on Linux
How to automatically change X11 displays setup with autorandr on Linux
 
 
Software requirements and conventions used
Category Requirements, Conventions or Software Version Used
System Distribution independent
Software X11 server, autorandr, xrandr or one of its graphical frontends
Other Administrative privileges to install software
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user

Installing autorandr

Autornadr is free and open source software. The utility is mainly written in Python and released under the GPLv3 license. It is available in the repositories of the major Linux distributions, therefore can be easily installed using  their respective package managers. Let’s see some examples. To perform the installation on Fedora, we can run:

$ sudo dnf install autorandr

To install the package on Debian or Ubuntu, instead, we can use the following command:

$ sudo apt-get update && sudo apt-get install autorandr

Autorandr is also available in the Archlinux “Community” repository. We can install it by using the pacman package manager:

$ sudo pacman -Sy autorandr



Since autorandr is written in Python, it is also distributed as Python package, therefore can be installed in a distribution-independent way, using pip, the Python package manager. To perform the installation for our user only (running pip as root is discouraged), we can use the following command:

$ pip install autorandr --user  

When installed this way, the autorandr binary is placed under the ~/.local/bin directory, which should be already part of the user PATH.

How autorandr works

Autorandr “fingerprints” displays connected to the system and associate them with their current X11 server settings in “profiles” which are automatically applied each time a fingerprint is matched. Let’s see some usage examples.

At the moment I am writing from my Notebook, and I have no other monitors connected to it. The only display in use is the native one, which is set to work at its maximum resolution (1920x1080) and with a certain refresh rate.

To make autorandr remember this configuration, what I need to do is to save it in a “profile” and assign a name to it. To accomplish this task I invoke the utility with the --save option and pass the name I want to use for the profile as argument:

$ autorandr --save laptop

Invoking the utility without any option or argument, I can see the profile was correctly saved and it is the one currently in use:

$ autorandr
laptop (detected) (current)

To set this profile as the default one, I run:

$ autorandr --default laptop

When a profile is set as default, it is used if no other configuration matches. If no default profile exists, instead, the current configuration is kept.



Good. Now, let’s add an external monitor to the setup. I connect the monitor, set the desired resolution (2560x1080 in this case) and place it at the right of the native machine monitor, which is marked as the primary one. Such task can be performed from the command line, using xrandr, or, more conveniently, using a graphical frontend. In this example I use “arandr”:

Arandr is a graphical frontend for xrandr: we can use it to setup displays and their layouts.
Arandr is a graphical frontend for xrandr: we can use it to setup displays and their layouts.

Once I am content with the setup, I make it effective, then “register” it as a new profile using autorandr. In this case I save it as “laptop_external_ultrawide”:

$ autorandr --save laptop_external_ultrawide

Now, when I will detach the external monitor, autorandr will check for a profile that matches the new configuration. If one exists it will be applied (in this case “laptop”, which is also the default). In the same way, the “laptop_external_ultrawide” profile will automatically be applied when I will re-attach the same external monitor.

Loading a profile manually

As we saw, a profile is loaded depending on the display(s) connected to our machine. We can, however, load a specific profile manually. In such case what we want to do, is to simply pass the profile name as argument to the utility:

$ autorandr laptop_external_ultrawide

If a profile is already in use, it will not be reloaded, unless the --force option is passed.

Getting the settings associated with the active profile

Sometimes can be useful to take a look at the xrandr settings associated with the active profile. To accomplish such action, all we have to do is to run autorandr with the --config option:

$ autorandr --config

Here is the output returned by the command when the “laptop_external_ultrawide” profile is in use:

output DP-1
off
output HDMI-1
off
output DP-2
off
output eDP-1
crtc 0
mode 1920x1080
pos 0x0
primary
rate 60.01
x-prop-broadcast_rgb Automatic
x-prop-colorspace Default
x-prop-max_bpc 12
x-prop-non_desktop 0
x-prop-scaling_mode Full aspect
output HDMI-2
crtc 1
mode 2560x1080
pos 1920x0
rate 59.98
x-prop-aspect_ratio Automatic
x-prop-audio auto
x-prop-broadcast_rgb Automatic
x-prop-colorspace Default
x-prop-max_bpc 12
x-prop-non_desktop 0

Removing a profile

Removing a profile is really easy, since there is an option dedicated to the task: --remove. To remove the “laptop_external_ultrawide” we would run:

$ autorandr --remove laptop_external_ultrawide

Autorandr configuration file(s)

Autorandr keeps profiles data under the ~/.config/autorandr directory. Configurations related to a profile are placed in a sub-directory named after the profile itself, which contains two files: config and setup. Here is the file structure related to the existing profiles on my machine:

/home/egdoc/.config/autorandr/
├── laptop
│   ├── config
│   └── setup
└── laptop_external_ultrawide
    ├── config
    └── setup



The file named “config” contains the xrandr options relative to the profile; the “setup” file, instead, contains the “fingerprint” of the displays. Here is the fingerprint related to hardware setup associated to the “laptop_external_ultrawide” profile on my system:

HDMI-2 00ffffffffffff001e6d1477d8660300081d010380502278eaca95a6554ea1260f5054256b807140818081c0a9c0b300d1c08100d1cfcd4600a0a0381f4030203a001e4e3100001a023a801871382d40582c45001e4e3100001e000000fd00384b1e5a19000a202020202020000000fc004c472048445220574648440a2001ca020337f1230907074c100403011f1359da125d5e5f830100006d030c001000b83c20006001020367d85dc4013c8000e305c000e3060501295900a0a038274030203a001e4e3100001a565e00a0a0a02950302035001e4e3100001a000000ff003930384e544142364a3933360a0000000000000000000000000000000000008a
eDP-1 00ffffffffffff0026cf7d0500000000001a0104951f11780a7690945554902721505400000001010101010101010101010101010101383680a07038204018303c0035ae10000019000000000000000000000000000000000000000000fe00496e666f566973696f6e0a2020000000fe00523134304e574635205231200a0016

By the way, the fingerprint of the current hardware configuration can be obtained by running autorandr with the --fingerprint option.

Conclusions

Autorandr is a free and open source utility written in Python, which can be used to automatically apply specific X11 configurations depending on the displays connected to a machine. In this article we saw how to install the utility in some of the most used Linux distributions; how to create, remove and manually load a profile, and how to list existing ones. Finally, we saw how to inspect configurations associated to a profile, and how they are organized in the filesystem.