Distro Guides

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

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.


Ubuntu Package

Needed for

Core Dependencies



Bars and popups



Drawing on bars and popups



Writing on bars and popups



Sending notifications with dbus (optional).


X server


X11 backends



required for X11 backend




Wayland backend (see below)



python bindings for the wlroots library



python bindings for the wayland library



required for wayland backeds


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

Finally, if you're a gnome user, you can start integrate Qtile into Gnome's session manager and use gnome as usual.


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.


We currently support wlroots==0.16.0,<0.17.0 and pywlroots==0.16.4.

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

export PYTHONPATH=$HOME/.local/lib/python$(python3 --version | awk -F '[ .]' '{print $2 "." $3}')/site-packages
$HOME/.local/bin/qtile $@

# 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