Core options

Scott Moreau edited this page Jan 28, 2019 · 3 revisions


  1. plugins = viewport_impl move resize wobbly cube ...

A space-separated list of enabled plugins. Due to current limitations, the viewport_impl plugin is required and must always be the first in the list.

  1. vwidth/vheight = 1,2,3,...

Integer options, the number of horizontal/vertical workspaces. For now it can't be changed at runtime.


  1. natural_scroll/tap_to_click/disable_while_typing = 1/0

Touchpad-related options, self-explanatory.

  1. xkb_layout/xkb_option/xkb_variant

Options to control the keyboard layout, they follow the same format as the corresponding setxkbmap options. Example:

xkb_layout = us,bg
xkb_option = grp:win_space_toggle,compose:ralt
xkb_variant = ,phonetic
  1. kb_repeat_rate/kb_repeat_delay = N

Control keyboard repeat rate/delay. Example:

kb_repeat_rate = 40.000000
kb_repeat_delay = 400.000000
  1. cursor_size/cursor_theme

Control the cursor size and theme. Example:

cursor_size = 24
cursor_theme = Bibata_Ice
  1. Binding input devices to outputs

Some devices like built-in touchscreens should be mapped to exactly one output (e.g they apply only for that output). Find out the device name and the output name (usually by inspecting the log), then create a section as follows:

output = <output_name>

## Example:
[SYNA7501:00 06CB:16CA]
output = eDP-1

Output configuration

To configure outputs, you first need to figure out each output's name. They are usually the same as xrandr output names. If you are unsure which output names are on your system, check the log. There you can also find information about the supported modes.

Each output has its own section in the config name. The section name is the same as the output name. Each of the following options should be put in the output section for the output that you want to configure.

  1. mode = width x height @ refresh or mode = default

Use the given mode. Refresh rate can be in Hz or mHz. Example: mode = 1920x1080@60

  1. custom_mode_N = modeline

Add a custom mode to the given output. The modeline is the same as the one which is used in X, and can be generated by for ex. cvt. The custom mode can then be set via the mode option. Example:

custom_mode_1 = 712.75  3840 4160 4576 5312  2160 2163 2168 2237 -hsync +vsync
  1. scale = X

Set output scale, use for HiDPI. Wayfire supports fractional scaling. Example: scale = 1.5. Default is 1

  1. transform = V

Set output transform, i.e rotation. Possible values: normal (default), 90, 180, 270, flipped, 90_flipped, 180_flipped, 270_flipped

  1. layout = x,y

Sets the position of the output in the global compositor space. Outputs which don't have a layout set will be arranged next to the rightmost output. Currently Wayfire supports only a very basic output layout. So, if you configure the outputs so that there is empty space between them, you won't be able to move the mouse from one to the other. Overlapping outputs also will result in possibly weird behavior.

To properly calculate the output size in the global compositor space, you need to take its resolution, divide by scale and then apply the rotation. You can use a little "trick" to save yourself the hassle of computing layouts if you have just 2 monitors arranged horizontally: just specify the layout of the left one to 0,0 and the other will be automatically arranged to the right.


This is a section which contains some hacks that might be required to make things work. Fortunately there is only a single option supported for now.

  1. app_id_mode = stock/gtk-shell/full

TL;DR: if you use only wf-dock as task manager/dock, set to full. Otherwise, try stock and gtk-shell, and use whichever works better for you.

In contrast to X, in wayland clients like taskbars, docks, etc. can't just query the icon of a window. They need to obtain it by using some heuristics involving the app-id. However, in GTK3 there is a bug where the application sometimes reports the wrong app-id. There is a custom protocol(gtk-shell1) which can be used to get the correct app-id. The situation will get better in GTK4 where the bug is fixed, but in the meantime we somehow need to supply the dock/taskmanager with both app-ids (the potentially wrong one and the potentially missing one from gtk-shell1). This isn't possible with the regular protocols, that's why wayfire and wf-dock use a custom format (when app_id_mode=full) so that both app-ids can be sent at the same time. This would unfortunately break clients that are unaware of this hack. That's why it's up to the user of Wayfire to select whichever mode works best for them, depending on what clients they use.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.