This page provides an overview of the various interfaces available to interact with Qtile's command graph.

  • lazy calls

  • when running qtile shell

  • when running qtile cmd-obj

  • when using CommandClient or InteractiveCommandClient in python

The way that these commands are called varies depending on which option you select. However, all interfaces follow the same, basic approach: navigate to the desired object and then execute a command on that object. The following examples illustrate this principle by showing how the same command can be accessed by the various interfaces:

Lazy call:

qtile shell:
> cd widget/volume
widget[volume] > increase_volume()

qtile cmd-obj:
qtile cmd-obj -o widget volume -f increase_volume

>>> from libqtile.command.client import CommandClient
>>> c = CommandClient()
>>> c.navigate("widget", "volume").call("increase_volume")

>>> from libqtile.command.client import InteractiveCommandClient
>>> c = InteractiveCommandClient()
>>> c.widget["volume"].increase_volume()

The Interfaces

From the examples above, you can see that there are five main interfaces which can be used to interact with Qtile's command graph. Which one you choose will depend on how you intend to use it as each interface is suited to different scenarios.

  • The lazy interface is used in config scripts to bind commands to keys and mouse callbacks.

  • The qtile shell is a tool for exploring the graph by presenting it as a file structure. It is not designed to be used for scripting.

  • For users creating shell scripts, the qtile cmd-obj interface would be the recommended choice.

  • For users wanting to control Qtile from a python script, there are two available interfaces libqtile.command.client.CommandClient and libqtile.command.client.InteractiveCommandClient. Users are advised to use the InteractiveCommandClient as this simplifies the syntax for navigating the graph and calling commands.

The Lazy interface

The lazy.lazy object is a special helper object to specify a command for later execution. Lazy objects are typically users' first exposure to Qtile's command graph but they may not realise it. However, understanding this will help users when they try using some of the other interfaces listed on this page.

The basic syntax for a lazy command is:


No node is required when accessing commands on the root node. In addition, multiple nodes can be sequenced if required to navigate to a specific object. For example, bind a key that would focus the next window on the active group on screen 2, you would create a lazy object as follows:



As noted above, lazy calls do not call the relevant command but only create a reference to it. While this makes it ideal for binding commands to key presses and mouse_callbacks for widgets, it also means that lazy calls cannot be included in user-defined functions.

qtile shell

The qtile shell maps the command graph to a virtual filesystem that can be navigated in a similar way. While it is unlikely to be used for scripting, the qtile shell interface provides an excellent means for users to navigate and familiarise themselves with the command graph.

For more information, please refer to qtile shell

qtile cmd-obj

qtile cmd-obj is a command line interface for executing commands on the command graph. It can be used as a standalone command (e.g. executed directly from the terminal) or incorporated into shell scripts.

For more information, please refer to qtile cmd-obj


The CommandClient interface is a low-level python interface for accessing and navigating the command graph. The low-level nature means that navigation steps must be called explicitly, rather than being inferred from the body of the calling command.

For example:

from libqtile.command.client import CommandClient

c = CommandClient()

# Call info command on clock widget
info = c.navigate("widget", "clock").call("info")

# Call info command on the screen displaying the clock widget
info = c.navigate("widget", "clock").navigate("screen", None).call("info")

Note from the last example that each navigation step must be called separately. The arguments passed to navigate() are node and selector. selector is None when you wish to access the default object on that node (e.g. the current screen).

More technical explanation about the python command clients can be found at Executing graph commands: Command Interface.


The InteractiveCommandClient is likely to be the more popular interface for users wishing to access the command graph via external python scripts. One of the key differences between the InteractiveCommandClient and the above CommandClient is that the InteractiveCommandClient removes the need to call navigate and call explicitly. Instead, the syntax mimics that of the lazy interface.

For example, to call the same commands in the above example:

from libqtile.command.client import InteractiveCommandClient

c = InteractiveCommandClient()

# Call info command on clock widget
info = c.widget["clock"].info()

# Call info command on the screen displaying the clock widget
info = c.widget["clock"]