kanshi

Related articles
Sway
kanshi
allows you to define output profiles that are automatically enabled and disabled on hotplug. For instance, this can be used to turn a laptop's internal screen off when docked.
This is a Wayland equivalent for tools like
autorandr
. kanshi can be used on Wayland compositors supporting the wlr-output-management protocol.
Installation
Install
kanshi
or
kanshi-git
AUR
.
Configuration
Basic
Create kanshi configuration file:
~/.config/kanshi/config
profile {
	output LVDS-1 disable
	output "Some Company ASDF 4242" mode 1600x900 position 0,0
}

profile {
	output LVDS-1 enable scale 2
}
Each output profile is delimited by brackets. It contains several output directives (whose syntax is similar to
sway-output(5)
). A profile will be enabled if all of the listed outputs are connected.
Tip
You can get a list of output names and additional information using commands like
wlr-randr
,
swaymsg -t get_outputs
or use the GUI applications
wdisplays-git
AUR
or
wdisplays-persistent
AUR
which will write also directly to kanshi's configuration file.
Advanced
For easier management of multiple setups
(e.g. Internal laptop monitor only, Docked to one monitor at home, Docked to two work monitors, ...)
you can define defaults for the outputs used inside profiles and assign them aliases. The defaults will apply to all profiles where the respective output is mentioned. For more see
kanshi(5)
.
~/.config/kanshi/config
output "Dell Inc. DELL S2721DGF G52TR83" {
  mode 2560x1440@165.08
  position 1280,0
  scale 2
  alias $HOME_1
}

output "LG Display 0x058B Unknown" {
  mode 2560x1440@59.99800
  position 0,0
  scale 2
  alias $INTERNAL
}

profile home_1 {
  output $INTERNAL disable
  output $HOME_1 enable
}
You can find out these values with a command like
hyprctl monitors
which will display all three of those in its output.
hyprctl monitors
make: LG Display
model: 0x058B
serial:
It is also possible to further integrate kanshi with your workflow by using the
exec
directive to execute a command once the profile was successfully applied.
~/.config/kanshi/config
profile home_1 {
  output $INTERNAL disable
  output $HOME_1 enable
  exec uwsm app -- $HOME/.config/hypr/scripts/move-workspaces.sh "LG Display 0x058B"
}
Usage
Run the command:
$ kanshi
See
#Manage kanshi with systemd
for an automated usage.
Tips and tricks
Manage kanshi with systemd
Create and start
~/.config/systemd/user/sway-session.target
(if you don't have created yet) by following
Sway#Manage Sway-specific daemons with systemd
.
Create the
kanshi.service
file:
~/.config/systemd/user/kanshi.service
[Unit]
Description=Dynamic output configuration for Wayland compositors
Documentation=man:kanshi(1)
BindsTo=sway-session.target

[Service]
Type=simple
ExecStart=/usr/bin/kanshi

[Install]
WantedBy=sway-session.target
Enable
this
user unit
. It is only activated when Sway is running and deactivated when Sway stops.
Troubleshooting
Workspace number starts from 2 in external monitor after wake up
If you have a configuration like
above
, when you connected a second display to your computer, the workspace in the second display should start from 1 since the first display is disabled. This should be the case when you plugged your monitor in the first time or after starting the system. But after sleep, this number might be 2. In this case just move the first workspace to this monitor by adding a directive to the kanshi configuration file:
~/.config/kanshi/config
profile {
	output LVDS-1 disable
	output "Some Company ASDF 4242" mode 1600x900 position 0,0
	# We've added this directive here (do not forget to update the output name):
	exec swaymsg workspace 1, move workspace to HDMI-A-1
}

profile {
	output LVDS-1 enable scale 2
}
See also
Source code and documentation