Qtile root object

The root node represents the main Qtile manager instance. Many of the commands on this node are therefore related to the running of the application itself.

The root can access every other node in the command graph. Certain objects can be accessed without a selector resulting in the current object being selected (e.g. current group, screen, layout, window).

class libqtile.core.manager.Qtile

API commands

To access commands on this object via the command graph, use one of the following options:

lazy.<command>()

qtile cmd-obj -o cmd -f <command>

The following commands are available for this object:

add_rule(match_args, rule_args[, min_priorty])	Add a dgroup rule, returns rule_id needed to remove it
addgroup(group[, label, layout, layouts, ...])	Add a group with the given name
change_window_order(new_location)	Change the order of the current window within the current group.
commands()	Returns a list of possible commands for this object
critical()	Set log level to CRITICAL
debug()	Set log level to DEBUG
delgroup(group)	Delete a group with the given name
display_kb()	Display table of key bindings
doc(name)	Returns the documentation for a specified command name
error()	Set log level to ERROR
eval(code)	Evaluates code in the same context as this function
findwindow([prompt, widget])	Launch prompt widget to find a window of the given name
fire_user_hook(hook_name, *args)	Fire a custom hook.
function(function, *args, **kwargs)	Call a function with current object as argument
get_groups()	Return a dictionary containing information for all groups
get_screens()	Return a list of dictionaries providing information on all screens
get_state()	Get pickled state for restarting qtile
get_test_data()	Returns any content arbitrarily set in the self.test_data attribute.
hide_show_bar([position, screen])	Toggle visibility of a given bar
info()	Set log level to INFO
internal_windows()	Return info for each internal window (bars, for example)
items(name)	Build a list of contained items for the given item class.
labelgroup([prompt, widget])	Launch prompt widget to label the current group
list_widgets()	List of all addressible widget names
loglevel()
loglevelname()
next_layout([name])	Switch to the next layout.
next_screen()	Move to next screen
next_urgent()	Focus next window with urgent hint
pause()	Drops into pdb
prev_layout([name])	Switch to the previous layout.
prev_screen()	Move to the previous screen
qtile_info()	Returns a dictionary of info on the Qtile instance
qtilecmd([prompt, widget, messenger])	Execute a Qtile command using the client syntax
reconfigure_screens(*_, **__)	This can be used to set up screens again during run time.
reload_config()	Reload the configuration file.
remove_rule(rule_id)	Remove a dgroup rule by rule_id
restart()	Restart Qtile.
run_extension(extension)	Run extensions
shutdown([exitcode])	Quit Qtile
simulate_keypress(modifiers, key)	Simulates a keypress on the focused window.
spawn(cmd[, shell, env])	Spawn a new process.
spawncmd([prompt, widget, command, ...])	Spawn a command using a prompt widget, with tab-completion.
status()	Return "OK" if Qtile is running
switch_groups(namea, nameb)	Switch position of two groups by name
switch_window(location)	Change to the window at the specified index in the current group.
switchgroup([prompt, widget])	Launch prompt widget to switch to a given group to the current screen
sync()	Sync the backend's event queue.
to_layout_index(index[, name])	Switch to the layout with the given index in self.layouts.
to_screen(n)	Warp focus to screen n, where n is a 0-based screen number
togroup([prompt, widget])	Launch prompt widget to move current window to a given group
tracemalloc_dump()	Dump tracemalloc snapshot
tracemalloc_toggle()	Toggle tracemalloc status
ungrab_all_chords()	Leave all chord modes and grab the root bindings
ungrab_chord()	Leave a chord mode
validate_config()
warning()	Set log level to WARNING
windows()	Return info for each client window

Command documentation

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

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, index: int | None = None, persist: bool | None = False) → bool

Add a group with the given name

change_window_order(new_location: int) → None

Change the order of the current window within the current group.

commands() → list[str]

Returns a list of possible commands for this object

Used by __qsh__ for command completion and online help

critical() → None

Set log level to CRITICAL

debug() → None

Set log level to DEBUG

delgroup(group: str) → None

Delete a group with the given name

display_kb() → str

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

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

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")

fire_user_hook(hook_name: str, *args: Any) → None

Fire a custom hook.

function(function, *args, **kwargs) → Task | None

Call a function with current object as argument

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

Return a dictionary containing information for all groups

Examples

get_groups()

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

Return a list of dictionaries providing information on all screens

get_state() → str

Get pickled state for restarting qtile

get_test_data() → Any

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', screen: Literal['current', 'all'] = 'current') → None

Toggle visibility of a given bar

Parameters:

position

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

screen

one of: "current", "all" (default: "current")

info() → None

Set log level to INFO

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

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 command 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

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]

List of all addressible widget names

loglevel() → int

loglevelname() → str

next_layout(name: str | None = None) → None

Switch to the next layout.

Parameters:

name

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

next_screen() → None

Move to next screen

next_urgent() → None

Focus next window with urgent hint

pause() → None

Drops into pdb

prev_layout(name: str | None = None) → None

Switch to the previous layout.

Parameters:

name

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

prev_screen() → None

Move to the previous screen

qtile_info() → dict

Returns a dictionary of info on the Qtile instance

qtilecmd(prompt: str = 'command', widget: str = 'prompt', messenger: str = 'xmessage') → None

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(*_: list[Any], **__: dict[Any, Any]) → None

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 args are ignored; it is here in case this function is hooked directly to screen_change.

reload_config() → None

Reload the configuration file.

Can also be triggered by sending Qtile a SIGUSR1 signal.

remove_rule(rule_id: int) → None

Remove a dgroup rule by rule_id

restart() → None

Restart Qtile.

Can also be triggered by sending Qtile a SIGUSR2 signal.

run_extension(extension: _Extension) → None

Run extensions

shutdown(exitcode: int = 0) → None

Quit Qtile

Parameters:

exitcode

Set exit status of Qtile. Can be e.g. used to make login managers poweroff or restart the system. (default: 0)

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

Simulates a keypress on the focused window.

This triggers internal bindings only; for full simulation see external tools such as xdotool or ydotool.

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: list[str] | str, shell: bool = False, env: dict[str, str] = {}) → int

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).

env:

Dictionary of environmental variables to pass with command.

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: dict[str, str] | None = None) → None

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']

Return "OK" if Qtile is running

switch_groups(namea: str, nameb: str) → None

Switch position of two groups by name

switch_window(location: int) → None

Change to the window at the specified index in the current group.

switchgroup(prompt: str = 'group', widget: str = 'prompt') → None

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

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

to_layout_index(index: int, name: str | None = None) → None

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

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

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]

Dump tracemalloc snapshot

tracemalloc_toggle() → None

Toggle tracemalloc status

Running tracemalloc is required for qtile top

ungrab_all_chords() → None

Leave all chord modes and grab the root bindings

ungrab_chord() → None

Leave a chord mode

validate_config() → None

warning() → None

Set log level to WARNING

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

Return info for each client window