Distro Guides¶

Below are the preferred installation methods for specific distros. If you are running something else, please see Installing From Source.

Installing on Arch Linux¶

Stable versions of Qtile are currently packaged for Arch Linux. To install this package, run:

pacman -S qtile

Please see the ArchWiki for more information on Qtile.

Installing on Fedora 40 or later.¶

Both Qtile X11 and Wayland stable versions can be installed via the DNF Package Manager.

If you want to pick a specific version(Such as the wayland version) then double-click Tab after "qtile".

dnf install qtile

Installing on Funtoo¶

Latest versions of Qtile are available on Funtoo. To install it, run:

emerge -av x11-wm/qtile

You can also install the development version from GitHub:

echo "x11-wm/qtile-9999 **" >> /etc/portage/package.accept_keywords
emerge -av qtile

Customize¶

You can customize your installation with the following useflags:

The dbus useflag is enabled by default. Disable it only if you know what it is and know you don't use/need it.

All widget-* useflags are disabled by default because these widgets require additional dependencies while not everyone will use them. Enable only widgets you need to avoid extra dependencies thanks to these useflags.

Visit Funtoo Qtile documentation for more details on Qtile installation on Funtoo.

Installing on Ubuntu or Debian 11 (bullseye) or greater¶

Ubuntu and Debian >=11 comes with the necessary packages for installing Qtile. Starting from a minimal Debian installation, the following packages are required:

sudo apt install xserver-xorg xinit
sudo apt install libpangocairo-1.0-0
sudo apt install python3-pip python3-xcffib python3-cairocffi

Either Qtile can then be downloaded from the package index or the Github repository can be used, see Installing From Source:

pip install qtile

Installing on Slackware¶

Qtile is available on the SlackBuilds.org as:

Using slpkg (third party package manager)¶

The easy way to install Qtile is with slpkg. For example:

slpkg -s sbo qtile

Manual installation¶

Download dependencies first and install them. The order in which you need to install is:

Please see the HOWTO for more information on SlackBuild Usage HOWTO.

Installing on FreeBSD¶

Qtile is available via FreeBSD Ports. It can be installed with

pkg install qtile

Installing on NixOS¶

Qtile is available in the NixOS repos. To set qtile as your window manager, include this in your configuration.nix file:

services.xserver.windowManager.qtile.enable = true;

Other options for qtile can be declared within the services.xserver.windowManager.qtile attribute set.

You may add extra packages in the qtile python environment by putting them in the extraPackages list.

services.xserver.windowManager.qtile = {


  enable = true;


  extraPackages = python3Packages: with python3Packages; [


    qtile-extras


  ];
};

The Qtile package creates desktop files for both X11 and Wayland, to use one of the backends choose the right session in your display manager.

The configuration file can be changed from its default location ($XDG_CONFIG/qtile/config.py) by setting the configFile attribute:

qtile = {


  enable = true;


  configFile = ./my_qtile_config.py;
};

NOTE:

Home manager¶

If you are using home-manager, you can copy your qtile configuration by using the following:

xdg.configFile."qtile/config.py".source = ./my_qtile_config.py;

or, if you have a directory containing multiple python files:

xdg.configFile."qtile" = {


  source = ./src;


  recursive = true;
};

Flake¶

Qtile also has a flake in the repository. This can be used for the following use cases:

Note that flakes are an experimental NixOS feature but they are already widely used. This section is meant for users that already use flakes.

To run a bleeding edge version of Qtile with the flake, add the Qtile repo to your inputs and define the overlay. An example flake is the following:

{


   description = "A very basic flake";


   inputs = {


     nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";


     qtile-flake = {


       url = "github:qtile/qtile";


       inputs.nixpkgs.follows = "nixpkgs";


     };


   };


   outputs = { self, nixpkgs, qtile-flake }: {


     nixosConfigurations.demo = nixpkgs.lib.nixosSystem {


       system = "x86_64-linux";


       modules = [


         (_: { nixpkgs.overlays = [ qtile-flake.overlays.default ]; })


         ({ config, pkgs, lib, ...}: {


           services.xserver = {


             enable = true;


             windowManager.qtile.enable = true;


           };


           # make qtile X11 the default session


           services.displayManager.defaultSession = lib.mkForce "qtile";


           # rest of your NixOS config


         })


       ];


     };


   };
}

This flake can also be tested with a vm:

sudo nixos-rebuild build-vm --flake .#demo

Gives you a script to run that runs Qemu to test your config. For this to work you have to set a user with a password.

To hack on Qtile with Nix, simply run nix develop in a checkout of the repo. In the development shell, there are a few useful things:

Installing From Source¶

Python interpreters¶

We aim to always support the last three versions of CPython, the reference Python interpreter. We usually support the latest stable version of PyPy as well. You can check the versions and interpreters we currently run our test suite against in our tox configuration file.

There are not many differences between versions aside from Python features you may or may not be able to use in your config. PyPy should be faster at runtime than any corresponding CPython version under most circumstances, especially for bits of Python code that are run many times. CPython should start up faster than PyPy and has better compatibility for external libraries.

Core Dependencies¶

Here are Qtile's core runtime dependencies and the package names that provide them in Ubuntu. Note that Qtile can run with one of two backends -- X11 and Wayland -- so only the dependencies of one of these is required.

Qtile¶

With the dependencies in place, you can now install the stable version of qtile from PyPI:

pip install qtile

Or with sets of dependencies:

pip install qtile[wayland]  # for Wayland dependencies
pip install qtile[widgets]  # for all widget dependencies
pip install qtile[all]      # for all dependencies

Or install qtile-git with:

git clone https://github.com/qtile/qtile.git
cd qtile
pip install .
pip install --config-setting backend=wayland .  # adds wayland dependencies

Starting Qtile¶

There are several ways to start Qtile. The most common way is via an entry in your X session manager's menu. The default Qtile behavior can be invoked by creating a qtile.desktop file in /usr/share/xsessions.

A second way to start Qtile is a custom X session. This way allows you to invoke Qtile with custom arguments, and also allows you to do any setup you want (e.g. special keyboard bindings like mapping caps lock to control, setting your desktop background, etc.) before Qtile starts. If you're using an X session manager, you still may need to create a custom.desktop file similar to the qtile.desktop file above, but with Exec=/etc/X11/xsession. Then, create your own ~/.xsession. There are several examples of user defined xsession s in the qtile-examples repository.

If there is no display manager such as SDDM, LightDM or other and there is need to start Qtile directly from ~/.xinitrc do that by adding exec qtile start at the end.

In very special cases, ex. Qtile crashing during session, then suggestion would be to start through a loop to save running applications:

while true; do


    qtile
done

Wayland¶

Qtile can be run as a Wayland compositor rather than an X11 window manager. For this, Qtile uses wlroots, a compositor library which is undergoing fast development. Be aware that some distributions package outdated versions of wlroots. More up-to-date distributions such as Arch Linux may package pywayland, pywlroots and python-xkbcommon. Also note that we may not have yet caught up with the latest wlroots release ourselves.

NOTE:

With the Wayland dependencies in place, Qtile can be run either from a TTY, or within an existing X11 or Wayland session where it will run inside a nested window:

qtile start -b wayland

See the Wayland page for more information on running Qtile as a Wayland compositor.

Similar to the xsession example above, a wayland session file can be used to start qtile from a login manager. To use this, you should create a qtile-wayland.desktop file in /usr/share/wayland-sessions.

udev rules¶

Qtile has widgets that support managing various kinds of hardware (LCD backlight, keyboard backlight, battery charge thresholds) via the kernel's exposed sysfs endpoints. However, to make this work, Qtile needs permission to write to these files. There is a udev rules file at /resources/99-qtile.rules in the tree, which users installing from source will want to install at /etc/udev/rules.d/ on their system. By default, this rules file changes the group of the relevant files to the sudo group, and changes the file mode to be g+w (i.e. writable by all members of the sudo group). The theory here is that most systems qtile is installed on will also have the primary user in the sudo group. However, you can change this to whatever you like with the --group argument; see the sample udev rules.

Note that this file invokes Qtile's hidden udev from udevd, so udevd will need qtile in its $PATH. For distro packaging this shouldn't be a problem, since /usr/bin is typically in udev's path. However, for users that installed from source, you may need to modify the udev script to be one that sources your virtualenv and then invokes qtile (or just invoke it via its hardcoded path if you installed it with --break-system-packages), e.g.:

# create a wrapper script that loads the right stuff from our home directory; since
# udev will run this script as root, it has no idea about how we've installed qtile
mkdir -p $HOME/.local/bin
tee $HOME/.local/bin/qtile-udev-wrapper <<- EOF
#!/bin/sh
export PYTHONPATH=$HOME/.local/lib/python$(python3 --version | awk -F '[ .]' '{print $2 "." $3}')/site-packages
$HOME/.local/bin/qtile $@
EOF
# copy the in-tree udev rules file to the right place to make udev see it,
# and change the rules to point at our wrapper script above.
sed "s,qtile,$HOME/.local/bin/qtile-udev-wrapper,g" ./resources/99-qtile.rules | sudo tee /etc/udev/rules.d/99-qtile.rules

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 supports XWayland but 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¶

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

Core Commands¶

See the Wayland backend section in the API Commands documentation.

So something has gone wrong... what do you do?¶

When Qtile is running, it logs error messages (and other messages) to its log file. This is found at ~/.local/share/qtile/qtile.log. This is the first place to check to see what is going on. If you are getting unexpected errors from normal usage or your configuration (and you're not doing something wacky) and believe you have found a bug, then please report a bug.

If you are hacking on Qtile and you want to debug your changes, this log is your best friend. You can send messages to the log from within libqtile by using the logger:

from libqtile.log_utils import logger
logger.warning("Your message here")
logger.warning(variable_you_want_to_print)
try:


    # some changes here that might error
except Exception:


    logger.exception("Uh oh!")

logger.warning is convenient because its messages will always be visibile in the log. logger.exception is helpful because it will print the full traceback of an error to the log. By sticking these amongst your changes you can look more closely at the effects of any changes you made to Qtile's internals.

X11: Capturing an xtrace¶

Occasionally, a bug will be low level enough to require an xtrace of Qtile's conversations with the X server. To capture one of these, create an xinitrc or similar file with:

exec xtrace qtile >> ~/qtile.log

This will put the xtrace output in Qtile's logfile as well. You can then demonstrate the bug, and paste the contents of this file into the bug report.

Note that xtrace may be named x11trace on some platforms, for example, on Fedora and Arch.

Debugging in Wayland¶

To get incredibly verbose output of communications between clients and the server, you can set WAYLAND_DEBUG=1 in the environment before starting the process. This applies to the server itself, so be aware that running qtile with this set will generate lots of output for Qtile and all clients that it launches. If you're including this output with a bug report please try to cut out just the relevant portions.

If you're hacking on Qtile and would like this debug log output for it rather than any clients, it can be helpful to run the helper script at scripts/wephyr in the source from an existing session. You can then run clients from another terminal using the WAYLAND_DISPLAY value printed by Qtile, so that the debug logs printed by Qtile are only the server's.

If you suspect a client may be responsible for a bug, it can be helpful to look at the issue trackers for other compositors, such as sway. Similarly if you're hacking on Qtile's internals and think you've found an unexpected quirk it may be helpful to search the issue tracker for wlroots.

qtile start¶

This is the entry point for the window manager, and what you should run from your .xsession or similar. This will make an attempt to detect if qtile is already running and fail if it is. See qtile start --help for more details.

qtile shell¶

The Qtile command shell is a command-line shell interface that provides access to the full complement of Qtile command functions. The shell features command name completion, and full command documentation can be accessed from the shell itself. The shell uses GNU Readline when it's available, so the interface can be configured to, for example, obey VI keybindings with an appropriate .inputrc file. See the GNU Readline documentation for more information.

Navigating the Object Graph¶

The shell presents a filesystem-like interface to the command graph - the builtin "cd" and "ls" commands act like their familiar shell counterparts:

> ls
layout/  widget/  screen/  bar/     window/  group/
> cd screen
layout/  window/  bar/  widget/
> cd ..
/
> ls
layout/  widget/  screen/  bar/     window/  group/

If you try to access an object that has no "default" value then you will see an error message:

> ls
layout/  widget/  screen/  bar/     window/  group/
> cd bar
Item required for bar
> ls bar
bar[bottom]/
> cd bar/bottom
bar['bottom']> ls
screen/  widget/

Please refer to Navigating the command graph for a summary of which objects need a specified selector and the type of selector required. Using ls will show which selectors are available for an object. Please see below for an explanation about how Qtile displays shell paths.

Alternatively, the items() command can be run on the parent object to show which selectors are available. The first value shows whether a selector is optional (False means that a selector is required) and the second value is a list of selectors:

> ls
layout/  widget/  screen/  bar/     window/  group/
> items(bar)
(False, ['bottom'])

Displaying the shell path¶

Note that the shell provides a "short-hand" for specifying node keys (as opposed to children). The following is a valid shell path:

> cd group/4/window/31457314

The command prompt will, however, always display the Python node path that should be used in scripts and key bindings:

group['4'].window[31457314]>

Live Documentation¶

The shell help command provides the canonical documentation for the Qtile API:

> cd layout/1
layout[1]> help
help command   -- Help for a specific command.
Builtins
========
cd    exit  help  ls    q     quit
Commands for this object
========================
add           commands      current       delete        doc
down          get_info      items         next          previous
rotate        shuffle_down  shuffle_up    toggle_split  up
layout[1]> help previous
previous()
Focus previous stack.

qtile migrate¶

qtile migrate is a tool to help users update their configs to reflect any breaking changes/deprecations introduced in later versions.

The tool can automatically apply updates but it can also be used to highlight impacted lines, allowing users to update their configs manually.

The tool can take a number of options when running:

Available migrations¶

The following migrations are currently available.

Running migrations¶

Assuming your config file is in the default location, running qtile migrate is sufficient to start the migration process.

Let's say you had a config file with the following contents:

import libqtile.command_client
keys = [


    KeyChord(


        [mod],


        "x",


        [Key([], "Up", lazy.layout.grow()), Key([], "Down", lazy.layout.shrink())],


        mode="Resize layout",


    )
]
qtile.cmd_spawn("alacritty")

Running qtile migrate will run each available migration and, where the migration would result in changes, a diff will be shown and you will be asked whether you wish to apply the changes.

UpdateKeychordArgs: Updates ``KeyChord`` argument signature.
--- original
+++ modified
@@ -5,7 +5,8 @@


        [mod],


        "x",


        [Key([], "Up", lazy.layout.grow()), Key([], "Down", lazy.layout.shrink())],
-        mode="Resize layout",
+        name="Resize layout",
+    mode=True,


    )
]
Apply changes? (y)es, (n)o, (s)kip file, (q)uit.

You will see from the output above that you are shown the name of the migration being applied and its purpose, along with the changes that will be implemented.

If you select quit the migration will be stopped and any applied changes will be reversed.

Once all migrations have been run on a file, you will then be asked whether you want to save changes to the file:

Save all changes to config.py? (y)es, (n)o.

At the end of the migration, backups of your original config will still be in your config folder. NB these will be overwritten if you re-run qtile migrate.

Linting¶

If you don't want the script to modify your config directly, you can use the --lint option to show you where changes are required.

Running qtile migrate --lint on the same config as shown above will result in the following output:

config.py:
[Ln 1, Col 7]: The 'libqtile.command_*' modules have been moved to 'libqtile.command.*'. (ModuleRenames)
[Ln 8, Col 8]: The use of mode='mode name' for KeyChord is deprecated. Use mode=True and value='mode name'. (UpdateKeychordArgs)
[Ln 12, Col 6]: Use of 'cmd_' prefix is deprecated. 'cmd_spawn' should be replaced with 'spawn' (RemoveCmdPrefix)

Explanations of migrations¶

The table below provides more detail of the available migrations.

qtile cmd-obj¶

This is a simple tool to expose qtile.command functionality to shell. This can be used standalone or in other shell scripts.

How it works¶

qtile cmd-obj works by selecting a command object and calling a specified function of that object.

As per Architecture, Qtile's command graph has seven nodes: layout, window, group, bar, widget, screen, and a special root node. These are the objects that can be accessed via qtile cmd-obj.

Running the command against a selected object without a function (-f) will run the help command and list the commands available to the object. Commands shown with an asterisk ("*") require arguments to be passed via the -a flag.

Selecting an object¶

With the exception of cmd, all objects need an identifier so the correct object can be selected. Refer to Navigating the command graph for more information.

NOTE:

Information on functions¶

Running a function with the -i flag will provide additional detail about that function (i.e. what it does and what arguments it expects).

Passing arguments to functions¶

Arguments can be passed to a function by using the -a flag. For example, to change the label for the group named "1" to "A", you would run qtile cmd-obj -o group 1 -f set_label -a A.

WARNING:

Examples:¶

Output of qtile cmd-obj -h¶

usage: qtile cmd-obj [-h] [--object OBJ_SPEC [OBJ_SPEC ...]]


                 [--function FUNCTION] [--args ARGS [ARGS ...]] [--info]
Simple tool to expose qtile.command functionality to shell.
optional arguments:


  -h, --help            show this help message and exit


  --object OBJ_SPEC [OBJ_SPEC ...], -o OBJ_SPEC [OBJ_SPEC ...]


                        Specify path to object (space separated). If no


                        --function flag display available commands.


  --function FUNCTION, -f FUNCTION


                        Select function to execute.


  --args ARGS [ARGS ...], -a ARGS [ARGS ...]


                        Set arguments supplied to function.


  --info, -i            With both --object and --function args prints


                        documentation for function.
Examples:


 qtile cmd-obj


 qtile cmd-obj -o root  # same as above, root node is default


 qtile cmd-obj -o root -f prev_layout -i


 qtile cmd-obj -o root -f prev_layout -a 3 # prev_layout on group 3


 qtile cmd-obj -o group 3 -f focus_back


 qtile cmd-obj -o widget textbox -f update -a "New text"


 qtile cmd-obj -f restart # restart qtile

Output of qtile cmd-obj -o group 3¶

-o group 3 -f commands            Returns a list of possible commands for this object
-o group 3 -f doc               * Returns the documentation for a specified command name
-o group 3 -f eval              * Evaluates code in the same context as this function
-o group 3 -f focus_back          Focus the window that had focus before the current one got it.
-o group 3 -f focus_by_name     * Focus the first window with the given name. Do nothing if the name is
-o group 3 -f function          * Call a function with current object as argument
-o group 3 -f info                Returns a dictionary of info for this group
-o group 3 -f info_by_name      * Get the info for the first window with the given name without giving it
-o group 3 -f items             * Returns a list of contained items for the specified name
-o group 3 -f next_window         Focus the next window in group.
-o group 3 -f prev_window         Focus the previous window in group.
-o group 3 -f set_label         * Set the display name of current group to be used in GroupBox widget.
-o group 3 -f setlayout
-o group 3 -f switch_groups     * Switch position of current group with name
-o group 3 -f toscreen          * Pull a group to a specified screen.
-o group 3 -f unminimize_all      Unminimise all windows in this group

Output of qtile cmd-obj -o root¶

-o root -f add_rule              * Add a dgroup rule, returns rule_id needed to remove it
-o root -f addgroup              * Add a group with the given name
-o root -f commands                Returns a list of possible commands for this object
-o root -f critical                Set log level to CRITICAL
-o root -f debug                   Set log level to DEBUG
-o root -f delgroup              * Delete a group with the given name
-o root -f display_kb            * Display table of key bindings
-o root -f doc                   * Returns the documentation for a specified command name
-o root -f error                   Set log level to ERROR
-o root -f eval                  * Evaluates code in the same context as this function
-o root -f findwindow            * Launch prompt widget to find a window of the given name
-o root -f focus_by_click        * Bring a window to the front
-o root -f function              * Call a function with current object as argument
-o root -f get_info                Prints info for all groups
-o root -f get_state               Get pickled state for restarting qtile
-o root -f get_test_data           Returns any content arbitrarily set in the self.test_data attribute.
-o root -f groups                  Return a dictionary containing information for all groups
-o root -f hide_show_bar         * Toggle visibility of a given bar
-o root -f info                    Set log level to INFO
-o root -f internal_windows        Return info for each internal window (bars, for example)
-o root -f items                 * Returns a list of contained items for the specified name
-o root -f list_widgets            List of all addressible widget names
-o root -f next_layout           * Switch to the next layout.
-o root -f next_screen             Move to next screen
-o root -f next_urgent             Focus next window with urgent hint
-o root -f pause                   Drops into pdb
-o root -f prev_layout           * Switch to the previous layout.
-o root -f prev_screen             Move to the previous screen
-o root -f qtile_info              Returns a dictionary of info on the Qtile instance
-o root -f qtilecmd              * Execute a Qtile command using the client syntax
-o root -f remove_rule           * Remove a dgroup rule by rule_id
-o root -f restart                 Restart qtile
-o root -f run_extension         * Run extensions
-o root -f run_external          * Run external Python script
-o root -f screens                 Return a list of dictionaries providing information on all screens
-o root -f shutdown                Quit Qtile
-o root -f simulate_keypress     * Simulates a keypress on the focused window.
-o root -f spawn                 * Run cmd in a shell.
-o root -f spawncmd              * Spawn a command using a prompt widget, with tab-completion.
-o root -f status                  Return "OK" if Qtile is running
-o root -f switch_groups         * Switch position of groupa to groupb
-o root -f switchgroup           * Launch prompt widget to switch to a given group to the current screen
-o root -f sync                    Sync the X display. Should only be used for development
-o root -f to_layout_index       * Switch to the layout with the given index in self.layouts.
-o root -f to_screen             * Warp focus to screen n, where n is a 0-based screen number
-o root -f togroup               * Launch prompt widget to move current window to a given group
-o root -f tracemalloc_dump        Dump tracemalloc snapshot
-o root -f tracemalloc_toggle      Toggle tracemalloc status
-o root -f warning                 Set log level to WARNING
-o root -f windows                 Return info for each client window

qtile run-cmd¶

Run a command applying rules to the new windows, ie, you can start a window in a specific group, make it floating, intrusive, etc.

The Windows must have NET_WM_PID.

# run xterm floating on group "test-group"
qtile run-cmd -g test-group -f xterm

qtile top¶

qtile top is a top-like tool to measure memory usage of Qtile's internals.

NOTE:

>>> from libqtile.command.client import InteractiveCommandClient
>>> i=InteractiveCommandClient()
>>> i.eval("import tracemalloc;tracemalloc.start()")

dqtile-cmd¶

A Rofi/dmenu interface to qtile-cmd. Accepts all arguments of qtile-cmd.

Examples:¶

Output of dqtile-cmd -o cmd¶

[image]

Output of dqtile-cmd -h¶

dqtile-cmd


    A Rofi/dmenu interface to qtile-cmd. Excepts all arguments of qtile-cmd


    (see below).
usage: dqtile-cmd [-h] [--object OBJ_SPEC [OBJ_SPEC ...]]


                  [--function FUNCTION] [--args ARGS [ARGS ...]] [--info]
Simple tool to expose qtile.command functionality to shell.
optional arguments:


  -h, --help            show this help message and exit


  --object OBJ_SPEC [OBJ_SPEC ...], -o OBJ_SPEC [OBJ_SPEC ...]


                        Specify path to object (space separated). If no


                        --function flag display available commands.


  --function FUNCTION, -f FUNCTION


                        Select function to execute.


  --args ARGS [ARGS ...], -a ARGS [ARGS ...]


                        Set arguments supplied to function.


  --info, -i            With both --object and --function args prints


                        documentation for function.
Examples:


 dqtile-cmd


 dqtile-cmd -o cmd


 dqtile-cmd -o cmd -f prev_layout -i


 dqtile-cmd -o cmd -f prev_layout -a 3 # prev_layout on group 3


 dqtile-cmd -o group 3 -f focus_back
If both rofi and dmenu are present rofi will be selected as default, to change this us --force-dmenu as the first argument.

iqshell¶

In addition to the standard qtile shell shell interface, we provide a kernel capable of running through Jupyter that hooks into the qshell client. The command structure and syntax is the same as qshell, so it is recommended you read that for more information about that.

Dependencies¶

In order to run iqshell, you must have ipykernel and jupyter_console. You can install the dependencies when you are installing qtile by running:

$ pip install qtile[ipython]

Otherwise, you can just install these two packages separately, either through PyPI or through your distribution package manager.

Installing and Running the Kernel¶

Once you have the required dependencies, you can run the kernel right away by running:

$ python3 -m libqtile.interactive.iqshell_kernel

However, this will merely spawn a kernel instance, you will have to run a separate frontend that connects to this kernel.

A more convenient way to run the kernel is by registering the kernel with Jupyter. To register the kernel itself, run:

$ python3 -m libqtile.interactive.iqshell_install

If you run this as a non-root user, or pass the --user flag, this will install to the user Jupyter kernel directory. You can now invoke the kernel directly when starting a Jupyter frontend, for example:

$ jupyter console --kernel qshell

The iqshell script will launch a Jupyter terminal console with the qshell kernel.

iqshell vs qtile shell¶

One of the main drawbacks of running through a Jupyter kernel is the frontend has no way to query the current node of the kernel, and as such, there is no way to set a custom prompt. In order to query your current node, you can call pwd.

This, however, enables many of the benefits of running in a Jupyter frontend, including being able to save, run, and re-run code cells in frontends such as the Jupyter notebook.

The Jupyter kernel also enables more advanced help, text completion, and introspection capabilities (however, these are currently not implemented at a level much beyond what is available in the standard qtile shell).

Configuration lookup order¶

Qtile looks in the following places for a configuration file, in order:

Qtile will try to create the configuration file as a copy of the default config, if it doesn't exist yet, this one will be placed inside of $XDG_CONFIG_HOME/qtile/config.py (if set) or ~/.config/qtile/config.py.

Default Configuration¶

The default configuration is invoked when qtile cannot find a configuration file. In addition, if qtile is restarted or the config is reloaded, qtile will load the default configuration if the config file it finds has some kind of error in it. The documentation below describes the configuration lookup process, as well as what the key bindings are in the default config.

The default config is not intended to be suitable for all users; it's mostly just there so qtile does /something/ when fired up, and so that it doesn't crash and cause you to lose all your work if you reload a bad config.

Configuration variables¶

A Qtile configuration consists of a file with a bunch of variables in it, which qtile imports and then runs as a Python file to derive its final configuration. The documentation below describes the most common configuration variables; more advanced configuration can be found in the qtile-examples repository, which includes a number of real-world configurations that demonstrate how you can tune Qtile to your liking. (Feel free to issue a pull request to add your own configuration to the mix!)

Lazy objects¶

Lazy objects are a way of executing any of the commands available in Qtile's commands API.

The name "lazy" refers to the fact that the commands are not executed at the time of the call. Instead, the lazy object creates a reference to the relevant command and this is only executed when the relevant event is triggered (e.g. on a keypress).

Typically, for config files, the commands are used to manipulate windows, layouts and groups as well application commands like exiting, restarting, reloading the config file etc.

Example¶

from libqtile.config import Key
from libqtile.lazy import lazy
keys = [


    Key(


        ["mod1"], "k",


        lazy.layout.down()


    ),


    Key(


        ["mod1"], "j",


        lazy.layout.up()


    )
]

NOTE:

Lazy functions¶

This is overview of the commonly used functions for the key bindings. These functions can be called from commands on the REPLACE object or on another object in the command tree.

Some examples are given below. For a complete list of available commands, please refer to Commands API.

General functions¶

Group functions¶

Window functions¶

Screen functions¶

ScratchPad DropDown functions¶

User-defined functions¶

Examples¶

lazy.function can also be used as a decorator for functions.

from libqtile.config import Key
from libqtile.lazy import lazy
@lazy.function
def my_function(qtile):


    ...
keys = [


    Key(


        ["mod1"], "k",


        my_function


    )
]

Additionally, you can pass arguments to user-defined function in one of two ways:

Arguments can be added to the lazy.function call.

from libqtile.config import Key
from libqtile.lazy import lazy
from libqtile.log_utils import logger
def multiply(qtile, value, multiplier=10):


    logger.warning(f"Multiplication results: {value * multiplier}")
keys = [


    Key(


        ["mod1"], "k",


        lazy.function(multiply, 10, multiplier=2)


    )
]

Arguments can also be passed to the decorated function.

from libqtile.config import Key
from libqtile.lazy import lazy
from libqtile.log_utils import logger
@lazy.function
def multiply(qtile, value, multiplier=10):


    logger.warning(f"Multiplication results: {value * multiplier}")
keys = [


    Key(


        ["mod1"], "k",


        multiply(10, multiplier=2)


    )
]

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 Group objects.

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.

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 Matching¶

ScratchPad and DropDown¶

ScratchPad is a special - by default invisible - group which acts as a container for DropDown configurations. A DropDown can be configured to spawn a defined process and bind that's process' window to it. The associated window can then be shown and hidden by the lazy command 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 Match object to the corresponding DropDown. See below.

Reference¶

Keys¶

The keys variable defines Qtile's key bindings.

Default Key Bindings¶

The mod key for the default config is mod4, which is typically bound to the "Super" keys, which are things like the windows key and the mac command key. The basic operation is:

The default config defines one screen and 8 groups, one for each letter in asdfuiop. It has a basic bottom bar that includes a group box, the current window name, a little text reminder that you're using the default config, a system tray, and a clock.

The default configuration has several more advanced key combinations, but the above should be enough for basic usage of qtile.

See Keybindings in images for visual keybindings in keyboard layout.

Defining key bindings¶

Individual key bindings are defined with Key as demonstrated in the following example. Note that you may specify more than one callback functions.

from libqtile.config import Key
keys = [


   # Pressing "Meta + Shift + a".


   Key(["mod4", "shift"], "a", callback, ...),


   # Pressing "Control + p".


   Key(["control"], "p", callback, ...),


   # Pressing "Meta + Tab".


   Key(["mod4", "mod1"], "Tab", callback, ...),
]

The above may also be written more concisely with the help of the EzKey helper class. The following example is functionally equivalent to the above:

from libqtile.config import EzKey as Key
keys = [


   Key("M-S-a", callback, ...),


   Key("C-p",   callback, ...),


   Key("M-A-<Tab>", callback, ...),
]

The EzKey modifier keys (i.e. MASC) can be overwritten through the EzKey.modifier_keys dictionary. The defaults are:

modifier_keys = {


   'M': 'mod4',


   'A': 'mod1',


   'S': 'shift',


   'C': 'control',
}

Callbacks can also be configured to work only under certain conditions by using the when() method. Currently, the following conditions are supported:

from libqtile.config import Key
keys = [


    # Only trigger callback for a specific layout


    Key(


        [mod, 'shift'],


        "j",


        lazy.layout.grow().when(layout='verticaltile'),


        lazy.layout.grow_down().when(layout='columns')


    ),


    # Limit action to when the current window is not floating


    Key([mod], "f", lazy.window.toggle_fullscreen().when(when_floating=False))


    # Limit action to when the current window is floating


    Key([mod], "f", lazy.window.toggle_fullscreen().when(when_floating=True))


    # Also matches are supported on the current window


    # For example to match on the wm_class for fullscreen do the following


    Key([mod], "f", lazy.window.toggle_fullscreen().when(focused=Match(wm_class="yourclasshere"))
]

KeyChords¶

Qtile also allows sequences of keys to trigger callbacks. These sequences are known as chords and are defined with KeyChord. Chords are added to the keys section of the config file.

from libqtile.config import Key, KeyChord
keys = [


    KeyChord([mod], "z", [


        Key([], "x", lazy.spawn("xterm"))


    ])
]

The above code will launch xterm when the user presses Mod + z, followed by x.

WARNING:

Modes¶

Chords can optionally persist until a user presses <escape>. This can be done by setting mode=True. This can be useful for configuring a subset of commands for a particular situations (i.e. similar to vim modes).

from libqtile.config import Key, KeyChord
keys = [


    KeyChord([mod], "z", [


        Key([], "g", lazy.layout.grow()),


        Key([], "s", lazy.layout.shrink()),


        Key([], "n", lazy.layout.normalize()),


        Key([], "m", lazy.layout.maximize())],


        mode=True,


        name="Windows"


    )
]

In the above example, pressing Mod + z triggers the "Windows" mode. Users can then resize windows by just pressing g (to grow the window), s to shrink it etc. as many times as needed. To exit the mode, press <escape>.

NOTE:

Chains¶

Chords can also be chained to make even longer sequences.

from libqtile.config import Key, KeyChord
keys = [


    KeyChord([mod], "z", [


        KeyChord([], "x", [


            Key([], "c", lazy.spawn("xterm"))


        ])


    ])
]

Modes can also be added to chains if required. The following example demonstrates the behaviour when using the mode argument in chains:

from libqtile.config import Key, KeyChord
keys = [


    KeyChord([mod], "z", [


        KeyChord([], "y", [


            KeyChord([], "x", [


                Key([], "c", lazy.spawn("xterm"))


            ], mode=True, name="inner")


        ])


    ], mode=True, name="outer")
]

After pressing Mod+z y x c, the "inner" mode will remain active. When pressing <escape>, the "inner" mode is exited. Since the mode in between does not have mode set, it is also left. Arriving at the "outer" mode (which has this argument set) stops the "leave" action and "outer" now becomes the active mode.

NOTE:

Modifiers¶

On most systems mod1 is the Alt key - you can see which modifiers, which are enclosed in a list, map to which keys on your system by running the xmodmap command. This example binds Alt-k to the "down" command on the current layout. This command is standard on all the included layouts, and switches to the next window (where "next" is defined differently in different layouts). The matching "up" command switches to the previous window.

Modifiers include: "shift", "lock", "control", "mod1", "mod2", "mod3", "mod4", and "mod5". They can be used in combination by appending more than one modifier to the list:

Key(


    ["mod1", "control"], "k",


    lazy.layout.shuffle_down()
)

Special keys¶

These are most commonly used special keys. For complete list please see the code. You can create bindings on them just like for the regular keys. For example Key(["mod1"], "F4", lazy.window.kill()).

Reference¶

Layouts¶

A layout is an algorithm for laying out windows in a group on your screen. Since Qtile is a tiling window manager, this usually means that we try to use space as efficiently as possible, and give the user ample commands that can be bound to keys to interact with layouts.

The layouts variable defines the list of layouts you will use with Qtile. The first layout in the list is the default. If you define more than one layout, you will probably also want to define key bindings to let you switch to the next and previous layouts.

See Built-in Layouts for a listing of available layouts.

Example¶

from libqtile import layout
layouts = [


    layout.Max(),


    layout.Stack(stacks=2)
]

Mouse¶

The mouse config file variable defines a set of global mouse actions, and is a list of Click and Drag objects, which define what to do when a window is clicked or dragged.

Default Mouse Bindings¶

By default, holding your mod key and left-clicking (and holding) a window will allow you to drag it around as a floating window. Holding your mod key and right-clicking (and holding) a window will resize the window (and also make it float if it is not already floating).

Example¶

from libqtile.config import Click, Drag
mouse = [


    Drag([mod], "Button1", lazy.window.set_position_floating(),


        start=lazy.window.get_position()),


    Drag([mod], "Button3", lazy.window.set_size_floating(),


        start=lazy.window.get_size()),


    Click([mod], "Button2", lazy.window.bring_to_front())
]

The above example can also be written more concisely with the help of the EzClick and EzDrag helpers:

from libqtile.config import EzClick as Click, EzDrag as Drag
mouse = [


    Drag("M-1", lazy.window.set_position_floating(),


        start=lazy.window.get_position()),


    Drag("M-3", lazy.window.set_size_floating(),


        start=lazy.window.get_size()),


    Click("M-2", lazy.window.bring_to_front())
]

Reference¶

Screens¶

The screens configuration variable is where the physical screens, their associated bars, and the widgets contained within the bars are defined (see Built-in Widgets for a listing of available widgets).

Example¶

Tying together screens, bars and widgets, we get something like this:

from libqtile.config import Screen
from libqtile import bar, widget
window_name = widget.WindowName()
screens = [


    Screen(


        bottom=bar.Bar([


            widget.GroupBox(),


            window_name,


            ], 30),


        ),


    Screen(


        bottom=bar.Bar([


            widget.GroupBox(),


            window_name,


            ], 30),


        )


    ]

Note that a widget can be passed to multiple bars (and likewise multiple times to the same bar). Its contents is mirrored across all copies so this is useful where you want identical content (e.g. the name of the focussed window, like in this example).

Bars support both solid background colors and gradients by supplying a list of colors that make up a linear gradient. For example, bar.Bar(..., background="#000000") will give you a black back ground (the default), while bar.Bar(..., background=["#000000", "#FFFFFF"]) will give you a background that fades from black to white.

Bars (and widgets) also support transparency by adding an alpha value to the desired color. For example, bar.Bar(..., background="#00000000") will result in a fully transparent bar. Widget contents will not be impacted i.e. this is different to the opacity parameter which sets the transparency of the entire window.

NOTE:

Users can add borders to the bar by using the border_width and border_color parameters. Providing a single value sets the value for all four sides while sides can be customised individually by setting four values in a list (top, right, bottom, left) e.g. border_width=[2, 0, 2, 0] would draw a border 2 pixels thick on the top and bottom of the bar.

Multiple Screens¶

You will see from the example above that screens is a list of individual Screen objects. The order of the screens in this list should match the order of screens as seen by your display server.

X11¶

You can view the current order of your screens by running xrandr --listmonitors.

Examples of how to set the order of your screens can be found on the Arch wiki.

Wayland¶

The Wayland backend supports the wlr-output-management protocol for configuration of outputs by tools such as Kanshi.

Fake Screens¶

instead of using the variable screens the variable fake_screens can be used to set split a physical monitor into multiple screens. They can be used like this:

from libqtile.config import Screen
from libqtile import bar, widget
# screens look like this
#     600         300
#  |-------------|-----|
#  |          480|     |580
#  |   A         |  B  |
#  |----------|--|     |
#  |       400|--|-----|
#  |   C      |        |400
#  |----------|   D    |
#     500     |--------|
#                 400
#
# Notice there is a hole in the middle
# also D goes down below the others
fake_screens = [


  Screen(


      bottom=bar.Bar(


          [


              widget.Prompt(),


              widget.Sep(),


              widget.WindowName(),


              widget.Sep(),


              widget.Systray(),


              widget.Sep(),


              widget.Clock(format='%H:%M:%S %d.%m.%Y')


          ],


          24,


          background="#555555"


      ),


      x=0,


      y=0,


      width=600,


      height=480


  ),


  Screen(


      top=bar.Bar(


          [


              widget.GroupBox(),


              widget.WindowName(),


              widget.Clock()


          ],


          30,


      ),


      x=600,


      y=0,


      width=300,


      height=580


  ),


  Screen(


      top=bar.Bar(


          [


              widget.GroupBox(),


              widget.WindowName(),


              widget.Clock()


          ],


          30,


      ),


      x=0,


      y=480,


      width=500,


      height=400


  ),


  Screen(


      top=bar.Bar(


          [


              widget.GroupBox(),


              widget.WindowName(),


              widget.Clock()


          ],


          30,


      ),


      x=500,


      y=580,


      width=400,


      height=400


  ),
]

Third-party bars¶

There might be some reasons to use third-party bars. For instance you can come from another window manager and you have already configured dzen2, xmobar, or something else. They definitely can be used with Qtile too. In fact, any additional configurations aren't needed. Just run the bar and qtile will adapt.

Reference¶

Hooks¶

Qtile provides a mechanism for subscribing to certain events in libqtile.hook. To subscribe to a hook in your configuration, simply decorate a function with the hook you wish to subscribe to.

See Built-in Hooks for a listing of available hooks.

Examples¶

Automatic floating dialogs¶

Let's say we wanted to automatically float all dialog windows (this code is not actually necessary; Qtile floats all dialogs by default). We would subscribe to the client_new hook to tell us when a new window has opened and, if the type is "dialog", as can set the window to float. In our configuration file it would look something like this:

from libqtile import hook
@hook.subscribe.client_new
def floating_dialogs(window):


    dialog = window.window.get_wm_type() == 'dialog'


    transient = window.window.get_wm_transient_for()


    if dialog or transient:


        window.floating = True

A list of available hooks can be found in the Built-in Hooks reference.

Autostart¶

If you want to run commands or spawn some applications when Qtile starts, you'll want to look at the startup and startup_once hooks. startup is emitted every time Qtile starts (including restarts), whereas startup_once is only emitted on the very first startup.

Let's create an executable file ~/.config/qtile/autostart.sh that will start a few programs when Qtile first runs. Remember to chmod +x ~/.config/qtile/autostart.sh so that it can be executed.

#!/bin/sh
pidgin &
dropbox start &

We can then subscribe to startup_once to run this script:

import os
import subprocess
from libqtile import hook
@hook.subscribe.startup_once
def autostart():


    home = os.path.expanduser('~/.config/qtile/autostart.sh')


    subprocess.call(home)

Accessing the qtile object¶

If you want to do something with the Qtile manager instance inside a hook, it can be imported into your config:

from libqtile import qtile

Async hooks¶

Hooks can also be defined as coroutine functions using async def, which will run them asynchronously in the event loop:

@hook.subscribe.focus_change
async def _():


    ...

Matching windows¶

Qtile's config provides a number of situations where the behaviour depends on whether the relevant window matches some specified criteria.

These situations include:

In each instance, the criteria are defined via a Match object. The properties of the object will be compared to a 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 Window to be compared against and returns a boolean.

A basic rule would therefore look something like:

Match(wm_class="mpv")

This would match against any window whose class was mpv.

Where a string is provided as an argument then the value must match exactly. More flexibility can be achieved by using regular expressions. For example:

import re
Match(wm_class=re.compile(r"mpv"))

This would still match a window whose class was mpv but it would also match any class starting with mpv e.g. mpvideo.

NOTE:

import re
Match(wm_class=re.compile(r".*mpv"))

Creating advanced rules¶

While the func parameter allows users to create more complex matches, this requires a knowledge of qtile's internal objects. An alternative is to combine Match objects using logical operators & (and), | (or), ~ (not) and ^ (xor).

For example, to create rule that matches all windows with a fixed aspect ratio except for mpv windows, you would provide the following:

Match(func=lambda c: c.has_fixed_ratio()) & ~Match(wm_class="mpv")

It is also possible to use wrappers for Match objects if you do not want to use the operators. The following wrappers are available:

So, to recreate the above rule using the wrappers, you would write the following:

from libqtile.config import InvertMatch, Match, MatchAll
MatchAll(Match(func=lambda c: c.has_fixed_ratio()), InvertMatch(Match(wm_class="mpv")))

In addition to the above variables, there are several other boolean configuration variables that control specific aspects of Qtile's behavior:

Testing your configuration¶

The best way to test changes to your configuration is with the provided scripts at ./scripts/xephyr (X11) or ./scripts/wephyr (Wayland). This will run Qtile with your config.py inside a nested window and prevent your running instance of Qtile from crashing if something goes wrong.

See Hacking Qtile for more information on using Xephyr.

Default configuration¶

[image] [image] [image]

Generate your own images¶

Qtile provides a tiny helper script to generate keybindings images from a config file. In the repository, the script is located under scripts/gen-keybinding-img.

This script accepts a configuration file and an output directory. If no argument is given, the default configuration will be used and files will be placed in same directory where the command has been run.

usage: gen-keybinding-img [-h] [-c CONFIGFILE] [-o OUTPUT_DIR]
Qtile keybindings image generator
optional arguments:


    -h, --help          show this help message and exit


    -c CONFIGFILE, --config CONFIGFILE


                        use specified configuration file. If no presented


                        default will be used


    -o OUTPUT_DIR, --output-dir OUTPUT_DIR


                        set directory to export all images to

Layer priority groups¶

We have tried to adhere to the EWMH specification. Windows are therefore stacked, from the bottom, according to the following priority rules:

Qtile had then added an additional layer so that Scratchpad windows are placed above everything else.

Tiled windows will open in the default, "windows not belonging in any other layer", layer. If floats_kept_above is set to True in the config then new floating windows will have the _NET_WM_STATE_ABOVE property set which will ensure they remain above tiled windows.

Moving windows¶

Imagine you have four tiled windows stacked (from the top) as follows:

"One"
"Two"
"Three"
"Four"

If you call move_up() on window "Four", the result will be:

"One"
"Two"
"Four"
"Three"

If you now call move_to_top() on window "Three", the result will be:

"Three"
"One"
"Two"
"Four"

NOTE:

The Command Graph¶

The objects in Qtile's command graph come in eight flavours, matching the eight basic components of the window manager: layouts, windows, groups, bars, widgets, screens, core, and a special root node. Objects are addressed by a path specification that starts at the root and follows the available paths in the graph. This is what the graph looks like:

Each arrow can be read as "holds a reference to". So, we can see that a widget object holds a reference to objects of type bar, screen and group. Let's start with some simple examples of how the addressing works. Which particular objects we hold reference to depends on the context - for instance, widgets hold a reference to the screen that they appear on, and the bar they are attached to.

Let's look at an example, starting at the root node. The following script runs the status command on the root node, which, in this case, is represented by the InteractiveCommandClient object:

from libqtile.command.client import InteractiveCommandClient
c = InteractiveCommandClient()
print(c.status())

The InteractiveCommandClient is a class that allows us to traverse the command graph using attributes to select child nodes or commands. In this example, we have resolved the status() command on the root object. The interactive command client will automatically find and connect to a running Qtile instance, and which it will use to dispatch the call and print out the return.

An alternative is to use the CommandClient, which allows for a more precise resolution of command graph objects, but is not as easy to interact with from a REPL:

from libqtile.command.client import CommandClient
c = CommandClient()
print(c.call("status")())

Like the interactive client, the command client will automatically connect to a running Qtile instance. Here, we first resolve the status() command with the .call("status"), which simply located the function, then we can invoke the call with no arguments.

For the rest of this example, we will use the interactive command client. From the graph, we can see that the root node holds a reference to group nodes. We can access the "info" command on the current group like so:

c.group.info()

To access a specific group, regardless of whether or not it is current, we use the Python mapping lookup syntax. This command sends group "b" to screen 1 (by the libqtile.config.Group.toscreen() method):

c.group["b"].toscreen(1)

In different contexts, it is possible to access a default object, where in other contexts a key is required. From the root of the graph, the current group, layout, screen and window can be accessed by simply leaving the key specifier out. The key specifier is mandatory for widget and bar nodes.

With this context, we can now drill down deeper in the graph, following the edges in the graphic above. To access the screen currently displaying group "b", we can do this:

c.group["b"].screen.info()

Be aware, however, that group "b" might not currently be displayed. In that case, it has no associated screen, the path resolves to a non-existent node, and we get an exception:

libqtile.command.CommandError: No object screen in path 'group['b'].screen'

The graph is not a tree, since it can contain cycles. This path (redundantly) specifies the group belonging to the screen that belongs to group "b":

c.group["b"].screen.group

This amount of connectivity makes it easy to reach out from a given object when callbacks and events fire on that object to related objects.

Navigating the command graph¶

As noted previously, some objects require a selector to ensure that the correct object is selected, while other nodes provide a default object without a selector.

The table below shows what selectors are required for the different nodes and whether the selector is optional (i.e. if it can be omitted to select the default object).

Command graph development¶

This page provides further detail on how Qtile's command graph works. If you just want to script your Qtile window manager the earlier information, in addition to the documentation on the available commands should be enough to get started.

To develop the Qtile manager itself, we can dig into how Qtile represents these objects, which will lead to the way the commands are dispatched.

Client-Server Scripting Model¶

Qtile has a client-server control model - the main Qtile instance listens on a named pipe, over which marshalled command calls and response data is passed. This allows Qtile to be controlled fully from external scripts. Remote interaction occurs through an instance of the libqtile.command.interface.IPCCommandInterface class. This class establishes a connection to the currently running instance of Qtile. A libqtile.command.client.InteractiveCommandClient can use this connection to dispatch commands to the running instance. Commands then appear as methods with the appropriate signature on the InteractiveCommandClient object. The object hierarchy is described in the Architecture section of this manual. Full command documentation is available through the Qtile Shell.

Digging Deeper: Command Objects¶

All of the configured objects setup by Qtile are CommandObject subclasses. These objects are so named because we can issue commands against them using the command scripting API. Looking through the code, the commands that are exposed are commands that are decorated with the @expose_command() decorator. When writing custom layouts, widgets, or any other object, you can add your own custom functions and, once you add the decorator, they will be callable using the standard command infrastructure. An available command can be extracted by calling .command() with the name of the command.

In addition to having a set of associated commands, each command object also has a collection of items associated with it. This is what forms the graph that is shown above. For a given object type, the items() method returns all of the names of the associated objects of that type and whether or not there is a defaultable value. For example, from the root, .items("group") returns the name of all of the groups and that there is a default value, the currently focused group.

To navigate from one command object to the next, the .select() method is used. This method resolves a requested object from the command graph by iteratively selecting objects. A selector like [("group", "b"), ("screen", None)] would be to first resolve group "b", then the screen associated to the group.

The Command Graph¶

In order to help in specifying command objects, there is the abstract command graph structure. The command graph structure allows us to address any valid command object and issue any command against it without needing to have any Qtile instance running or have anything to resolve the objects to. This is particularly useful when constructing lazy calls, where the Qtile instance does not exist to specify the path that will be resolved when the command is executed. The only limitation of traversing the command graph is that it must follow the allowed edges specified in the first section above.

Every object in the command graph is represented by a CommandGraphNode. Any call can be resolved from a given node. In addition, each node knows about all of the children objects that can be reached from it and have the ability to .navigate() to the other nodes in the command graph. Each of the object types are represented as CommandGraphObject types and the root node of the graph, the CommandGraphRoot represents the Qtile instance. When a call is performed on an object, it returns a CommandGraphCall. Each call will know its own name as well as be able to resolve the path through the command graph to be able to find itself.

Note that the command graph itself can standalone, there is no other functionality within Qtile that it relies on. While we could have started here and built up, it is helpful to understand the objects that the graph is meant to represent, as the graph is just a representation of a traversal of the real objects in a running Qtile window manager. In order to tie the running Qtile instance to the abstract command graph, we move on to the command interface.

Executing graph commands: Command Interface¶

The CommandInterface is what lets us take an abstract call on the command graph and resolve it against a running command object. Put another way, this is what takes the graph traversal .group["b"].screen.info() and executes the info() command against the addressed screen object. Additional functionality can be used to check that a given traversal resolves to actual objcets and that the requested command actually exists. Note that by construction of the command graph, the traversals here must be feasible, even if they cannot be resolved for a given configuration state. For example, it is possible to check the screen assoctiated to a group, even though the group may not be on a screen, but it is not possible to check the widget associated to a group.

The simplest form of the command interface is the QtileCommandInterface, which can take an in-process Qtile instance as the root CommandObject and execute requested commands. This is typically how we run the unit tests for Qtile.

The other primary example of this is the IPCCommandInterface which is able to then route all calls through an IPC client connected to a running Qtile instance. In this case, the command graph call can be constructed on the client side without having to dispatch to Qtile and once the call is constructed and deemed valid, the call can be executed.

In both of these cases, executing a command on a command interface will return the result of executing the command on a running Qtile instance. To support lazy execution, the LazyCommandInterface instead returns a LazyCall which is able to be resolved later by the running Qtile instance when it is configured to fire.

Tying it together: Command Client¶

So far, we have our running Command Objects and the Command Interface to dispatch commands against these objects as well as the Command Graph structure itself which encodes how to traverse the connections between the objects. The final component which ties everything together is the Command Client, which allows us to navigate through the graph to resolve objects, find their associated commands, and execute the commands against the held command interface.

The idea of the command client is that it is created with a reference into the command graph and a command interface. All navigation can be done against the command graph, and traversal is done by creating a new command client starting from the new node. When a command is executed against a node, that command is dispatched to the held command interface. The key decision here is how to perform the traversal. The command client exists in two different flavors: the standard CommandClient which is useful for handling more programmatic traversal of the graph, calling methods to traverse the graph, and the InteractiveCommandClient which behaves more like a standard Python object, traversing by accessing properties and performing key lookups.

Returning to our examples above, we now have the full context to see what is going on when we call:

from libqtile.command.client import CommandClient
c = CommandClient()
print(c.call("status")())
from libqtile.command.client import InteractiveCommandClient
c = InteractiveCommandClient()
print(c.status())

In both cases, the command clients are constructed with the default command interface, which sets up an IPC connection to the running Qtile instance, and starts the client at the graph root. When we call c.call("status") or c.status, we navigate the command client to the status command on the root graph object. When these are invoked, the commands graph calls are dispatched via the IPC command interface and the results then sent back and printed on the local command line.

The power that can be realized by separating out the traversal and resolution of objects in the command graph from actually invoking or looking up any objects within the graph can be seen in the lazy module. By creating a lazy evaluated command client, we can expose the graph traversal and object resolution functionality via the same InteractiveCommandClient that is used to perform live command execution in the Qtile prompt.

Introduction¶

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

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:
lazy.widget["volume"].increase_volume()
qtile shell:
> cd widget/volume
widget[volume] > increase_volume()
qtile cmd-obj:
qtile cmd-obj -o widget volume -f increase_volume
CommandClient:
>>> from libqtile.command.client import CommandClient
>>> c = CommandClient()
>>> c.navigate("widget", "volume").call("increase_volume")
InteractiveCommandClient:
>>> 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¶

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:

lazy.node[selector].command(arguments)

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:

lazy.screen[1].group.next_window()

NOTE:

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

CommandClient¶

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.

InteractiveCommandClient¶

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"].screen.info()

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

Layout objects¶

Layouts position windows according to their specific rules. Layout commands typically include moving windows around the layout and changing the size of windows.

Layouts can access the windows being displayed, the group holding the layout and the screen displaying the layout.

Window objects¶

The size and position of windows is determined by the current layout. Nevertheless, windows can still change their appearance in multiple ways (toggling floating state, fullscreen, opacity).

Windows can access objects relevant to the display of the window (i.e. the screen, group and layout).

Group objects¶

Groups are Qtile's workspaces. Groups are not responsible for the positioning of windows (that is handled by the layouts) so the available commands are somewhat more limited in scope.

Groups have access to the layouts in that group, the windows in the group and the screen displaying the group.

Bar objects¶

The bar is primarily used to display widgets on the screen. As a result, the bar does not need many of its own commands.

To select a bar on the command graph, you must use a selector (as there is no default bar). The selector is the position of the bar on the screen i.e. "top", "bottom", "left" or "right".

The bar can access the screen it's on and the widgets it contains via the command graph.

Widget objects¶

Widgets are small scripts that are used to provide content or add functionality to the bar. Some widgets will expose commands in order for functionality to be triggered indirectly (e.g. via a keypress).

Widgets can access the parent bar and screen via the command graph.

Screen objects¶

Screens are the display area that holds bars and an active group. Screen commands include changing the current group and changing the wallpaper.

Screens can access objects displayed on that screen e.g. bar, widgets, groups, layouts and windows.

Backend core objects¶

The backend core is the link between the Qtile objects (windows, layouts, groups etc.) and the specific backend (X11 or Wayland). This core should be largely invisible to users and, as a result, these objects do not expose many commands.

Nevertheless, both backends do contain important commands, notably set_keymap on X11 and change_vt used to change to a different TTY on Wayland.

The backend core has no access to other nodes on the command graph.

X11 backend¶

Wayland backend¶

Requirements¶

Here are Qtile's additional dependencies that may be required for tests:

Backends¶

The test suite can be run using the X11 or Wayland backend, or both. By default, only the X11 backend is used for tests. To test a single backend or both backends, specify as arguments to pytest:

pytest --backend wayland  # Test just Wayland backend
pytest --backend x11 --backend wayland  # Test both

Testing with the X11 backend requires Xephyr (and xvfb for headless mode) in addition to the core dependencies.

Building cffi module¶

Qtile ships with a small in-tree pangocairo binding built using cffi, pangocffi.py, and also binds to xcursor with cffi. The bindings are not built at run time and will have to be generated manually when the code is downloaded or when any changes are made to the cffi library. This can be done by calling:

./scripts/ffibuild

Setting up the environment¶

In the root of the project, run ./dev.sh. It will create a virtualenv called venv.

Activate this virtualenv with . venv/bin/activate. Deactivate it with the deactivate command.

Building the documentation¶

To build the documentation, you will also need to install graphviz.

Go into the docs/ directory and run pip install -r requirements.txt.

Build the documentation with make html.

Check the result by opening _build/html/index.html in your browser.

NOTE:

Development and testing¶

In practice, the development cycle looks something like this:

Tests and pre-commit hooks will be run by our CI on every pull request as well so you can see whether or not your contribution passes.

Coding style¶

While not all of our code follows PEP8, we do try to adhere to it where possible. All new code should be PEP8 compliant.

The make lint command (or pre-commit run -a) will run our linters and formatters with our configuration over the whole libqtile to ensure your patch complies with reasonable formatting constraints. We also request that git commit messages follow the standard format.

Logging¶

Logs are important to us because they are our best way to see what Qtile is doing when something abnormal happens. However, our goal is not to have as many logs as possible, as this hinders readability. What we want are relevant logs.

To decide which log level to use, refer to the following scenarios:

Be careful not to overuse DEBUG and clutter the logs. No information should be duplicated between two messages.

Also, keep in mind that any other level than DEBUG is aimed at users who don't necessarily have advanced programming knowledge; adapt your message accordingly. If it can't make sense to your grandma, it's probably meant to be a DEBUG message.

Using Xephyr¶

Qtile has a very extensive test suite, using the Xephyr nested X server. When tests are run, a nested X server with a nested instance of Qtile is fired up, and then tests interact with the Qtile instance through the client API. The fact that we can do this is a great demonstration of just how completely scriptable Qtile is. In fact, Qtile is designed expressly to be scriptable enough to allow unit testing in a nested environment.

The Qtile repo includes a tiny helper script to let you quickly pull up a nested instance of Qtile in Xephyr, using your current configuration. Run it from the top-level of the repository, like this:

./scripts/xephyr

Change the screen size by setting the SCREEN_SIZE environment variable. Default: 800x600. Example:

SCREEN_SIZE=1920x1080 ./scripts/xephyr

Change the log level by setting the LOG_LEVEL environment variable. Default: INFO. Example:

LOG_LEVEL=DEBUG ./scripts/xephyr

The script will also pass any additional options to Qtile. For example, you can use a specific configuration file like this:

./scripts/xephyr -c ~/.config/qtile/other_config.py

Once the Xephyr window is running and focused, you can enable capturing the keyboard shortcuts by hitting Control+Shift. Hitting them again will disable the capture and let you use your personal keyboard shortcuts again.

You can close the Xephyr window by enabling the capture of keyboard shortcuts and hit Mod4+Control+Q. Mod4 (or Mod) is usually the Super key (or Windows key). You can also close the Xephyr window by running qtile cmd-obj -o cmd -f shutdown in a terminal (from inside the Xephyr window of course).

You don't need to run the Xephyr script in order to run the tests as the test runner will launch its own Xephyr instances.

Second X Session¶

Some users prefer to test Qtile in a second, completely separate X session: Just switch to a new tty and run startx normally to use the ~/.xinitrc X startup script.

It's likely though that you want to use a different, customized startup script for testing purposes, for example ~/.config/qtile/xinitrc. You can do so by launching X with:

startx ~/.config/qtile/xinitrc

startx deals with multiple X sessions automatically. If you want to use xinit instead, you need to first copy /etc/X11/xinit/xserverrc to ~/.xserverrc; when launching it, you have to specify a new session number:

xinit ~/.config/qtile/xinitrc -- :1

Examples of custom X startup scripts are available in qtile-examples.

Debugging in PyCharm¶

Make sure to have all the requirements installed and your development environment setup.

PyCharm should automatically detect the venv virtualenv when opening the project. If you are using another viirtualenv, just instruct PyCharm to use it in Settings -> Project: qtile -> Project interpreter.

In the project tree, on the left, right-click on the libqtile folder, and click on Mark Directory as -> Sources Root.

Next, add a Configuration using a Python template with these fields:

Then, in a terminal, run:

Note that we used the same display, :1, in both the terminal command and the PyCharm configuration environment variables. Feel free to change the screen size to fit your own screen.

Finally, place your breakpoints in the code and click on Debug!

Once you finished debugging, you can close the Xephyr window with kill PID (use the jobs builtin to get its PID).

Debugging in VSCode¶

Make sure to have all the requirements installed and your development environment setup.

Open the root of the repo in VSCode. If you have created it, VSCode should detect the venv virtualenv, if not, select it.

Create a launch.json file with the following lines.

{


  "version": "0.2.0",


  "configurations": [


      {


          "name": "Python: Qtile",


          "type": "python",


          "request": "launch",


          "program": "${workspaceFolder}/bin/qtile",


          "cwd": "${workspaceFolder}",


          "args": ["-c", "libqtile/resources/default_config.py"],


          "console": "integratedTerminal",


          "env": {"PYTHONUNBUFFERED":"1", "DISPLAY":":1"}


      }


  ]
}

Then, in a terminal, run:

Note that we used the same display, :1, in both the terminal command and the VSCode configuration environment variables. Then debug usually in VSCode. Feel free to change the screen size to fit your own screen.

Resources¶

Here are a number of resources that may come in handy:

Reporting bugs¶

Perhaps the easiest way to contribute to Qtile is to report any bugs you run into on the GitHub issue tracker.

Useful bug reports are ones that get bugs fixed. A useful bug report normally has two qualities:

Ensure to include any appropriate log entries from ~/.local/share/qtile/qtile.log and/or ~/.xsession-errors! Sometimes, an xtrace is requested. If that is the case, refer to capturing an xtrace.

Writing code¶

To get started writing code for Qtile, check out our guide to Hacking on Qtile. A more detailed page on creating widgets is available here.

IMPORTANT:

Submit a pull request¶

You've done your hacking and are ready to submit your patch to Qtile. Great! Now it's time to submit a pull request to our issue tracker on GitHub.

IMPORTANT:

NOTE:

Feel free to add your contribution (no matter how small) to the appropriate place in the CHANGELOG as well!

Unit testing¶

We must test each unit of code to ensure that new changes to the code do not break existing functionality. The framework we use to test Qtile is pytest. How pytest works is outside of the scope of this documentation, but there are tutorials online that explain how it is used.

Our tests are written inside the test folder at the top level of the repository. Reading through these, you can get a feel for the approach we take to test a given unit. Most of the tests involve an object called manager. This is the test manager (defined in test/helpers.py), which exposes a command client at manager.c that we use to test a Qtile instance running in a separate thread as if we were using a command client from within a running Qtile session.

For any Qtile-specific question on testing, feel free to ask on our issue tracker or on IRC (#qtile on irc.oftc.net).

Running tests locally¶

This section gives an overview about tox so that you don't have to search its documentation just to get started.

Checks are grouped in so-called environments. Some of them are configured to check that the code works (the usual unit test, e.g. py39, pypy3), others make sure that your code conforms to the style guide (pep8, codestyle, mypy). A third kind of test verifies that the documentation and packaging processes work (docs, docstyle, packaging).

We have configured tox to run the full suite of tests whenever a pull request is submitted/updated. To reduce the amount of time taken by these tests, we have created separate environments for both python versions and backends (e.g. tests for x11 and wayland run in parallel for each python version that we currently support).

These environments were designed with automation in mind so there are separate test environments which should be used for running qtile's tests locally. By default, tests will only run on x11 backend (but see below for information on how to set the backend).

tox -e test # Run all tests in default python version
tox -e test -- -x test/widgets/test_widgetbox.py  # run a single file
tox -e test -- -x test/widgets/test_widgetbox.py::test_widgetbox_widget
tox -e test -- --backend=wayland --backend=x11  # run tests on both backends
tox -e test-both  # same as above
tox -e test-wayland  # Just run tests on wayland backend

Writing migrations¶

Migrations are needed when a commit introduces a change which makes a breaking change to a user's config. Examples include renaming classes, methods, arguments and moving modules or class definitions.

Where these changes are made, it is strongly encouraged to support the old syntax where possible and warn the user about the deprecations.

Whether or not a deprecation warning is provided, a migration script should be provided that will modify the user's config when they run qtile migrate.

Click here for detailed instructions on How to write a migration script.

How to write a migration script¶

Qtile's migration scripts should provide two functions:

To do this, we use LibCST to parse the config file and make changes as appropriate. Basic tips for using LibCST are included below but it is recommended that you read their documentation to familiarise yourself with the available functionalities.

Structure of a migration file¶

Migrations should be saved as a new file in libqtile/scripts/migrations.

A basic migration will look like this:

from libqtile.scripts.migrations._base import MigrationTransformer, _QtileMigrator, add_migration
class MyMigration(MigrationTransformer):


    """The class that actually modifies the code."""


    ...
class Migrator(_QtileMigrator):


    ID = "MyMigrationName"


    SUMMARY = "Summary of migration."


    HELP = """


    Longer text explaining purpose of the migration and, ideally,


    giving code examples.


    """


    AFTER_VERSION = "0.22.1"


    TESTS = []


    visitor = MyMigration
add_migration(Migrator)

Providing details about the migration¶

The purpose of Migrator class in the code above is to provide the information about the migration.

It is important that the information is as helpful as possible as it is used in multiple places.

How migrations are run¶

You are pretty much free to transform the code as you see fit. By default, the script will run the visit method on the parsed code and will pass the visitor attribute of the _QtileMigrator class object. Therefore, if all your transformations can be performed in a single visitor, it is not necessary to do anything further in the Migrator class.

However, if you want to run multiple visitors, transformers, codemods, this is possible by overriding the run method of the _QtileMigrator class. For example, the RemoveCmdPrefix migrator has the following code:

def run(self, original):


    # Run the base migrations


    transformer = CmdPrefixTransformer()


    updated = original.visit(transformer)


    self.update_lint(transformer)


    # Check if we need to add an import line


    if transformer.needs_import:


        # We use the built-in visitor to add the import


        context = codemod.CodemodContext()


        AddImportsVisitor.add_needed_import(


            context, "libqtile.command.base", "expose_command"


        )


        visitor = AddImportsVisitor(context)


        # Run the visitor over the updated code


        updated = updated.visit(visitor)


    return original, updated

In this migration, it may be required to add an import statement. LibCST has a built-in transformation for doing this so we can run that after our own transformation has been performed.

IMPORTANT:

Transforming the code¶

It is recommended that you use a transformed to update the code. For convenience, a MigrationTransformer class is defined in libqtile.scripts.migrations._base. This class definition includes some metadata information and a lint method for outputting details of errors.

Let's look at an example transformer to understand how the migration works. The code below shows how to change a positional argument to a keyword argument in the WidgetBox widget.

class WidgetboxArgsTransformer(MigrationTransformer):


    @m.call_if_inside(


        m.Call(func=m.Name("WidgetBox")) | m.Call(func=m.Attribute(attr=m.Name("WidgetBox")))


    )


    @m.leave(m.Arg(keyword=None))


    def update_widgetbox_args(self, original_node, updated_node) -> cst.Arg:


        """Changes positional  argumentto 'widgets' kwargs."""


        self.lint(


            original_node,


            "The positional argument should be replaced with a keyword argument named 'widgets'.",


        )


        return updated_node.with_changes(keyword=cst.Name("widgets"), equal=EQUALS_NO_SPACE)

Our class (which inherits from MigrationTransformer) defines a single method to perform the transformation. We take advantage of LibCST and its Matchers to narrow the scope of when the transformation is run.

We are looking to modify an argument so we use the @m.leave(m.Arg()) decorator to call the function at end of parsing an argument. We can restrict when this is called by specify m.Arg(keyword=None) so that it is only called for positional arguments. Furthermore, as we only want this called for WidgetBox instantiation lines, we add an additional decorator @m.call_if_inside(m.Call()). This ensures the method is only called when we're in a call. On its own, that's not helpful as args would almost always be part of a call. However, we can say we only want to match calls to WidgetBox. The reason for the long syntax above is that LibCST parses WidgetBox() and widget.WidgetBox() differently. In the first one, WidgetBox is in the func property of the call. However, in the second, the func is an Attribute as it is a dotted name and so we need to check the attr property.

The decorated method takes two arguments, original_mode and updated_node (note: The original_node should not be modified). The method should also confirm the return type.

The above method provides a linting message by calling self.lint and passing the original node and a helpful message.

Finally, the method updates the code by calling updated_node.with_changes(). In this instance, we add a keyword ("widgets") to the argument. We also remove spaces around the equals sign as these are added by default by LibCST. The updated node is returned.

Helper classes¶

Helper classes are provided for common transformations.

class RenameHookTransformer(RenamerTransformer):


    from_to = ("window_name_change", "client_name_updated")

Testing the migration¶

All migrations must be tested, ideally with a number of scenarios to confirm that the migration works as expected.

Unlike other tests, the tests for the migrations are defined within the TESTS attribute.

This is a list that should take a Check, Change or NoChange object (all are imported from libqtile.scripts.migrations._base).

A Change object needs two parameters, the input code and the expected output. A NoChange object just defines the input (as the output should be the same).

A Check object is identical to Change however, when running the test suite, the migrated code will be verified with qtile check. The code will therefore need to include all relevant imports etc.

Based on the above, the following is recommended as best practice:

For example, the RemoveCmdPrefix migration has the following TESTS:

TESTS = [


    Change("""qtile.cmd_spawn("alacritty")""", """qtile.spawn("alacritty")"""),


    Change("""qtile.cmd_groups()""", """qtile.get_groups()"""),


    Change("""qtile.cmd_screens()""", """qtile.get_screens()"""),


    Change("""qtile.current_window.cmd_hints()""", """qtile.current_window.get_hints()"""),


    Change(


        """qtile.current_window.cmd_opacity(0.5)""",


        """qtile.current_window.set_opacity(0.5)""",


    ),


    Change(


        """


        class MyWidget(widget.Clock):


            def cmd_my_command(self):


                pass


        """,


        """


        from libqtile.command.base import expose_command


        class MyWidget(widget.Clock):


            @expose_command


            def my_command(self):


                pass


        """


    ),


    NoChange(


        """


        def cmd_some_other_func():


            pass


        """


    ),


    Check(


        """


        from libqtile import qtile, widget


        class MyClock(widget.Clock):


            def cmd_my_exposed_command(self):


                pass


        def my_func(qtile):


            qtile.cmd_spawn("rickroll")


            hints = qtile.current_window.cmd_hints()


            groups = qtile.cmd_groups()


            screens = qtile.cmd_screens()


            qtile.current_window.cmd_opacity(0.5)


        def cmd_some_other_func():


            pass


        """,


        """


        from libqtile import qtile, widget


        from libqtile.command.base import expose_command


        class MyClock(widget.Clock):


            @expose_command


            def my_exposed_command(self):


                pass


        def my_func(qtile):


            qtile.spawn("rickroll")


            hints = qtile.current_window.get_hints()


            groups = qtile.get_groups()


            screens = qtile.get_screens()


            qtile.current_window.set_opacity(0.5)


        def cmd_some_other_func():


            pass


        """


    )
]

The tests check:

NOTE:

You can check your tests by running pytest -k <YourMigrationID>. Note, mpypy must be installed for the Check tests to be run.

Deprecation Policy¶

Interfaces that have been deprecated for at least two years after the first release containing the deprecation notice can be deleted. Since all new breaking changes should have a migration, users can use qtile migrate to bootstrap across versions when migrations are deleted if necessary.

Deprecated interfaces that do not have a migration (i.e. whose deprecation was noted before the migration feature was introduced) are all fair game to be deleted, since the migration feature is more than two years old.

Why the name Qtile?¶

Users often wonder, why the Q? Does it have something to do with Qt? No. Below is an IRC excerpt where cortesi explains the great trial that ultimately brought Qtile into existence, thanks to the benevolence of the Open Source Gods. Praise be to the OSG!

ramnes:  what does Qtile mean?
ramnes:  what's the Q?
@tych0:  ramnes: it doesn't :)
@tych0:  cortesi was just looking for the first letter that wasn't registered


         in a domain name with "tile" as a suffix
@tych0:  qtile it was :)
cortesi: tych0, dx: we really should have something more compelling to


         explain the name. one day i was swimming at manly beach in sydney,


         where i lived at the time. suddenly, i saw an enormous great white


         right beside me. it went for my leg with massive, gaping jaws, but


         quick as a flash, i thumb-punched it in both eyes. when it reared


         back in agony, i saw that it had a jagged, gnarly scar on its


         stomach... a scar shaped like the letter "Q".
cortesi: while it was distracted, i surfed a wave to shore. i knew that i


         had to dedicate my next open source project to the ocean gods, in


         thanks for my lucky escape. and thus, qtile got its name...

When I first start xterm/urxvt/rxvt containing an instance of Vim, I see text and layout corruption. What gives?¶

Vim is not handling terminal resizes correctly. You can fix the problem by starting your xterm with the "-wf" option, like so:

xterm -wf -e vim

Alternatively, you can just cycle through your layouts a few times, which usually seems to fix it.

How do I know which modifier specification maps to which key?¶

To see a list of modifier names and their matching keys, use the xmodmap command. On my system, the output looks like this:

$ xmodmap
xmodmap:  up to 3 keys per modifier, (keycodes in parentheses):
shift       Shift_L (0x32),  Shift_R (0x3e)
lock        Caps_Lock (0x9)
control     Control_L (0x25),  Control_R (0x69)
mod1        Alt_L (0x40),  Alt_R (0x6c),  Meta_L (0xcd)
mod2        Num_Lock (0x4d)
mod3
mod4        Super_L (0xce),  Hyper_L (0xcf)
mod5        ISO_Level3_Shift (0x5c),  Mode_switch (0xcb)

My "pointer mouse cursor" isn't the one I expect it to be!¶

Qtile should set the default cursor to left_ptr, you must install xcb-util-cursor if you want support for themed cursors.

LibreOffice menus don't appear or don't stay visible¶

A workaround for problem with the mouse in libreoffice is setting the environment variable »SAL_USE_VCLPLUGIN=gen«. It is dependent on your system configuration as to where to do this. e.g. ArchLinux with libreoffice-fresh in /etc/profile.d/libreoffice-fresh.sh.

How can I get my groups to stick to screens?¶

This behaviour can be replicated by configuring your keybindings to not move groups between screens. For example if you want groups "1", "2" and "3" on one screen and "q", "w", and "e" on the other, instead of binding keys to lazy.group[name].toscreen(), use this:

groups = [


    # Screen affinity here is used to make


    # sure the groups startup on the right screens


    Group(name="1", screen_affinity=0),


    Group(name="2", screen_affinity=0),


    Group(name="3", screen_affinity=0),


    Group(name="q", screen_affinity=1),


    Group(name="w", screen_affinity=1),


    Group(name="e", screen_affinity=1),
]
def go_to_group(name: str):


    def _inner(qtile):


        if len(qtile.screens) == 1:


            qtile.groups_map[name].toscreen()


            return


        if name in '123':


            qtile.focus_screen(0)


            qtile.groups_map[name].toscreen()


        else:


            qtile.focus_screen(1)


            qtile.groups_map[name].toscreen()


    return _inner
for i in groups:


    keys.append(Key([mod], i.name, lazy.function(go_to_group(i.name))))

To be able to move windows across these groups which switching groups, a similar function can be used:

def go_to_group_and_move_window(name: str):


    def _inner(qtile):


        if len(qtile.screens) == 1:


            qtile.current_window.togroup(name, switch_group=True)


            return


        if name in "123":


            qtile.current_window.togroup(name, switch_group=False)


            qtile.focus_screen(0)


            qtile.groups_map[name].toscreen()


        else:


            qtile.current_window.togroup(name, switch_group=False)


            qtile.focus_screen(1)


            qtile.groups_map[name].toscreen()


    return _inner
for i in groups:


    keys.append(Key([mod, "shift"], i.name, lazy.function(go_to_group_and_move_window(i.name))))

If you use the GroupBox widget you can make it reflect this behaviour:

groupbox1 = widget.GroupBox(visible_groups=['1', '2', '3'])
groupbox2 = widget.GroupBox(visible_groups=['q', 'w', 'e'])

And if you jump between having single and double screens then modifying the visible groups on the fly may be useful:

@hook.subscribe.screens_reconfigured
async def _():


    if len(qtile.screens) > 1:


        groupbox1.visible_groups = ['1', '2', '3']


    else:


        groupbox1.visible_groups = ['1', '2', '3', 'q', 'w', 'e']


    if hasattr(groupbox1, 'bar'):


        groupbox1.bar.draw()

Where can I find example configurations and other scripts?¶

Please visit our qtile-examples repo which contains examples of users' configurations, scripts and other useful links.

Where are the log files for Qtile?¶

The log files for qtile are at ~/.local/share/qtile/qtile.log.

How can I match the bar with picom?¶

You can use "QTILE_INTERNAL:32c = 1" in your picom.conf to match the bar. This will match all internal Qtile windows, so if you want to avoid that or to target bars individually, you can set a custom property and match that:

mybar = Bar(...)
@hook.subscribe.startup
def _():


    mybar.window.window.set_property("QTILE_BAR", 1, "CARDINAL", 32)

This would enable matching on mybar's window using "QTILE_BAR:32c = 1". See 2526 and 1515 for more discussion.

Why do get a warning that fonts cannot be loaded?¶

When installing Qtile on a new system, when running the test suite or the Xephyr script (./scripts/xephyr), you might see errors in the output like the following or similar:

xterm: cannot load font "-Misc-Fixed-medium-R-*-*-13-120-75-75-C-120-ISO10646-1"
xterm: cannot load font "-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1"

---------- Captured stderr call ----------
Warning: Cannot convert string "8x13" to type FontStruct
Warning: Unable to load any usable ISO8859 font
Warning: Unable to load any usable ISO8859 font
Error: Aborting: no font found
-------- Captured stderr teardown --------
Qtile exited with exitcode: -9

If it happens, it might be because you're missing fonts on your system.

On ArchLinux, you can fix this by installing xorg-fonts-misc:

sudo pacman -S xorg-fonts-misc

Try to search for "xorg fonts misc" with your distribution name on the internet to find how to install them.

I've upgraded and Qtile's broken. What do I do?¶

If you've recently upgraded, the first thing to do is check the changelog and see if any breaking changes were made.

Next, check your log file (see above) to see if any error messages explain what the problem is.

If you're still stuck, come and ask for help on Discord, IRC or GitHub.

What is a widget?¶

In Qtile, a widget is a small drawing that is displayed on the user's bar. The widget can display text, images and drawings. In addition, the widget can be configured to update based on timers, hooks, dbus_events etc. and can also respond to mouse events (clicks, scrolls and hover).

Widget base classes¶

Qtile provides a number of base classes for widgets than can be used to implement commonly required features (e.g. display text).

Your widget should inherit one of these classes. Whichever base class you inherit for your widget, if you override either the __init__ and/or _configure methods, you should make sure that your widget calls the equivalent method from the superclass.

class MyCustomWidget(base._TextBox):


    def __init__(self, **config):


        super().__init__("", **config)


        # My widget's initialisation code here

The functions of the various base classes are explained further below.

_Widget¶

This is the base widget class that defines the core components required for a widget. All other base classes are based off this class.

This is like a blank canvas so you're free to do what you want but you don't have any of the extra functionality provided by the other base classes.

The base._Widget class is therefore typically used for widgets that want to draw graphics on the widget as opposed to displaying text.

_TextBox¶

The base._TextBox class builds on the bare widget and adds a drawer.TextLayout which is accessible via the self.layout property. The widget will adjust its size to fit the amount of text to be displayed.

Text can be updated via the self.text property but note that this does not trigger a redrawing of the widget.

Parameters including font, fontsize, fontshadow, padding and foreground (font colour) can be configured. It is recommended not to hard-code these parameters as users may wish to have consistency across units.

InLoopPollText¶

The base.InLoopPollText class builds on the base._TextBox by adding a timer to periodically refresh the displayed text.

Widgets using this class should override the poll method to include a function that returns the required text.

NOTE:

ThreadPoolText¶

The base.ThreadPoolText class is very similar to the base.InLoopPollText class. The key difference is that the poll method is run asynchronously and triggers a callback once the function completes. This allows widgets to get text from long-running functions without blocking Qtile.

Mixins¶

As well as inheriting from one of the base classes above, widgets can also inherit one or more mixins to provide some additional functionality to the widget.

PaddingMixin¶

This provides the padding(_x|_y|) attributes which can be used to change the appearance of the widget.

If you use this mixin in your widget, you need to add the following line to your __init__ method:

self.add_defaults(base.PaddingMixin.defaults)

MarginMixin¶

The MarginMixin is essentially effectively exactly the same as the PaddingMixin but, instead, it provides the margin(_x|_y|) attributes.

As above, if you use this mixin in your widget, you need to add the following line to your __init__ method:

self.add_defaults(base.MarginMixin.defaults)

Configuration¶

Now you know which class to base your widget on, you need to know how the widget gets configured.

Defining Parameters¶

Each widget will likely have a number of parameters that users can change to customise the look and feel and/or behaviour of the widget for their own needs.

The widget should therefore provide the default values of these parameters as a class attribute called defaults. The format of this attribute is a list of tuples.

defaults = [


    ("parameter_name",


     default_parameter_value,


     "Short text explaining what parameter does")
]

Users can override the default value when creating their config.py file.

MyCustomWidget(parameter_name=updated_value)

Once the widget is initialised, these parameters are available at self.parameter_name.

The __init__ method¶

Parameters that should not be changed by users can be defined in the __init__ method.

This method is run when the widgets are initially created. This happens before the qtile object is available.

The _configure method¶

The _configure method is called by the bar object and sets the self.bar and self.qtile attributes of the widget. It also creates the self.drawer attribute which is necessary for displaying any content.

Once this method has been run, your widget should be ready to display content as the bar will draw once it has finished its configuration.

Calls to methods required to prepare the content for your widget should therefore be made from this method rather than __init__.

Displaying output¶

A Qtile widget is just a drawing that is displayed at a certain location the user's bar. The widget's job is therefore to create a small drawing surface that can be placed in the appropriate location on the bar.

The "draw" method¶

The draw method is called when the widget needs to update its appearance. This can be triggered by the widget itself (e.g. if the content has changed) or by the bar (e.g. if the bar needs to redraw its entire contents).

This method therefore needs to contain all the relevant code to draw the various components that make up the widget. Examples of displaying text, icons and drawings are set out below.

It is important to note that the bar controls the placing of the widget by assigning the offsetx value (for horizontal positioning) and offsety value (for vertical positioning). Widgets should use this at the end of the draw method. Both offsetx and offsety are required as both values will be set if the bar is drawing a border.

self.drawer.draw(offsetx=self.offsetx, offsety=self.offsety, width=self.width)

NOTE:

Displaying text¶

Text is displayed by using a drawer.TextLayout object. If all you are doing is displaying text then it's highly recommended that you use the base._TextBox superclass as this simplifies adding and updating text.

If you wish to implement this manually then you can create a your own drawer.TextLayout by using the self.drawer.textlayout method of the widget (only available after the _configure method has been run). object to include in your widget.

Some additional formatting of Text can be displayed using pango markup and ensuring the markup parameter is set to True.

self.textlayout = self.drawer.textlayout(


                     "Text",


                     "fffff",       # Font colour


                     "sans",        # Font family


                     12,            # Font size


                     None,          # Font shadow


                     markup=False,  # Pango markup (False by default)


                     wrap=True      # Wrap long lines (True by default)


                     )

Displaying icons and images¶

Qtile provides a helper library to convert images to a surface that can be drawn by the widget. If the images are static then you should only load them once when the widget is configured. Given the small size of the bar, this is most commonly used to draw icons but the same method applies to other images.

from libqtile import images
def setup_images(self):


    self.surfaces = {}


    # File names to load (will become keys to the `surfaces` dictionary)


    names = (


        "audio-volume-muted",


        "audio-volume-low",


        "audio-volume-medium",


        "audio-volume-high"


    )


    d_images = images.Loader(self.imagefolder)(*names)  # images.Loader can take more than one folder as an argument


    for name, img in d_images.items():


        new_height = self.bar.height - 1


        img.resize(height=new_height)   # Resize images to fit widget


        self.surfaces[name] = img.pattern  # Images added to the `surfaces` dictionary

Drawing the image is then just a matter of painting it to the relevant surface:

def draw(self):


    self.drawer.ctx.set_source(self.surfaces[img_name])  # Use correct key here for your image


    self.drawer.ctx.paint()


    self.drawer.draw(offsetx=self.offset, width=self.length)

Drawing shapes¶

It is possible to draw shapes directly to the widget. The Drawer class (available in your widget after configuration as self.drawer) provides some basic functions rounded_rectangle, rounded_fillrect, rectangle and fillrect.

In addition, you can access the Cairo context drawing functions via self.drawer.ctx.

For example, the following code can draw a wifi icon showing signal strength:

import math
...
def to_rads(self, degrees):


    return degrees * math.pi / 180.0
def draw_wifi(self, percentage):


    WIFI_HEIGHT = 12


    WIFI_ARC_DEGREES = 90


    y_margin = (self.bar.height - WIFI_HEIGHT) / 2


    half_arc = WIFI_ARC_DEGREES / 2


    # Draw grey background


    self.drawer.ctx.new_sub_path()


    self.drawer.ctx.move_to(WIFI_HEIGHT, y_margin + WIFI_HEIGHT)


    self.drawer.ctx.arc(WIFI_HEIGHT,


                        y_margin + WIFI_HEIGHT,


                        WIFI_HEIGHT,


                        self.to_rads(270 - half_arc),


                        self.to_rads(270 + half_arc))


    self.drawer.set_source_rgb("666666")


    self.drawer.ctx.fill()


    # Draw white section to represent signal strength


    self.drawer.ctx.new_sub_path()


    self.drawer.ctx.move_to(WIFI_HEIGHT, y_margin + WIFI_HEIGHT)


    self.drawer.ctx.arc(WIFI_HEIGHT


                        y_margin + WIFI_HEIGHT,


                        WIFI_HEIGHT * percentage,


                        self.to_rads(270 - half_arc),


                        self.to_rads(270 + half_arc))


    self.drawer.set_source_rgb("ffffff")


    self.drawer.ctx.fill()

This creates something looking like this: [image: wifi_image] [image] .

Background¶

At the start of the draw method, the widget should clear the drawer by drawing the background. Usually this is done by including the following line at the start of the method:

self.drawer.clear(self.background or self.bar.background)

The background can be a single colour or a list of colours which will result in a linear gradient from top to bottom.

Updating the widget¶

Widgets will usually need to update their content periodically. There are numerous ways that this can be done. Some of the most common ones are summarised below.

Timers¶

A non-blocking timer can be called by using the self.timeout_add method.

self.timeout_add(delay_in_seconds, method_to_call, (method_args))

NOTE:

Hooks¶

Qtile has a number of hooks built in which are triggered on certain events.

The WindowCount widget is a good example of using hooks to trigger updates. It includes the following method which is run when the widget is configured:

from libqtile import hook
...
def _setup_hooks(self):


    hook.subscribe.client_killed(self._win_killed)


    hook.subscribe.client_managed(self._wincount)


    hook.subscribe.current_screen_change(self._wincount)


    hook.subscribe.setgroup(self._wincount)

Read the Built-in Hooks page for details of which hooks are available and which arguments are passed to the callback function.

Using dbus¶

Qtile uses dbus-fast for interacting with dbus.

If you just want to listen for signals then Qtile provides a helper method called add_signal_receiver which can subscribe to a signal and trigger a callback whenever that signal is broadcast.

NOTE:

For example, the Mpris2 widget uses the following code:

from libqtile.utils import add_signal_receiver
...
async def _config_async(self):


    subscribe = await add_signal_receiver(


                    self.message,  # Callback function


                    session_bus=True,


                    signal_name="PropertiesChanged",


                    bus_name=self.objname,


                    path="/org/mpris/MediaPlayer2",


                    dbus_interface="org.freedesktop.DBus.Properties")

dbus-fast can also be used to query properties, call methods etc. on dbus interfaces. Refer to the dbus-fast documentation for more information on how to use the module.

Mouse events¶

By default, widgets handle button presses and will call any function that is bound to the button in the mouse_callbacks dictionary. The dictionary keys are as follows:

You can then define your button bindings in your widget (e.g. in __init__):

class MyWidget(widget.TextBox)


    def __init__(self, *args, **config):


        widget.TextBox.__init__(self, *args, **kwargs)


        self.add_callbacks(


            {


                "Button1": self.left_click_method,


                "Button3": self.right_click_method


            }


        )

NOTE:

self.add_callbacks(


    {


        "Button1": lazy.spawn("xterm"),


    }
)

In addition to button presses, you can also respond to mouse enter and leave events. For example, to make a clock show a longer date when you put your mouse over it, you can do the following:

class MouseOverClock(widget.Clock):


    defaults = [


        (


            "long_format",


            "%A %d %B %Y | %H:%M",


            "Format to show when mouse is over widget."


        )


    ]


    def __init__(self, **config):


        widget.Clock.__init__(self, **config)


        self.add_defaults(MouseOverClock.defaults)


        self.short_format = self.format


    def mouse_enter(self, *args, **kwargs):


        self.format = self.long_format


        self.bar.draw()


    def mouse_leave(self, *args, **kwargs):


        self.format = self.short_format


        self.bar.draw()

Exposing commands to the IPC interface¶

If you want to control your widget via lazy or scripting commands (such as qtile cmd-obj), you will need to expose the relevant methods in your widget. Exposing commands is done by adding the @expose_command() decorator to your method. For example:

from libqtile.command.base import expose_command
from libqtile.widget import TextBox
class ExposedWidget(TextBox):


    @expose_command()


    def uppercase(self):


        self.update(self.text.upper())

Text in the ExposedWidget can now be made into upper case by calling lazy.widget["exposedwidget"].uppercase() or qtile cmd-onj -o widget exposedwidget -f uppercase.

If you want to expose a method under multiple names, you can pass these additional names to the decorator. For example, decorating a method with:

@expose_command(["extra", "additional"])
def mymethod(self):


    ...

will make make the method visible under mymethod, extra and additional.

Debugging¶

You can use the logger object to record messages in the Qtile log file to help debug your development.

from libqtile.log_utils import logger
...
logger.debug("Callback function triggered")

NOTE:

Submitting the widget to the official repo¶

The following sections are only relevant for users who wish for their widgets to be submitted as a PR for inclusion in the main Qtile repo.

Including the widget in libqtile.widget¶

You should include your widget in the widgets dict in libqtile.widget.__init__.py. The relevant format is {"ClassName": "modulename"}.

This has a number of benefits:

Testing¶

Any new widgets should include an accompanying unit test.

Basic initialisation and configurations (using defaults) will automatically be tested by test/widgets/test_widget_init_configure.py if the widget has been included in libqtile.widget.__init__.py (see above).

However, where possible, it is strongly encouraged that widgets include additional unit tests that test specific functionality of the widget (e.g. reaction to hooks).

See Unit testing for more.

Documentation¶

It is really important that we maintain good documentation for Qtile. Any new widgets must therefore include sufficient documentation in order for users to understand how to use/configure the widget.

The majority of the documentation is generated automatically from your module. The widget's docstring will be used as the description of the widget. Any parameters defined in the widget's defaults attribute will also be displayed. It is essential that there is a clear explanation of each new parameter defined by the widget.

Screenshots¶

While not essential, it is strongly recommended that the documentation includes one or more screenshots.

Screenshots can be generated automatically with a minimal amount of coding by using the fixtures created by Qtile's test suite.

A screenshot file must satisfy the following criteria:

An example screenshot file is below:

import pytest
from libqtile.widget import wttr
from test.widgets.docs_screenshots.conftest import vertical_bar, widget_config
RESPONSE = "London: +17°C"
@pytest.fixture
def widget(monkeypatch):


    def result(self):


        return RESPONSE


    monkeypatch.setattr("libqtile.widget.wttr.Wttr.fetch", result)


    yield wttr.Wttr
@widget_config([{"location": {"London": "Home"}}])
def ss_wttr(screenshot_manager):


    screenshot_manager.take_screenshot()
@vertical_bar
def ss_wttr_vertical(screenshot_manager):


    screenshot_manager.take_screenshot()

The widget fixture returns the widget class (not an instance of the widget). Any monkeypatching of the widget should be included in this fixture.

The screenshot function (here, called ss_wttr) must take an argument called screenshot_manager. The function can also be parameterized, in which case, each dict object will be used to configure the widget for the screenshot (and the configuration will be displayed in the docs). If you want to include parameterizations but also want to show the default configuration, you should include an empty dict ({}) as the first object in the list.

Taking a screenshot is then as simple as calling screenshot_manager.take_screenshot(). The method can be called multiple times in the same function.

Screenshots can also be taken in a vertical bar orientation by using the @vertical_bar decorator as shown in the above example.

screenshot_manager.take_screenshot() only takes a picture of the widget. If you need to take a screenshot of the bar then you need a few extra steps:

def ss_bar_screenshot(screenshot_manager):


    # Generate a filename for the screenshot


    target = screenshot_manager.target()


    # Get the bar object


    bar = screenshot_manager.c.bar["top"]


    # Take a screenshot. Will take screenshot of whole bar unless


    # a `width` parameter is set.


    bar.take_screenshot(target, width=width)

Getting help¶

If you still need help with developing your widget then please submit a question in the qtile-dev group or submit an issue on the github page if you believe there's an error in the codebase.

What is a layout?¶

In Qtile, a layout is essentially a set of rules that determine how windows should be displayed on the screen. The layout is responsible for positioning all windows other than floating windows, "static" windows, internal windows (e.g. the bar) and windows that have requested not to be managed by the window manager.

Base classes¶

To simplify the creation of layouts, a couple of base classes are available to users.

The Layout class¶

As a bare minimum, all layouts should inherit the base Layout class object as this class defines a number of methods required for basic usage and will also raise errors if the required methods are not implemented. Further information on these required methods is set out below.

The _SimpleLayoutBase class¶

This class implements everything needed for a basic layout with the exception of the configure method. Therefore, unless your layout requires special logic for updating and navigating the list of clients, it is strongly recommended that your layout inherits this base class

The _ClientList class¶

This class defines a list of clients and the current client.

The collection is meant as a base or utility class for special layouts, which need to maintain one or several collections of windows, for example Columns or Stack, which use this class as base for their internal helper.

The property current_index get and set the index to the current client, whereas current_client property can be used with clients directly.

Required methods¶

To create a minimal, functioning layout your layout must include the methods listed below:

As noted above, if you create a layout based on the _SimpleLayoutBase class, you will only need to define configure (and _init__, if you have custom parameters). However, for the purposes of this document, we will show examples of all required methods.

__init__¶

Initialise your layout's variables here. The main use of this method will be to load any default parameters defined by layout. These are defined in a class attribute called defaults. The format of this attribute is a list of tuples.

from libqtile.layout import base
class TwoByTwo(base.Layout):


    """


    A simple layout with a fixed two by two grid.


    By default, unfocused windows are smaller than the focused window.


    """


    defaults = [


        ("border_width", 5, "Window border width"),


        ("border_colour", "00ff00", "Window border colour"),


        ("margin_focused", 5, "Margin width for focused windows"),


        ("margin_unfocused", 50, "Margin width for unfocused windows")


    ]


    def __init__(self, **config):


        base.Layout.__init__(self, **config)


        self.add_defaults(TwoByTwo.defaults)


        self.clients = []


        self.current_client = None

Once the layouts is initialised, these parameters are available at self.border_width etc.

configure¶

This is where the magic happens! This method is responsible for determining how to position a window on the screen.

This method should therefore configure the dimensions and borders of a window using the window's .place() method. The layout can also call either hide() or .unhide() on the window.

def configure(self, client: Window, screen_rect: ScreenRect) -> None:


    """Simple example breaking screen into four quarters."""


    try:


        index = self.clients.index(client)


    except ValueError:


        # Layout not expecting this window so ignore it


        return


    # We're only showing first 4 windows


    if index > 3:


        client.hide()


        return


    # Unhide the window in case it was hiddent before


    client.unhide()


    # List to help us calculate x and y values of


    quarters = [


        (0, 0),


        (0.5, 0),


        (0, 0.5),


        (0.5, 0.5)


    ]


    # Calculate size and position for each window


    xpos, ypos = quarters[index]


    x = int(screen_rect.width * xpos) + screen_rect.x


    y = int(screen_rect.height * ypos) + screen_rect.y


    w = screen_rect.width // 2


    h = screen_rect.height // 2


    if client is self.current_client:


        margin = self.margin_focused


    else:


        margin = self.margin_unfocused


    client.place(


        x,


        y,


        w - self.border_width * 2,


        h - self.border_width * 2,


        self.border_width,


        self.border_colour,


        margin=[margin] * 4,


    )

add_client¶

This method is called whenever a window is added to the group, regardless of whether the layout is current or not. The layout should just add the window to its internal datastructures, without mapping or configuring/displaying.

def add_client(self, client: Window) -> None:


    # Assumes self.clients is simple list


    self.clients.insert(0, client)


    self.current_client = client

remove¶

This method is called whenever a window is removed from the group, regardless of whether the layout is current or not. The layout should just de-register the window from its data structures, without unmapping the window.

The method must also return the "next" window that should gain focus or None if there are no other windows.

def remove(self, client: Window) -> Window | None:


    # Assumes self.clients is a simple list


    # Client already removed so ignore this


    if client not in self.clients:


        return None


    # Client is only window in the list


    elif len(self.clients) == 1:


        self.clients.remove(client)


        self.current_client = None


        # There are no other windows so return None


        return None


    else:


        # Find position of client in our list


        index = self.clients.index(client)


        # Remove client


        self.clients.remove(client)


        # Ensure the index value is not greater than list size


        # i.e. if we closed the last window in the list, we need to return


        # the first one (index 0).


        index %= len(self.clients)


        next_client = self.clients[index]


        self.current_client = next_client


        return next_client

focus_first¶

This method is called when the first client in the layout should be focused.

This method should just return the first client in the layout, if any. NB the method should not focus the client itself, this is done by caller.

def focus_first(self) -> Window | None:


    if not self.clients:


        return None


    return self.client[0]

focus_last¶

This method is called when the last client in the layout should be focused.

This method should just return the last client in the layout, if any. NB the method should not focus the client itself, this is done by caller.

def focus_last(self) -> Window | None:


    if not self.clients:


        return None


    return self.client[-1]

focus_next¶

This method is called the next client in the layout should be focused.

This method should return the next client in the layout, if any. NB the layout should not cycle clients when reaching the end of the list as there are other method in the group for cycling windows which focus floating windows once the the end of the tiled client list is reached.

In addition, the method should not focus the client.

def focus_next(self, win: Window) -> Window | None:


    try:


        return self.clients[self.clients.index(win) + 1]


    except IndexError:


        return None

focus_previous¶

This method is called the previous client in the layout should be focused.

This method should return the previous client in the layout, if any. NB the layout should not cycle clients when reaching the end of the list as there are other method in the group for cycling windows which focus floating windows once the the end of the tiled client list is reached.

In addition, the method should not focus the client.

def focus_previous(self, win: Window) -> Window | None:


    if not self.clients or self.clients.index(win) == 0


        return None


    try:


        return self.clients[self.clients.index(win) - 1]


    except IndexError:


        return None

next¶

This method focuses the next tiled window and can cycle back to the beginning of the list.

def next(self) -> None:


    if self.current_client is None:


        return


    # Get the next client or, if at the end of the list, get the first


    client = self.focus_next(self.current_client) or self.focus_first()


    self.group.focus(client, True)

previous¶

This method focuses the previous tiled window and can cycle back to the end of the list.

def previous(self) -> None:


    if self.current_client is None:


        return


    # Get the previous client or, if at the end of the list, get the last


    client = self.focus_previous(self.current_client) or self.focus_last()


    self.group.focus(client, True)

Additional methods¶

While not essential to implement, the following methods can also be defined:

clone¶

Each group gets a copy of the layout. The clone method is used to create this copy. The default implementation in Layout is as follows:

def clone(self, group: _Group) -> Self:


    c = copy.copy(self)


    c._group = group


    return c

show¶

This method can be used to run code when the layout is being displayed. The method receives one argument, the ScreenRect for the screen showing the layout.

The default implementation is a no-op:

def show(self, screen_rect: ScreenRect) -> None:


    pass

hide¶

This method can be used to run code when the layout is being hidden.

The default implementation is a no-op:

def hide(self) -> None:


    pass

swap¶

This method is used to change the position of two windows in the layout.

def swap(self, c1: Window, c2: Window) -> None:


    if c1 not in self.clients and c2 not in self.clients:


        return


    index1 = self.clients.index(c1)


    index2 = self.clients.index(c2)


    self.clients[index1], self.clients[index2] = self.clients[index2], self.clients[index1]

focus¶

This method is called when a given window is being focused.

def focus(self, client: Window) -> None:


    if client not in self.clients:


        self.current_client = None


        return


    index = self.clients.index(client)


    # Check if window is not visible


    if index > 3:


        c = self.clients.pop(index)


        self.clients.insert(0, c)


    self.current_client = client

blur¶

This method is called when the layout loses focus.

def blur(self) -> None:


    self.current_client = None

Adding commands¶

Adding commands allows users to modify the behaviour of the layout. To make commands available via the command interface (e.g. via lazy.layout calls), the layout must include the following import:

from libqtile.command.base import expose_command

Commands are then decorated with @expose_command. For example:

@expose_command
def rotate(self, clockwise: bool = True) -> None:


    if not self.clients:


        return


    if clockwise:


        client = self.clients.pop(-1)


        self.clients.insert(0, client)


    else:


        client = self.clients.pop(0)


        self.clients.append(client)


    # Check if current client has been rotated off the screen


    if self.current_client and self.clients.index(self.current_client) > 3:


        if clockwise:


            self.current_client = self.clients[3]


        else:


            self.current_client = self.clients[0]


    # Redraw the layout


    self.group.layout_all()

The info command¶

Layouts should also implement an info method to provide information about the layout.

As a minimum, the test suite (see below) will expect a layout to return the following information:

NB the last item is not included in Layout's implementation of the method so it should be added when defining a class that inherits that base.

@expose_command
def info(self) -> dict[str, Any]:


    inf = base.Layout.info(self)


    inf["clients"] = self.clients


    return inf

Adding layout to main repo¶

If you think your layout is amazing and you want to share with other users by including it in the main repo then there are a couple of extra steps that you need to take.

Add to list of layouts¶

You must save the layout in libqtile/layout and then add a line importing the layout definition to libqtile/layout/__init__.py e.g.

from libqtile.layout.twobytwo import TwoByTwo

Add tests¶

Basic functionality for all layouts is handled automatically by the core test suite. However, you should create tests for any custom functionality of your layout (e.g. testing the rotate command defined above).

Full example¶

The full code for the example layout is as follows:

from __future__ import annotations
from typing import TYPE_CHECKING
from libqtile.command.base import expose_command
from libqtile.layout import base
if TYPE_CHECKING:


    from libqtile.backend.base import Window


    from libqtile.config import ScreenRect


    from libqtile.group import _Group
class TwoByTwo(base.Layout):


    """


    A simple layout with a fixed two by two grid.


    By default, unfocused windows are smaller than the focused window.


    """


    defaults = [


        ("border_width", 5, "Window border width"),


        ("border_colour", "00ff00", "Window border colour"),


        ("margin_focused", 5, "Margin width for focused windows"),


        ("margin_unfocused", 50, "Margin width for unfocused windows")


    ]


    def __init__(self, **config):


        base.Layout.__init__(self, **config)


        self.add_defaults(TwoByTwo.defaults)


        self.clients = []


        self.current_client = None


    def configure(self, client: Window, screen_rect: ScreenRect) -> None:


        """Simple example breaking screen into four quarters."""


        try:


            index = self.clients.index(client)


        except ValueError:


            # Layout not expecting this window so ignore it


            return


        # We're only showing first 4 windows


        if index > 3:


            client.hide()


            return


        # Unhide the window in case it was hiddent before


        client.unhide()


        # List to help us calculate x and y values of


        quarters = [


            (0, 0),


            (0.5, 0),


            (0, 0.5),


            (0.5, 0.5)


        ]


        # Calculate size and position for each window


        xpos, ypos = quarters[index]


        x = int(screen_rect.width * xpos) + screen_rect.x


        y = int(screen_rect.height * ypos) + screen_rect.y


        w = screen_rect.width // 2


        h = screen_rect.height // 2


        if client is self.current_client:


            margin = self.margin_focused


        else:


            margin = self.margin_unfocused


        client.place(


            x,


            y,


            w - self.border_width * 2,


            h - self.border_width * 2,


            self.border_width,


            self.border_colour,


            margin=[margin] * 4,


        )


    def add_client(self, client: Window) -> None:


        # Assumes self.clients is simple list


        self.clients.insert(0, client)


        self.current_client = client


    def remove(self, client: Window) -> Window | None:


        # Assumes self.clients is a simple list


        # Client already removed so ignore this


        if client not in self.clients:


            return None


        # Client is only window in the list


        elif len(self.clients) == 1:


            self.clients.remove(client)


            self.current_client = None


            # There are no other windows so return None


            return None


        else:


            # Find position of client in our list


            index = self.clients.index(client)


            # Remove client


            self.clients.remove(client)


            # Ensure the index value is not greater than list size


            # i.e. if we closed the last window in the list, we need to return


            # the first one (index 0).


            index %= len(self.clients)


            next_client = self.clients[index]


            self.current_client = next_client


            return next_client


    def focus_first(self) -> Window | None:


        if not self.clients:


            return None


        return self.client[0]


    def focus_last(self) -> Window | None:


        if not self.clients:


            return None


        return self.client[-1]


    def focus_next(self, win: Window) -> Window | None:


        try:


            return self.clients[self.clients.index(win) + 1]


        except IndexError:


            return None


    def focus_previous(self, win: Window) -> Window | None:


        if not self.clients or self.clients.index(win) == 0:


            return None


        try:


            return self.clients[self.clients.index(win) - 1]


        except IndexError:


            return None


    def next(self) -> None:


        if self.current_client is None:


            return


        # Get the next client or, if at the end of the list, get the first


        client = self.focus_next(self.current_client) or self.focus_first()


        self.group.focus(client, True)


    def previous(self) -> None:


        if self.current_client is None:


            return


        # Get the previous client or, if at the end of the list, get the last


        client = self.focus_previous(self.current_client) or self.focus_last()


        self.group.focus(client, True)


    def swap(self, c1: Window, c2: Window) -> None:


        if c1 not in self.clients and c2 not in self.clients:


            return


        index1 = self.clients.index(c1)


        index2 = self.clients.index(c2)


        self.clients[index1], self.clients[index2] = self.clients[index2], self.clients[index1]


    def focus(self, client: Window) -> None:


        if client not in self.clients:


            self.current_client = None


            return


        index = self.clients.index(client)


        # Check if window is not visible


        if index > 3:


            c = self.clients.pop(index)


            self.clients.insert(0, c)


        self.current_client = client


    def blur(self) -> None:


        self.current_client = None


    @expose_command


    def rotate(self, clockwise: bool = True) -> None:


        if not self.clients:


            return


        if clockwise:


            client = self.clients.pop(-1)


            self.clients.insert(0, client)


        else:


            client = self.clients.pop(0)


            self.clients.append(client)


        # Check if current client has been rotated off the screen


        if self.current_client and self.clients.index(self.current_client) > 3:


            if clockwise:


                self.current_client = self.clients[3]


            else:


                self.current_client = self.clients[0]


        # Redraw the layout


        self.group.layout_all()


    @expose_command


    def info(self) -> dict[str, Any]:


        inf = base.Layout.info(self)


        inf["clients"] = self.clients


        return inf

This should result in a layout looking like this: [image: layout_image] [image] .

Getting help¶

If you still need help with developing your widget then please submit a question in the qtile-dev group or submit an issue on the github page if you believe there's an error in the codebase.

I want to try out a feature somebody is working on¶

If you see a pull request on GitHub that you want to try out, have a look at the line where it says:

user wants to merge n commits into qtile:master from user:branch

Right now you probably have one remote from which you can fetch changes, the origin. If you cloned qtile/qtile, git remote show origin will spit out the upstream url. If you cloned your fork, origin points to it and you probably want to git remote add upstream https://www.github.com/qtile/qtile. To try out somebody's work, you can add their fork as a new remote:

git remote add <user> https://www.github.com/user/qtile

where you fill in the username from the line we asked you to search for before. Then you can load data from that remote with git fetch and then ultimately check out the branch with git checkout <user>/<branch>.

Alternatively, it is also possible to fetch and checkout pull requests without needing to add other remotes. The upstream remote is sufficient:

git fetch upstream pull/<id>/head:pr<id>
git checkout pr<id>

The numeric pull request id can be found in the url or next to the title (preceded by a # symbol).

NOTE:

I committed changes and the tests failed¶

You can easily change your last commit: After you have done your work, git add everything you need and use git commit --amend to change your last commit. This causes the git history of your local clone to be diverged from your fork on GitHub, so you need to force-push your changes with:

git push -f <origin> <feature-branch>

where origin might be your user name or origin if you cloned your fork and feature-branch is to be replaced by the name of the branch you are working on.

Assuming the feature branch is currently checked out, you can usually omit it and just specify the origin.

I was told to rebase my work¶

If upstream/master is changed and you happened to change the same files as the commits that were added upstream, you should rebase your work onto the most recent upstream/master. Checkout your master, pull from upstream, checkout your branch again and then rebase it:

git checkout master
git pull upstream/master
git checkout <feature-branch>
git rebase upstream/master

You will be asked to solve conflicts where your diff cannot be applied with confidence to the work that was pushed upstream. If that is the case, open the files in your text editor and resolve the conflicts manually. You possibly need to git rebase --continue after you have resolved conflicts for one commit if you are rebasing multiple commits.

Note that the above doesn't work if you didn't create a branch. In that case you will find guides elsewhere to fix this problem, ideally by creating a branch and resetting your master branch to where it should be.

I was told to squash some commits¶

If you introduce changes in one commit and replace them in another, you are told to squash these changes into one single commit without the intermediate step:

git rebase -i master

opens a text editor with your commits and a comment block reminding you what you can do with your commits. You can reword them to change the commit message, reorder them or choose fixup to squash the changes of a commit into the commit on the line above.

This also changes your git history and you will need to force-push your changes afterwards.

Note that interactive rebasing also allows you to split, reorder and edit commits.

I was told to edit a commit message¶

If you need to edit the commit message of the last commit you did, use:

git commit --amend

to open an editor giving you the possibility to reword the message. If you want to reword the message of an older commit or multiple commits, use git rebase -i as above with the reword command in the editor.