Qtile is configured in Python. A script (
default) is evaluated, and a small set of configuration variables are pulled
from its global namespace.
Configuration lookup order¶
Qtile looks in the following places for a configuration file, in order:
- The location specified by the
$XDG_CONFIG_HOME/qtile/config.py, if it is set
- It reads the module
libqtile.resources.default_config, included by default with every Qtile installation.
The default configuration is invoked when qtile cannot find a configuration file. In addition, if qtile is restarted via qshell, qtile will load the default configuration if the config file it finds has some kind of error in it. The documentation below describes the configuration lookup process, as well as what the key bindings are in the default config.
The default config is not intended to be suitable for all users; it’s mostly just there so qtile does /something/ when fired up, and so that it doesn’t crash and cause you to lose all your work if you reload a bad config.
The mod key for the default config is
mod4, which is typically bound to
the “Super” keys, which are things like the windows key and the mac command
key. The basic operation is:
mod + kor
mod + j: switch windows on the current stack
mod + <space>: put focus on the other pane of the stack (when in stack layout)
mod + <tab>: switch layouts
mod + w: close window
mod + <ctrl> + r: restart qtile with new config
mod + <group name>: switch to that group
mod + <shift> + <group name>: send a window to that group
mod + <enter>: start xterm
mod + r: start a little prompt in the bar so users can run arbitrary commands
The default config defines one screen and 8 groups, one for each letter in
asdfuiop. It has a basic bottom bar that includes a group box, the current
window name, a little text reminder that you’re using the default config,
a system tray, and a clock.
The default configuration has several more advanced key combinations, but the above should be enough for basic usage of qtile.
By default, holding your
mod key and clicking (and holding) a window will
allow you to drag it around as a floating window.
A Qtile configuration consists of a file with a bunch of variables in it, which qtile imports and then runs as a python file to derive its final configuration. The documentation below describes the most common configuration variables; more advanced configuration can be found in the qtile-examples repository, which includes a number of real-world configurations that demonstrate how you can tune Qtile to your liking. (Feel free to issue a pull request to add your own configuration to the mix!)
In addition to the above variables, there are several other boolean configuration variables that control specific aspects of Qtile’s behavior:
|auto_fullscreen||True||If a window requests to be fullscreen, it is automatically fullscreened. Set this to false if you only want windows to be fullscreen if you ask them to be.|
|bring_front_click||False||When clicked, should the window be brought to the front or not. (This sets the X Stack Mode to Above.)|
|cursor_warp||False||If true, the cursor follows the focus as directed by the keyboard, warping to the center of the focused window.|
|extension_defaults||same as widget_defaults||Default settings for extensions.|
See the configuration file for the default float_rules.
Behavior of the _NET_ACTIVATE_WINDOW message sent by applications
|follow_mouse_focus||True||Controls whether or not focus follows the mouse around as it moves across windows in a layout.|
||Default settings for bar widgets.|
Testing your configuration¶
The best way to test changes to your configuration is with the provided Xephyr
script. This will run Qtile with your
config.py inside a nested X server
and prevent your running instance of Qtile from crashing if something goes
See Hacking Qtile for more information on using Xephyr.
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
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
qtile.desktop file above, but with
create your own
~/.xsession. There are several examples of user defined
xsession s in the qtile-examples repository.
Finally, if you’re a gnome user, you can start integrate Qtile into Gnome’s session manager and use gnome as usual: