WAY-DISPLAYS(1)

📦 version 1.15.0, in nixos 26.05, nixpkgs unstable

✨ WAY-DISPLAYS 💅 — Auto Manage Your Wayland Displays

okay bestie, so this is the way-displays manual page (it's WAY-DISPLAYS(1) if we're being formal 🌸) and honestly? it's giving "let your displays manage themselves" and we're obsessed. ngl this tool is genuinely iconic and we're gonna walk through every single thing it does, no cap.

🎀 SYNOPSIS

way-displays [OPTIONS...]  [COMMAND]

that's it. that's the whole vibe. options in front, command at the end, slay. 💅

💖 DESCRIPTION

so here's literally everything it handles for you, bestie, and yes there are six things and we're listing all six:

Set resolution/refresh: preferred, highest or custom
Enable VRR / adaptive sync
Arrange in a row or a column
Auto scale based on DPI: 96 is a scale of 1
Update when displays plugged/unplugged
Update when laptop lid closed/opened

Works out of the box: no configuration required. 🫶 like, zero notes. it just works.

It's the Wayland successor to xlayoutdisplay, inspired by kanshi. main character energy fr.

See wiki for Configuration, Recipes, Troubleshooting and more.

🌈 Server

The background process that performs the management — that's the server, she's the one doing the work behind the scenes, iykyk. Configuration is read from a file discovered in order:

$XDG_CONFIG_HOME/way-displays/cfg.yaml
$HOME/.config/way-displays/cfg.yaml
/usr/local/etc/way-displays/cfg.yaml
/etc/way-displays/cfg.yaml

The file may be specified via the --config option.

cfg.yaml will be monitored for changes, which will be immediately applied. ✨ so you edit, she notices, she applies, periodt.

See the default /etc/way-displays/cfg.yaml and https://github.com/alex-courtis/way-displays/wiki/Configuration for details on individual configurable settings.

Server is run when no commands are specified. 👑

Server responds to IPC requests to fetch and mutate state: https://github.com/alex-courtis/way-displays/wiki/IPC

🦋 Client

Manages the server. The active configuration and display state may be inspected, and the configuration modified.

The active configuration can be written to disk, however any comments and formatting will be lost. 😭 yep, the comments ghost you. tragic but true.

⭐ REQUIREMENTS

You need a wlroots based compositor that supports the WLR Output Management protocol. that's the whole requirement, bestie.

way-displays is blessed for the sway and river. It may work on others. 🤷‍♀️

Hpyrland provides all way-displays functionality and you may experience issues. 💀 noted.

way-displays must be run as a daemon, a background server process. It will respond to your configuration changes as well as state changes such as plugging in a monitor or closing the lid.

User should be a member of the input group for querying laptop lid state. 🔍 (yes, actually join it, don't be that person)

💅 OPTIONS

-L | --l[og-threshold] <debug|info|warning|error|fatal> — Overrides cfg.yaml. info is default. highkey the sensible one.
-c | --c[onfig] <path> — Configuration file, falls back to defaults if not found.
-y | --y[aml] — Print client output as raw YAML. for the yaml girlies 🎀

👑 COMMANDS

-h | --h[elp] — Print usage and exit.
-v | --v[ersion] — Display version information and exit.
-g | --g[et] — Show the active configuration, commands and current display state. like a vibe check but for your monitors 🫶
-s | --s[et] — Add a new setting or modify an existing.

The settings you can --set (all of them, in order, no skipping 💜):

ARRANGE_ALIGN <row|column> <top|middle|bottom|left|right> — Set vertical arrangement and the alignment.
ORDER <name|!regex> ... — Set the order of arrangement. Replaces previous order. ⚠️ note that "replaces" — your old order is gone, so don't come crying to me.
SCALING <on|off> — Enable scaling, overrides AUTO_SCALE and SCALE
AUTO_SCALE <on|off> — Enable auto scaling.
SCALE <name> <scale> — Set the scale for a specific display.
MODE <name> MAX — Highest available resolution / refresh.
MODE <name> <width> <height> [<Hz>] — Specified resolution at its highest refresh. Optional refresh will choose a mode +-0.5Hz.
TRANSFORM <name> <90|180|270|flipped|flipped-90|flipped-180|flipped-270> — Transform a specific display.
VRR_OFF <name> — Disable VRR for a display.
DISABLED <name> — Disable a display.
CALLBACK_CMD <shell command> — Sets a /bin/sh command to be executed following most events. Obeys LOG_THRESHOLD

and the callback deets, because they matter:

Default: notify-send "way-displays ${CALLBACK_LEVEL}" "${CALLBACK_MSG}"
${CALLBACK_MSG} contains a human readable message
${CALLBACK_LEVEL} LOG_THRESHOLD
-d, --d[elete] — Remove an existing setting.

what --delete can nuke, one by one:

SCALE <name> — Use auto scaling for the display, if enabled.
MODE <name> — Use preferred or highest availble if no preferred. (yep, "availble" — that's how it's spelled in the manpage, we don't edit the source, we respect the source 💖)
TRANSFORM <name> — Remove transformation for a display.
VRR_OFF <name> — Enable VRR for a display. (yes, deleting the VRR_OFF setting turns VRR on, it's giving chaos but it's correct)
DISABLED <name> — Enable a display.
CALLBACK_CMD <shell command> — Remove command on display configuration success.
-t, --t[oggle] — Toggle a setting.

the toggle-ables, all four:

SCALING — Toggle scaling.
AUTO_SCALE — Toggle auto scaling.
VRR_OFF <name> — Toggle VRR for a display.
DISABLED <name> — Toggle a display.
-w | --w[rite] — Write active configuration to cfg.yaml; removes any whitespace or comments. 😭 bye bye comments, we hardly knew ye.

🧚 NAMING

Displays are matched by name or description with precedence: exact, regex, fuzzy. that's the order, don't fight it.

You can identify them via logs e.g.

DP-3 Arrived:
    name:     'DP-3'
    desc:     'Unknown Monitor Maker ABC123 (DP-3 via HDMI)'

It is recommended to use the description rather than the nondeterministic name. 🔥 fr, the name can change on you, the desc is the stable queen.

Any item prefixed with a ! will be interpreted as extended POSIX regex e.g. !^DP-1. Regex strings must be single quoted. 🎀

Using a regex is preferred, however fuzzy case insensitive string matches of at least 3 characters may be used.

DP-1 will match eDP-1 and DP-1. Consider using regex !^DP-1$ to exactly match. ⚠️ this is the classic gotcha, bestie — be precise or be surprised.

🌸 EXAMPLES

exec way-displays > /tmp/way-displays.${XDG_VTNR}.${USER}.log 2>&1

Add to your sway config to start way-displays when sway starts. 🫶

way-displays -g

Show current configuration and display state.

way-displays -s ARRANGE_ALIGN row bottom

Arrange left to right, aligned at the bottom.

way-displays -s ORDER "!^DP-[0-9]+$" HDMI-1 "monitor maker ABC model XYZ" eDP-1

Set the order for arrangement.

way-displays -s SCALE "eDP-1" 3

Set the scale.

way-displays -s MODE HDMI-A-1 3840 2160 24

Use 3840x2160@24Hz

way-displays -w

Persist your changes to your cfg.yaml 💾

💜 AUTHORS

Alexander Courtis.

and that's the whole page, bestie — this is way-displays from the User Manuals, dated 2025/08/29, and it ate. go arrange some displays. 💅✨

📦 where this page comes from

nixos 26.05: way-displays 1.15.0
nixpkgs unstable: way-displays 1.15.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms