Installing Qtile

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

First, you need to install all of Qtile’s dependencies (although some are optional/not needed depending on your Python version, as noted below).

Note that Python 3 versions 3.3 and newer are currently supported and tested.


Qtile uses xcffib as an XCB binding, which has its own instructions for building from source. However, if you’d like to skip building it, you can install its dependencies, you will need libxcb and libffi with the associated headers (libxcb-render0-dev and libffi-dev on Ubuntu), and install it via PyPI:

pip install xcffib


Qtile uses cairocffi with XCB support via xcffib. You’ll need libcairo2, the underlying library used by the binding. You should be sure before you install cairocffi that xcffib has been installed, otherwise the needed cairo-xcb bindings will not be built. Once you’ve got the dependencies installed, you can use the latest version on PyPI:

pip install cairocffi


You’ll also need libpangocairo, which on Ubuntu can be installed via sudo apt-get install libpangocairo-1.0-0. Qtile uses this to provide text rendering (and binds directly to it via cffi with a small in-tree binding).


Qtile uses the asyncio module as introduced in PEP 3156 for its event loop. Based on your Python version, there are different ways to install this:

  • Python >=3.4: The asyncio module comes as part of the standard library, so there is nothing more to install.

  • Python 3.3: This has all the infrastructure needed to implement PEP 3156, but the asyncio module must be installed from the Tulip project. This is done by calling:

    pip install asyncio

    Alternatively, you can install trollius (see next point). Note, however, that trollius is deprecated, and it is recommended that you use tulip, as trollius will likely be dropped if (and when) Python 2 support is dropped.

  • Python 2 (and 3.3 without asyncio): You will need to install trollius, which backports the asyncio module functionality to work without the infrastructure introduced in PEP 3156. You can install this from PyPI:

    pip install trollius


Until someone comes along and writes an asyncio-based dbus library, qtile will depend on python-dbus to interact with dbus. This means that if you want to use things like notification daemon or mpris widgets, you’ll need to install python-gobject and python-dbus. Qtile will run fine without these, although it will emit a warning that some things won’t work.


With the dependencies in place, you can now install qtile:

git clone git://
cd qtile
sudo python install

Stable versions of Qtile can be installed from PyPI:

pip install qtile

As long as the necessary libraries are in place, this can be done at any point, however, it is recommended that you first install xcffib to ensure the cairo-xcb bindings are built (see above).