Hacking Qtile


Any reasonably recent version of these should work, so you can probably just install them from your package manager.

On ubuntu, this can be done with sudo apt-get install python-nose xserver-xephyr x11-apps.

Running the test suite

$ cd test
$ nosetests

Note: nose runs the tests against the first version of qtile it finds on your $PYTHONPATH; for most people this is the currently installed version of qtile.

Using Xephyr and the test suite

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:


In practice, the development cycle looks something like this:

  1. make minor code change
  2. run appropriate test: nosetests --tests=test_module
  3. GOTO 1, until hackage is complete
  4. run entire test suite: nosetests
  5. commit

Second X Session

Some users prefer to test Qtile in it’s own brand new X session. If you’d like to run a second X session, you can switch to a new tty and start a new one with xinit second_xsession, where second_xsession is a file invoking your development version of qtile (and doing any other setup you want). Examples of custom xsession files are available in qtile-examples.

Contributing to Qtile

Now you’ve got a patch you want to submit to be merged to Qtile. Typically, this is done via github pull requests. Qtile uses a well known branching model; master is our current release, and the develop branch is what all pull requests should be based against.

While not all of our code follows PEP8, we do try to adhere to it where possible, and ideally any new code would be PEP8 compliant. Perhaps the biggest issue is tabs vs. spaces: only 4 space tabs, please. We also request that git commit messages follow the standard format.

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

Reporting Bugs

Please report any bugs you find to the github issue tracker.


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

Qtile Documentation


Previous topic

Frequently Asked Questions

Next topic


This Page