Scripting Commands

Here is documented some of the commands available on objects in the command tree when running qtile shell or scripting commands to qtile. Note that this is an incomplete list, some objects, such as layouts and widgets, may implement their own set of commands beyond those given here.

Qtile

class libqtile.core.manager.Qtile(*args, **kwargs)[source]

This object is the root of the command graph

add_rule(match_args: dict[str, Any], rule_args: dict[str, Any], min_priorty: bool = False) int | None[source]

Add a dgroup rule, returns rule_id needed to remove it

Parameters
match_args

config.Match arguments

rule_args

config.Rule arguments

min_priorty

If the rule is added with minimum priority (last) (default: False)

addgroup(group: str, label: str | None = None, layout: str | None = None, layouts: list[Layout] | None = None) bool[source]

Add a group with the given name

commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

critical() None[source]

Set log level to CRITICAL

debug() None[source]

Set log level to DEBUG

delgroup(group: str) None[source]

Delete a group with the given name

display_kb() str[source]

Display table of key bindings

doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

error() None[source]

Set log level to ERROR

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.

findwindow(prompt: str = 'window', widget: str = 'prompt') None[source]

Launch prompt widget to find a window of the given name

Parameters
prompt

Text with which to prompt user (default: "window")

widget

Name of the prompt widget (default: "prompt")

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

Call a function with current object as argument

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

Return a dictionary containing information for all groups

Examples

get_groups()

get_screens() list[dict[str, Any]][source]

Return a list of dictionaries providing information on all screens

get_state() str[source]

Get pickled state for restarting qtile

get_test_data() Any[source]

Returns any content arbitrarily set in the self.test_data attribute. Useful in tests.

hide_show_bar(position: Literal['top', 'bottom', 'left', 'right', 'all'] = 'all') None[source]

Toggle visibility of a given bar

Parameters
position

one of: "top", "bottom", "left", "right", or "all" (default: "all")

info() None[source]

Set log level to INFO

internal_windows() list[dict[str, Any]][source]

Return info for each internal window (bars, for example)

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

labelgroup(prompt: str = 'label', widget: str = 'prompt') None[source]

Launch prompt widget to label the current group

Parameters
prompt

Text with which to prompt user (default: "label")

widget

Name of the prompt widget (default: "prompt")

list_widgets() list[str][source]

List of all addressible widget names

loglevel() int[source]
loglevelname() str[source]
next_layout(name: Optional[str] = None) None[source]

Switch to the next layout.

Parameters
name

Group name. If not specified, the current group is assumed

next_screen() None[source]

Move to next screen

next_urgent() None[source]

Focus next window with urgent hint

pause() None[source]

Drops into pdb

prev_layout(name: Optional[str] = None) None[source]

Switch to the previous layout.

Parameters
name

Group name. If not specified, the current group is assumed

prev_screen() None[source]

Move to the previous screen

qtile_info() dict[source]

Returns a dictionary of info on the Qtile instance

qtilecmd(prompt: str = 'command', widget: str = 'prompt', messenger: str = 'xmessage') None[source]

Execute a Qtile command using the client syntax

Tab completion aids navigation of the command tree

Parameters
prompt

Text to display at the prompt (default: "command: ")

widget

Name of the prompt widget (default: "prompt")

messenger

Command to display output, set this to None to disable (default: "xmessage")

reconfigure_screens(ev: Any = None) None[source]

This can be used to set up screens again during run time. Intended usage is to be called when the screen_change hook is fired, responding to changes in physical monitor setup by configuring qtile.screens accordingly. The ev kwarg is ignored; it is here in case this function is hooked directly to screen_change.

reload_config() None[source]

Reload the configuration file.

Can also be triggered by sending Qtile a SIGUSR1 signal.

remove_rule(rule_id: int) None[source]

Remove a dgroup rule by rule_id

restart() None[source]

Restart Qtile.

Can also be triggered by sending Qtile a SIGUSR2 signal.

run_extension(extension: _Extension) None[source]

Run extensions

shutdown() None[source]

Quit Qtile

simulate_keypress(modifiers: list[str], key: str) None[source]

Simulates a keypress on the focused window.

Parameters
modifiers

A list of modifier specification strings. Modifiers can be one of "shift", "lock", "control" and "mod1" - "mod5".

key

Key specification.

Examples

simulate_keypress(["control", "mod2"], "k")

spawn(cmd: str | list[str], shell: bool = False) int[source]

Spawn a new process.

Parameters
cmd:

The command to execute either as a single string or list of strings.

shell:

Whether to execute the command in a new shell by prepending it with "/bin/sh -c". This enables the use of shell syntax within the command (e.g. pipes).

Examples

spawn("firefox")

spawn(["xterm", "-T", "Temporary terminal"])

spawn("screenshot | xclip", shell=True)

spawncmd(prompt: str = 'spawn', widget: str = 'prompt', command: str = '%s', complete: str = 'cmd', shell: bool = True, aliases: Optional[dict[str, str]] = None) None[source]

Spawn a command using a prompt widget, with tab-completion.

Parameters
prompt

Text with which to prompt user (default: "spawn: ").

widget

Name of the prompt widget (default: "prompt").

command

command template (default: "%s").

complete

Tab completion function (default: "cmd")

shell

Execute the command with /bin/sh (default: True)

aliases

Dictionary mapping aliases to commands. If the entered command is a key in this dict, the command it maps to will be executed instead.

status() Literal['OK'][source]

Return "OK" if Qtile is running

switch_groups(namea: str, nameb: str) None[source]

Switch position of two groups by name

switchgroup(prompt: str = 'group', widget: str = 'prompt') None[source]

Launch prompt widget to switch to a given group to the current screen

Parameters
prompt

Text with which to prompt user (default: "group")

widget

Name of the prompt widget (default: "prompt")

sync() None[source]

Sync the backend's event queue. Should only be used for development.

to_layout_index(index: str, name: Optional[str] = None) None[source]

Switch to the layout with the given index in self.layouts.

Parameters
index

Index of the layout in the list of layouts.

name

Group name. If not specified, the current group is assumed.

to_screen(n: int) None[source]

Warp focus to screen n, where n is a 0-based screen number

Examples

to_screen(0)

togroup(prompt: str = 'group', widget: str = 'prompt') None[source]

Launch prompt widget to move current window to a given group

Parameters
prompt

Text with which to prompt user (default: "group")

widget

Name of the prompt widget (default: "prompt")

tracemalloc_dump() tuple[bool, str][source]

Dump tracemalloc snapshot

tracemalloc_toggle() None[source]

Toggle tracemalloc status

Running tracemalloc is required for qtile top

ungrab_all_chords() None[source]

Leave all chord modes and grab the root bindings

ungrab_chord() None[source]

Leave a chord mode

validate_config() None[source]
warning() None[source]

Set log level to WARNING

windows() list[dict[str, Any]][source]

Return info for each client window

Bar

class libqtile.bar.Bar(*args, **kwargs)[source]

A bar, which can contain widgets

Parameters
widgets

A list of widget objects.

size

The "thickness" of the bar, i.e. the height of a horizontal bar, or the width of a vertical bar.

key

default

description

background

'#000000'

Background colour.

border_color

'#000000'

Border colour as str or list of str [N E S W]

border_width

0

Width of border as int of list of ints [N E S W]

margin

0

Space around bar as int or list of ints [N E S W].

opacity

1

Bar window opacity.

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.

fake_button_press(screen, position, x, y, button=1)[source]

Fake a mouse-button-press on the bar. Co-ordinates are relative to the top-left corner of the bar.

:screen The integer screen offset :position One of "top", "bottom", "left", or "right"

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

Call a function with current object as argument

info()[source]

Info for this object.

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

Group

class libqtile.config.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 = 9223372036854775807, label: str | None = None)[source]

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:

The name of this group.

matches:

List of Match objects whose matched windows will be assigned to this group.

exclusive:

When other apps are started in this group, should we allow them here or not?

spawn:

This will be exec() d when the group is created. Tou can pass either a program name or a list of programs to exec()

layout:

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:

The group layouts list overriding global layouts. Use this to define a separate list of layouts for this particular group.

persist:

Should this group stay alive when it has no member windows?

init:

Should this group be alive when Qtile starts?

layout_opts:

Options to pass to a layout.

screen_affinity:

Make a dynamic group prefer to start on a specific screen.

position:

The position of this group.

label:

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.

Screen

class libqtile.config.Screen(*args, **kwargs)[source]

A physical screen, and its associated paraphernalia.

Define a screen with a given set of Bar`s of a specific geometry. Also, ``x`, y, width, and height aren't specified usually unless you are using 'fake screens'.

The wallpaper parameter, if given, should be a path to an image file. How this image is painted to the screen is specified by the wallpaper_mode parameter. By default, the image will be placed at the screens origin and retain its own dimensions. If the mode is "fill", the image will be centred on the screen and resized to fill it. If the mode is "stretch", the image is stretched to fit all of it into the screen.

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

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

Returns a dictionary of info for this screen.

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

next_group(skip_empty: bool = False, skip_managed: bool = False) None[source]

Switch to the next group

prev_group(skip_empty: bool = False, skip_managed: bool = False, warp: bool = True) None[source]

Switch to the previous group

resize(x: Optional[int] = None, y: Optional[int] = None, w: Optional[int] = None, h: Optional[int] = None) None[source]
set_wallpaper(path: str, mode: Optional[str] = None) None[source]

Set the wallpaper to the given file.

toggle_group(group_name: Optional[str] = None, warp: bool = True) None[source]

Switch to the selected group or to the previously active one

Window

class libqtile.backend.base.Window(*args, **kwargs)[source]

A regular Window belonging to a client.

Abstract methods are required to be defined as part of a specific backend's implementation. Non-abstract methods have default implementations here to be shared across backends.

abstract bring_to_front() None[source]

Bring the window to the front

center() None[source]

Centers a floating window on the screen.

commands() list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

abstract disable_floating() None[source]

Tile the window.

abstract disable_fullscreen() None[source]

Un-fullscreen the window

doc(name) str

Returns the documentation for a specified command name

Used by __qsh__ to provide online help.

down_opacity() None[source]

Decrease the window's opacity by 10%.

abstract enable_floating() None[source]

Float the window.

abstract enable_fullscreen() None[source]

Fullscreen the window

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.

abstract focus(warp: bool = True) None[source]

Focus this window and optional warp the pointer to it.

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

Call a function with current object as argument

abstract get_position() tuple[int, int][source]

Get the (x, y) of the window

abstract get_size() tuple[int, int][source]

Get the (width, height) of the window

abstract info() dict[str, Any]

Return information on this window.

Mimimum required keys are: - name - x - y - width - height - group - id - wm_class

is_visible() bool

Is this window visible (i.e. not hidden)?

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

abstract kill() None

Kill the window

abstract move_floating(dx: int, dy: int) None[source]

Move window by dx and dy

abstract place(x, y, width, height, borderwidth, bordercolor, above=False, margin=None, respect_hints=False)

Place the window in the given position.

abstract resize_floating(dw: int, dh: int) None[source]

Add dw and dh to size of window

set_opacity(opacity: float) None[source]

Set the window's opacity

abstract set_position(x: int, y: int) None[source]

Move floating window to x and y; swap tiling window with the window under the pointer.

abstract set_position_floating(x: int, y: int) None[source]

Move window to x and y

abstract set_size_floating(w: int, h: int) None[source]

Set window dimensions to w and h

abstract static(screen: Optional[int] = None, x: Optional[int] = None, y: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None) None[source]

Makes this window a static window, attached to a Screen.

Values left unspecified are taken from the existing window state.

abstract toggle_floating() None[source]

Toggle the floating state of the window.

abstract toggle_fullscreen() None[source]

Toggle the fullscreen state of the window.

abstract toggle_maximize() None[source]

Toggle the fullscreen state of the window.

abstract toggle_minimize() None[source]

Toggle the minimized state of the window.

abstract togroup(group_name: Optional[str] = None, groupName: Optional[str] = None, switch_group: bool = False, toggle: bool = False) None[source]

Move window to a specified group

Also switch to that group if switch_group is True.

If toggle is True and and the specified group is already on the screen, use the last used group as target instead.

groupName is deprecated and will be dropped soon. Please use group_name instead.

Examples

Move window to current group:

togroup()

Move window to group "a":

togroup("a")

Move window to group "a", and switch to group "a":

togroup("a", switch_group=True)
toscreen(index: Optional[int] = None) None[source]

Move window to a specified screen.

If index is not specified, we assume the current screen

Examples

Move window to current screen:

toscreen()

Move window to screen 0:

toscreen(0)
up_opacity() None[source]

Increase the window's opacity by 10%.