AUTORANDR(1)

📦
version 1.15 · 3 versions
, in alpine 3.24, arch rolling, debian trixie, fedora 43, fedora 44, nixpkgs unstable, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 AUTORANDR — the autorandr(1) glow-up 💖

okay bestie, sit down, hydrate, because this one is actually iconic. it's autorandr, a General Commands Manual situation, and it's about to make your monitors behave. no cap. ✨

✨ NAME ✨

autorandr — automatically select a display configuration based on connected devices 🖥️🦋

🌸 SYNOPSIS 🌸

autorandr [OPTION] [PROFILE]

that's it. that's the whole vibe. option, then maybe a profile name. slay.

💅 DESCRIPTION 💅

so like, this program automatically detects your connected display hardware and then loads an appropriate X11 setup using xrandr. it's giving "i know what monitors you plugged in and i already handled it." 👑

it also supports the use of display profiles for different hardware setups, so you can have one for "laptop at desk", one for "docking station era", one for "chaos", whatever you want. main character energy for every setup.

Autorandr also includes several virtual configurations including off, common, clone-largest, horizontal, and vertical. see the documentation for explanation of each. iykyk. 🎀

🔥 OPTIONS 🔥

  • -h, --help — Display help text and exit. the "hey bestie what are you" button.
  • -c, --change — Automatically load the first detected profile. it just knows. ✨
  • -d, --default PROFILE — Make profile PROFILE the default profile. The default profile is used if no suitable profile can be identified. Else, the current configuration is kept.
  • -l, --load PROFILE — Load profile PROFILE. serving.
  • -s, --save PROFILE — Save the current setup to profile PROFILE. screenshot but for your whole monitor situation.
  • -r, --remove PROFILE — Remove profile PROFILE. bye girl 💀
  • --batch — Run autorandr for all users with active X11 sessions. group-chat-wide deployment fr fr.
  • --current — List only the current (active) configuration(s).
  • --config — Dump the variable values of your current xrandr setup.
  • --cycle — Cycle through all detected profiles. round and round we go 🌀
  • --debug — Enable verbose output. it will NOT stop talking and honestly? we love that.
  • --detected — List only the detected (i.e. available) configuration(s).
  • --dry-run — Don't change anything, only print the xrandr commands. window shopping, basically. 🛍️
  • --fingerprint — Fingerprint the current hardware setup.
  • --match-edid — Match displays based on edid instead of name.
  • --ignore-lid — By default, closed lids are considered as disconnected if other outputs are detected. This flag disables this behaviour. (so like, your laptop being shut normally counts as "not here" — this turns that off.)
  • --force — Force loading or reloading of a profile.
  • --list — List all profiles.
  • --skip-options [OPTION] ... — Set a comma-separated list of xrandr arguments to skip both in change detection and profile application. See xrandr(1) for xrandr arguments.
  • --version — Show version information and exit. 👑

🗂️ FILES 🗂️

Configuration files are searched for in the autorandr directory in the colon separated list of paths in $XDG_CONFIG_DIRS — or in /etc/xdg if that var is not set. They are then looked for in ~/.autorandr and if that doesn't exist, in $XDG_CONFIG_HOME/autorandr or in ~/.config/autorandr if that var is unset. the search order is lowkey doing the most but it's fine, it's thorough. 🧚

In each of those directories it looks for directories with config and setup in them. It is best to manage these files with the autorandr utility. (translation: don't hand-edit, let the tool do its thing bestie 🫶)

⚙️ DEFAULT OPTIONS ⚙️

You can store default values for any option in an INI-file located at ~/.config/autorandr/settings.ini. In a config section, you may place any default values in the form option-name=option-argument.

so cute. so configurable. so yours. 💖

🪝 HOOK SCRIPTS 🪝

Four more scripts can be placed in the configuration directory:

  • postswitch — Executed after a mode switch has taken place. This can be used to notify window managers or other applications about the switch.
  • preswitch — Executed before a mode switch takes place.
  • postsave — Executed after a profile was stored or altered.
  • predetect — Executed before autorandr attempts to run xrandr.

These scripts must be executable and can be placed directly in the configuration directory, where they will always be executed, or in the profile subdirectories, where they will only be executed on changes regarding that specific profile. ✨

Instead (or in addition) to these scripts, you can also place as many executable files as you like in subdirectories called script_name.d (e.g. postswitch.d). drop a whole folder of them, go off. 📁

Some of autorandr's state is exposed as environment variables prefixed with AUTORANDR_, such as: AUTORANDR_CURRENT_PROFILE, AUTORANDR_CURRENT_PROFILES, AUTORANDR_PROFILE_FOLDER, and AUTORANDR_MONITORS with the intention that they can be used within the hook scripts.

⚠️ the one kink is that during preswitch, AUTORANDR_CURRENT_PROFILE is reporting the upcoming profile rather than the current one. not a bug, just a plot twist. don't let it jumpscare you. 😭

👑 AUTHOR 👑

Phillip Berndt <phillip.berndt@googlemail.com>

See https://github.com/phillipberndt/autorandr for a full list of contributors.

🙈 REPORTING BUGS 🙈

Report issues upstream on GitHub: https://github.com/phillipberndt/autorandr/issues

Please attach the output of xrandr --verbose to your bug report if appropriate. (yes, actually attach it, it saves everyone a whole back-and-forth 💀)

🌈 SEE ALSO 🌈

For examples, advanced usage (including predefined per-profile & global hooks and wildcard EDID matching), and full documentation, see https://github.com/phillipberndt/autorandr.

and that's the page bestie 🎀 it's from the General Commands Manual, it's AUTORANDR(1), and it's genuinely so good. go forth, plug in a monitor, let it cook. mwah 💋✨

📦 where this page comes from