Running Qtile as a Wayland Compositor

Some functionality may not yet be implemented in the Wayland compositor. Please see the discussion here to see the current state of development. Also see troubleshooting.

Backend-Specific Configuration

If you want your config file to work with different backends but want some options set differently per backend, you can check the name of the current backend in your config as follows:

from libqtile import qtile

if qtile.core.name == "x11":
    term = "urxvt"
elif qtile.core.name == "wayland":
    term = "foot"

Running X11-Only Programs

Qtile _does_ support XWayland. This requires that wlroots and pywlroots were built with XWayland support, and that XWayland is installed on the system from startup. XWayland will be started the first time it is needed.

XWayland windows sometimes don't receive mouse events

There is currently a known bug (https://github.com/qtile/qtile/issues/3675) which causes pointer events (hover/click/scroll) to propagate to the wrong window when switching focus.

Input Device Configuration

InputConfig

class libqtile.backend.wayland.InputConfig(**config: Any)[source]

This is used to configure input devices. An instance of this class represents one set of settings that can be applied to an input device.

To use this, define a dictionary called wl_input_rules in your config. The keys are used to match input devices, and the values are instances of this class with the desired settings. For example:

from libqtile.backend.wayland import InputConfig

wl_input_rules = {
    "1267:12377:ELAN1300:00 04F3:3059 Touchpad": InputConfig(left_handed=True),
    "*": InputConfig(left_handed=True, pointer_accel=True),
    "type:keyboard": InputConfig(kb_options="ctrl:nocaps,compose:ralt"),
}

When a input device is being configured, the most specific matching key in the dictionary is found and the corresponding settings are used to configure the device. Unique identifiers are chosen first, then "type:X", then "*".

The command qtile cmd-obj -o core -f get_inputs can be used to get information about connected devices, including their identifiers.

Options default to None, leave a device's default settings intact. For information on what each option does, see the documenation for libinput: https://wayland.freedesktop.org/libinput/doc/latest/configuration.html. Note that devices often only support a subset of settings.

This tries to mirror how Sway configures libinput devices. For more information check out sway-input(5): https://man.archlinux.org/man/sway-input.5#LIBINPUT_CONFIGURATION

Keyboards, managed by xkbcommon, are configured with the options prefixed by kb_. X11's helpful XKB guide may be useful for figuring out the syntax for some of these settings.

key

default

description

accel_profile

None

'adaptive' or 'flat'

click_method

None

'none', 'button_areas' or 'clickfinger'

drag

None

True or False

drag_lock

None

True or False

dwt

None

True or False

kb_layout

None

Keyboard layout i.e. XKB_DEFAULT_LAYOUT

kb_options

None

Keyboard options i.e. XKB_DEFAULT_OPTIONS

kb_repeat_delay

600

Keyboard delay in milliseconds before repeating

kb_repeat_rate

25

Keyboard key repeats made per second

kb_variant

None

Keyboard variant i.e. XKB_DEFAULT_VARIANT

left_handed

None

True or False

middle_emulation

None

True or False

natural_scroll

None

True or False

pointer_accel

None

A float between -1 and 1.

scroll_button

None

'disable', 'Button[1-3,8,9]' or a keycode

scroll_method

None

'none', 'two_finger', 'edge', or 'on_button_down'

tap

None

True or False

tap_button_map

None

'lrm' or 'lmr'

If you want to change keyboard configuration during runtime, you can use the core's set_keymap command (see below).

Core Commands

Core

class libqtile.backend.wayland.core.Core(*args, **kwargs)[source]
change_vt(vt: int) bool[source]

Change virtual terminal to that specified

commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

eval(code: str) tuple[bool, str | None]

Evaluates code in the same context as this function

Return value is tuple (success, result), success being a boolean and result being a string representing the return value of eval, or None if exec was used instead.

function(function, *args, **kwargs) None

Call a function with current object as argument

get_inputs() dict[str, list[dict[str, str]]][source]

Get information on all input devices.

hide_cursor() None[source]

Hide the cursor.

info() dict[str, Any][source]

Get basic information about the running backend.

items(name: str) tuple[bool, list[str | int] | None]

Build a list of contained items for the given item class.

Exposing this allows __qsh__ to navigate the object graph.

Returns a tuple (root, items) for the specified item class, where:

root: True if this class accepts a "naked" specification without an item seletion (e.g. "layout" defaults to current layout), and False if it does not (e.g. no default "widget").

items: a list of contained items

set_keymap(layout: Optional[str] = None, options: Optional[str] = None, variant: Optional[str] = None) None[source]

Set the keymap for the current keyboard.

The options correspond to xkbcommon configuration environmental variables and if not specified are taken from the environment. Acceptable values are strings identical to those accepted by the env variables.

unhide_cursor() None[source]

Unhide the cursor.