kanshi(5)

💖 kanshi(5) — the config file, but make it make sense 💖

okay bestie, so this is the manual for kanshi in the File Formats Manual section. Sit down, grab a strawberry, we're learning how to write a config file that actually slays. ✨

---

🌸 NAME 🌸

kanshi — configuration file. that's it, that's the name, iconic behavior honestly.

---

🎀 DESCRIPTION 🎀

So a kanshi config file? It's literally just a list of profiles. Each profile has an optional name and contains a bunch of profile directives all wrapped up in brackets ({ and }). the way that it's basically a little gossip circle of profiles 💅

Example, look:

include /etc/kanshi/config.d/*

profile {
     output LVDS-1 disable
     output "Some Company ASDF 4242" {
          mode 1600x900
          position 0,0
     }
}

profile nomad {
     output LVDS-1 enable scale 2
}

see how cute that is. chef's kiss, no notes 🫶

---

✨ DIRECTIVES ✨

• profile [<name>] { <profile directives...> } — defines a new profile using the specified bracket-delimited profile directives. You can give it a name but honestly it's optional, lowkey vibe-based.
• output <criteria> <output-directive...> — this one sets up defaults for output directives inside profile definitions. 🧚

These defaults only kick in when the respective output is actually mentioned in a specific profile. Like, for example, these two profiles are literally equivalent, no cap:

output eDP-1 scale 2

profile manual {
     output eDP-1 scale 2
}

profile uses-defaults {
     output eDP-1
}

Output directives can be specified in a bracket-delimited block too, if that's your thing.

• include <path> — include another file from path. It expands shell syntax (go read wordexp(3) for the details, iykyk).

---

💅 PROFILE DIRECTIVES 💅

Profile directives get followed by space-separated arguments. And bestie, arguments can be quoted (with ") if they contain spaces. periodt.

• output <criteria> <output-directive...> — an output directive adds an output to the profile.

The criteria can be one of:

• An output name (e.g. "DP-1"). ⚠️ Note: output names may not be stable — they may change across reboots (depending on kernel driver probe order) or creation order (typically for USB-C docks). it's giving chaos.
• A space-separated string containing the output manufacturer, model and serial number (e.g. "Foocorp ASDF 1234"). A wildcard pattern can be used (e.g. "Foocorp ASDF *"), see glob(7). If one of these fields is missing, it needs to be populated with the string "Unknown" (e.g. "Foocorp ASDF Unknown").
• An output alias (e.g. "$work-desk3") defined by an output alias directive. Output aliases can only be used in profile scope.
• A wildcard "*", to match any output. Wildcards can only be used in profile scope and will only match one output.

Output directives may be specified in a bracket-delimited block as well.

On sway(1), output names and identifiers can be obtained via "swaymsg -t get_outputs". 📋

• ...output <criteria> <output-directive...> — same as output, but adds any number of outputs to the profile. This is usually combined with a wildcard criteria. yes the three dots are part of it, don't come for me 🙈
• exec <command> — an exec directive executes a command when the profile was successfully applied. This can be used to update the compositor state to the profile when it's not done automatically.

Commands are executed asynchronously and their order may not be preserved. 😭 If you need to execute sequential commands, you should collect them in one exec statement or in a separate script. do not fight this, just accept it.

On sway(1) for example, exec can be used to move workspaces to the right output:

profile multihead {
     output eDP-1 enable
     output DP-1 enable transform 270
     exec swaymsg workspace 1, move workspace to eDP-1
}

Note that some extra care must be taken with outputs identified by an output description, as the real name may change:

profile complex {
     output "Some Other Company GTBZ 2525" mode 1920x1200
     exec swaymsg workspace 1, move workspace to output '"Some Other Company GTBZ 2525"'
}

---

🌈 OUTPUT DIRECTIVES 🌈

• enable|disable — enables or disables the specified output. simple as that, slay.
• mode preferred — configures the specified output to use its preferred mode. let it choose, main character energy.
• mode [--custom] <width>x<height>[@<rate>[Hz]] — configures the specified output to use the specified mode. Modes are a combination of width and height (in pixels) and a refresh rate (in Hz) that your display can be configured to use.

Examples:

output HDMI-A-1 mode 1920x1080
output HDMI-A-1 mode 1920x1080@60Hz
output HDMI-A-1 mode --custom 1280x720@60Hz

• position <x>,<y> — places the output at the specified position in the global coordinates space.

Example:

output HDMI-A-1 position 1600,0

• scale <factor> — scales the output by the specified scale factor.
• transform <transform> — sets the output transform. Can be one of "90", "180", "270" for a rotation; or "flipped", "flipped-90", "flipped-180", "flipped-270" for a rotation and a flip; or "normal" for no transform. 🌀
• adaptive_sync on|off — enables or disables adaptive synchronization (aka. Variable Refresh Rate). the smoothness is real fr fr 🔥
• alias $<name> — defines an alias for this output. Output aliases can only be defined in global scope. don't try it anywhere else bestie 💀

---

👑 AUTHORS 👑

Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other open-source contributors. For more information about kanshi development, see <https://gitlab.freedesktop.org/emersion/kanshi>.

---

🔥 SEE ALSO 🔥

• kanshi(1)

---

and that's the whole page, bestie 🦋✨ this kanshi(5) situation comes from the File Formats Manual, dated 2026-01-24 — and that's the entire footer, so go forth and configure your outputs, you absolute legend 💖💅🎀