How To Run Bleeding-edge Qtile Within a Virtualenv

For having been using GNOME for quite a long time, I was considering trying some tiling window managers to see what it's like a few weeks ago. Along the way, I found a nice window manager written in Python: Qtile, what interests me most is that it's a hackable window manager, which makes it flexible to extend or change its behaviors.

Well, switching to use a tiling window manager is far simpler than I thought. There are two ways to have it:

  1. Installing it via the system's package manager, e.g. dnf for Fedora
  2. Installing it from the source code repo.

If you just want to give it a try, you can just install it via the package manager, logout the current X session, and re-login with Qtile as your window manager (there are options when you log in), and you're done. It's that simple.

As Qtile is still under active development, I would like to run the bleeding-edge source code to catch up with the main Qtile.

As in the docs, it's quite straight-forward to install it.

git clone git://
cd qtile
pip3 install .

But it will pollute the system environment, so I'd rather run it within a virtualenv.

Here are the steps on how to run it within a dedicated virtualenv for a user, say foo, on Fedora.

  1. Clone the repo

    mkdir -p ~/local/
    git clone
  2. Create a new virtualenv, and install dependencies there

    python3 -m venv ~/local/qtile/qtile-env/
    source ~/local/qtile/qtile-env/bin/activate
    # Install dependencies
    pip install xcffib
    pip install --no-cache-dir cairocffi
  3. Make a glue shell script to use the virtualenv

    cat > /home/foo/local/qtile/qtile-venv-entry <<EOF
    # This glue shell is only needed when you want to
    # run Qtile within a virtualenv
    source ~/local/qtile/qtile-env/bin/activate
    python ~/local/qtile/bin/qtile $*

    Also, make sure to make it executable, that is, chmod +x /home/foo/local/qtile/qtile-venv-entry

  4. Make a entry desktop file for the display manager

    cat > /usr/share/xsessions/qtile-venv.desktop <<EOF
    [Desktop Entry]
    Comment=Qtile Session Within Venv

    Pay attention to the Exec directive, it points to the glue script.

  5. Log out or reboot your system, then select "Qtile(venv)" as your window manager by clicking the setting icon when logging in.

See also

comments powered by Disqus