kanshi - ArchWiki

Jump to content

# kanshi

From ArchWiki

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-gitAUR.

## 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-gitAUR or wdisplays-persistentAUR 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

Category:

- Wayland

kanshi
Add topic