# Qtile

Related articles

- Comparison of tiling window managers
- Window manager

From Qtile web site:

  Qtile is a full-featured, hackable tiling window manager written in Python. Qtile is simple, small, and extensible. It's easy to write your own layouts, widgets, and built-in commands.It is written and configured entirely in Python, which means you can leverage the full power and flexibility of the language to make it fit your needs.

## Installing

Install one of the following packages:

- qtileAUR for the latest official release, running on Python 3.
- qtile-python2AUR for the latest official release, running on Python 2.
- qtile-python3-gitAUR for the latest git commit, running on Python 3.
- qtile-gitAUR for the latest git commit, running on Python 2.

## Starting

To start Qtile add `exec qtile` to your ~/.xinitrc and launch Xorg. The default configuration includes the shortcut `Super+Enter` to open a new xterm terminal, and `Super+Ctrl+q` to quit Qtile.

## Configuration

Note: This chapter only explains the basics of the configuration of Qtile. For more complete information, look at the official documentation.

As described in Configuration Lookup, Qtile provides a default configuration file that will be used in absence of user-defined ones. In order to start customizing Qtile, copy it to `~/.config/qtile/config.py`:

    $ mkdir -p ~/.config/qtile/
    $ cp /usr/share/doc/qtile_dir/default_config.py ~/.config/qtile/config.py

Where `qtile_dir` is the name of the AUR package you installed.

Alternatively, the most recent default configuration file can be downloaded from the git repository at libqtile/resources/default_config.py.

Several more complete configuration file examples can be found in the qtile-examples repository.

The configuration is fully done in Python: for a very quick introduction to the language you can read this tutorial.

Before restarting Qtile you can test your configuration file for syntax errors using the command:

    $ python2 -m py_compile ~/.config/qtile/config.py

If the command gives no output, your script is correct.

### Groups

In Qtile, the workspaces (or views) are called Groups. They can be defined as following:

    from libqtile.config import Group, Match
    ...
    groups = [
        Group("term"),
        Group("irc"),
        Group("web", match=Match(title=["Firefox"])),
       ]
    ...

### Keys

You can configure your shortcuts with the Key class. Here is an example of the shortcut `Alt+Shift+q` to quit the window manager.

    from libqtile.config import Key
    from libqtile.command import lazy
    ...
    keys = [
        Key(
            ["mod1", "shift"], "q",
            lazy.shutdown())
       ]
    ...

You can find out which `modX` corresponds to which key with the command Xmodmap.

#### Sound

You can add shortcuts to easily control the sound volume and state by adding a user to the audio group and using the `alsamixer` command-line interface.

    keys= [
        ...
        # Sound
        Key([], "XF86AudioMute", lazy.spawn("amixer -q set Master toggle")),
        Key([], "XF86AudioLowerVolume", lazy.spawn("amixer -c 0 sset Master 1- unmute")),
        Key([], "XF86AudioRaiseVolume", lazy.spawn("amixer -c 0 sset Master 1+ unmute"))
       ]

### Screens

Create one Screen class for every monitor you have. The bars of Qtile are configured in the Screen class as in the following example:

    from libqtile.config import Screen
    from libqtile import bar, widget
    ...
    screens = [
        Screen(
            bottom=bar.Bar([          # add a bar to the bottom of the screen
                widget.GroupBox(),    # display the current Group
                widget.WindowName()   # display the name of the window that currently has focus
                ], 30))
       ]
    ...

#### Bars and widgets

You can find a list of all the built-in widgets in the official documentation.

If you want to add a widget to your bar, just add it like in the example above (for the `WindowName` widget). For example, if we want to add a battery notification, we can use the `Battery` widget:

    from libqtile.config import Screen
    from libqtile import bar, widget
    ...
    screens = [
        Screen(top=bar.Bar([
            widget.GroupBox(),    # display the current Group
            widget.Battery()      # display the battery state
           ], 30))
       ]
    ...

### Startup

You can start up applications using hooks, specifically the `startup` hook. For a list of available hooks see the documentation.

Here is an example where an application starts only once:

    import os
    import subprocess

    @hook.subscribe.startup_once
    def autostart():
        home = os.path.expanduser('~')
        subprocess.call([home + '/.config/qtile/autostart.sh'])

## Debugging

If you want to locate the source of a problem, you can execute the following line in your terminal:

    echo "exec qtile" > /tmp/.start_qtile ; xinit /tmp/.start_qtile -- :2

## See also

- Qtile website
- The official documentation
- tilenol - A window manager inspired by Qtile.

Category:

- Tiling WMs