Installation
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 CI 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.
Dependency |
Ubuntu Package |
Needed for |
|---|---|---|
Core Dependencies |
||
python3-cffi |
Bars and popups |
|
python3-cairocffi |
Drawing on bars and popups |
|
libpangocairo |
libpangocairo-1.0-0 |
Writing on bars and popups |
-- |
Sending notifications with dbus (optional). |
|
X11 |
||
X server |
xserver-xorg |
X11 backends |
python3-xcffib |
required for X11 backend |
|
Wayland |
||
libwlroots-dev |
Wayland backend (see below) |
|
-- |
generate C headers (Wayland backend) |
|
wayland-protocols |
Additional standard Wayland protocols |
|
Qtile
With the dependencies in place, you can now install the stable version of qtile from PyPI:
uv tool install qtile
Or with sets of dependencies:
uv tool install qtile[widgets] # for all widget dependencies
uv tool install qtile[all] # for all dependencies
Or install qtile-git with:
git clone https://github.com/qtile/qtile.git
cd qtile
uv tool install . # for minimal dependencies
uv tool install .[dev,widgets,optional-core] # for all dependencies
Installing other dependencies
If you use uv to install qtile, any python modules that you want to use with it
must be installed in the same environment. You have a few options for doing this:
At installation time:
# Install package from pypi
uv tool install --with package-name qtile # can use qtile[widgets] etc. as above
# Install from github repo
uv tool install --with git+https://github.com/elParaguayo/qtile-extras/ .
# Install from custom requirements file
uv tool install --with-requirements /path/to/requirements.txt .
Installing packages after installation is a bit more complicated and does not seem to
be officially supported when using uv tool. However, the following code should work:
cd $(uv tool dir)/qtile
uv pip install package-name
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. We are trying our best to keep up with latest wlroots release.
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. You can
install it manually with:
# copy the in-tree udev rules file to the right place to make udev see it
cat ./resources/99-qtile.rules | sudo tee /etc/udev/rules.d/99-qtile.rules