Groups¶

A group is a container for a bunch of windows, analogous to workspaces in other window managers. Each client window managed by the window manager belongs to exactly one group. The groups config file variable should be initialized to a list of libqtile.config.Group objects.

libqtile.config.Group objects provide several options for group configuration. Groups can be configured to show and hide themselves when they're not empty, spawn applications for them when they start, automatically acquire certain groups, and various other options.

Group¶

Example¶

from libqtile.config import Group, Match

groups = [
    Group("a"),
    Group("b"),
    Group("c", matches=[Match(wm_class=["Firefox"])]),
]

# allow mod3+1 through mod3+0 to bind to groups; if you bind your groups
# by hand in your config, you don't need to do this.
from libqtile.dgroups import simple_key_binder

dgroups_key_binder = simple_key_binder("mod3")

Reference¶

Group ¶

Group(
    name: str,
    matches: list[Match] | None = None,
    exclusive: bool = False,
    spawn: str | list[str] | None = None,
    layout: str | None = None,
    layouts: list[Layout] | None = None,
    persist: bool = True,
    init: bool = True,
    layout_opts: dict[str, Any] | None = None,
    screen_affinity: int | None = None,
    position: int = maxsize,
    label: str | None = None,
)

Represents a "dynamic" group.

These groups can spawn apps, only allow certain Matched windows to be on them, hide when they're not in use, etc. Groups are identified by their name.

Parameters:

name (str) –

The name of this group.
matches (list[Match] | None, default: None ) –

List of [Match][Match] objects whose matched windows will be assigned to this group.
exclusive (bool, default: False ) –

When other apps are started in this group, should we allow them here or not?
spawn (str | list[str] | None, default: None ) –

This will be executed (via qtile.spawn()) when the group is created. You can pass either a program name or a list of programs to exec().
layout (str | None, default: None ) –

The name of default layout for this group (e.g. "max"). This is the name specified for a particular layout in config.py or if not defined it defaults in general to the class name in all lower case.
layouts (list[Layout] | None, default: None ) –

The group layouts list overriding global layouts. Use this to define a separate list of layouts for this particular group.
persist (bool, default: True ) –

Should this group stay alive when it has no member windows?
init (bool, default: True ) –

Should this group be alive when Qtile starts?
layout_opts (dict[str, Any] | None, default: None ) –

Options to pass to a layout.
screen_affinity (int | None, default: None ) –

Make a dynamic group prefer to start on a specific screen.
position (int, default: maxsize ) –

The position of this group.
label (str | None, default: None ) –

The display name of the group. Use this to define a display name other than name of the group. If set to None, the display name is set to the name.

simple_key_binder ¶

simple_key_binder(mod, keynames=None)

Bind keys to mod+group position or to the keys specified as second argument.

Group Matching¶

Match ¶

Match(
    title: str | Pattern | None = None,
    wm_class: str | Pattern | None = None,
    role: str | Pattern | None = None,
    wm_type: str | Pattern | None = None,
    wm_instance_class: str | Pattern | None = None,
    net_wm_pid: int | None = None,
    func: Callable[[Window], bool] | None = None,
    wid: int | None = None,
)

Bases: _Match

Window properties to compare (match) with a window.

The properties will be compared to a [libqtile.base.Window][libqtile.base.Window] to determine if its properties match. It can match by title, wm_class, role, wm_type, wm_instance_class, net_wm_pid, or wid. Additionally, a function may be passed, which takes in the [libqtile.base.Window][libqtile.base.Window] to be compared against and returns a boolean.

For some properties, [Match][Match] supports both regular expression objects (i.e. the result of re.compile()) or strings (match as an exact string). If a window matches all specified values, it is considered a match.

Parameters:

title (str | Pattern | None, default: None ) –

Match against the WM_NAME atom (X11) or title (Wayland).
wm_class (str | Pattern | None, default: None ) –

Match against any value in the whole WM_CLASS atom (X11) or app ID (Wayland).
role (str | Pattern | None, default: None ) –

Match against the WM_ROLE atom (X11 only).
wm_type (str | Pattern | None, default: None ) –

Match against the WM_TYPE atom (X11 only).
wm_instance_class (str | Pattern | None, default: None ) –

Match against the first string in WM_CLASS atom (X11) or app ID (Wayland).
net_wm_pid (int | None, default: None ) –

Match against the _NET_WM_PID atom (X11) or PID (Wayland).
func (Callable[[Window], bool] | None, default: None ) –

Delegate the match to the given function, which receives the tested client as an argument and must return True if it matches, False otherwise.
wid (int | None, default: None ) –

Match against the window ID. This is a unique ID given to each window.

Methods:

map –

Apply callback to each client that matches this Match.

map ¶

map(
    callback: Callable[[Window], Any], clients: list[Window]
) -> None

Apply callback to each client that matches this Match.

Rule ¶

Rule(
    match: _Match | list[_Match],
    group: _Group | None = None,
    float: bool = False,
    intrusive: bool = False,
    break_on_match: bool = True,
)

How to act on a match.

A [Rule][Rule] contains a list of [Match][Match] objects, and a specification about what to do when any of them is matched.

Parameters:

match (_Match | list[_Match]) –

[Match][Match] object or a list of such associated with this rule.
float (bool, default: False ) –

Should we auto float this window?
intrusive (bool, default: False ) –

Should we override the group's exclusive setting?
break_on_match (bool, default: True ) –

Should we stop applying rules if this rule is matched?

libqtile.config.ScratchPad is a special - by default invisible - group which acts as a container for libqtile.config.DropDown configurations. A libqtile.config.DropDown can be configured to spawn a defined process and bind thats process' window to it. The associated window can then be shown and hidden by the lazy command [dropdown_toggle][dropdown_toggle] (see lazy objects) from the ScratchPad group. Thus - for example - your favorite terminal emulator turns into a quake-like terminal by the control of Qtile.

If the DropDown window turns visible it is placed as a floating window on top of the current group. If the DropDown is hidden, it is simply switched back to the ScratchPad group.

Example¶

from libqtile.config import Group, ScratchPad, DropDown, Key
from libqtile.lazy import lazy

groups = [
    ScratchPad("scratchpad", [
        # define a drop down terminal.
        # it is placed in the upper third of screen by default.
        DropDown("term", "urxvt", opacity=0.8),

        # define another terminal exclusively for `qtile shell` at different position
        DropDown("qtile shell", "urxvt -hold -e 'qtile shell'",
                  x=0.05, y=0.4, width=0.9, height=0.6, opacity=0.9,
                  on_focus_lost_hide=True) ]),
    Group("a"),
]

keys = [
    # toggle visibiliy of above defined DropDown named "term"
    Key([], 'F11', lazy.group['scratchpad'].dropdown_toggle('term')),
    Key([], 'F12', lazy.group['scratchpad'].dropdown_toggle('qtile shell')),
]

Note that if the window is set to not floating, it is detached from DropDown and ScratchPad, and a new process is spawned next time the DropDown is set visible.

Some programs run in a server-like mode where the spawned process does not directly own the window that is created, which is instead created by a background process. In this case, the window may not be correctly caught in the scratchpad group. To work around this, you can pass a libqtile.config.Match object to the corresponding libqtile.config.DropDown. See below.

Reference¶

ScratchPad ¶

ScratchPad(
    name: str,
    dropdowns: list[DropDown] | None = None,
    position: int = maxsize,
    label: str = "",
    single: bool = False,
)

Bases: Group

Represents a "ScratchPad" group.

ScratchPad adds a (by default) invisible group to Qtile. That group is used as a place for currently not visible windows spawned by a [DropDown][DropDown] configuration.

Parameters:

name (str) –

The name of this group.
dropdowns (list[DropDown] | None, default: None ) –

[DropDown][DropDown] s available on the scratchpad.
position (int, default: maxsize ) –

The position of this group.
label (str, default: '' ) –

The display name of the [ScratchPad][ScratchPad] group. Defaults to the empty string such that the group is hidden in libqtile.widget.GroupBox widget.
single (bool, default: False ) –

If True, only one of the dropdowns will be visible at a time.

DropDown ¶

DropDown(name: str, cmd: str, **config: Any)

Bases: Configurable

Configure a specified command and its associated window for the [ScratchPad][ScratchPad].

That window can be shown and hidden using a configurable keystroke or any other scripted trigger.

Define a command to spawn a process for the first time the class:DropDown is shown.

Parameters:

name (str) –

The name of the dropdown.
cmd (str) –

Command to spawn a window to be captured by the dropdown.

Methods:

add_defaults –

Add defaults to this object, overwriting any which already exist.

add_defaults ¶

add_defaults(defaults)

Add defaults to this object, overwriting any which already exist.

Groups¶

Group¶

Example¶

Reference¶

Group ¶

simple_key_binder ¶

Group Matching¶

Match ¶

map ¶

Rule ¶

ScratchPad and DropDown¶

Example¶

Reference¶

ScratchPad ¶

DropDown ¶

add_defaults ¶