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.
Qtile will try to create the configuration file as a copy of the default config, if it doesn’t exist yet.
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.|
A function which generates group binding hotkeys. It takes a single argument, the DGroups object, and can use that to set up dynamic key bindings.
A sample implementation is available in libqtile/dgroups.py called simple_key_binder(), which will bind groups to mod+shift+0-10 by default.
|dgroups_app_rules||||A list of Rule objects which can send windows to various groups based on matching criteria.|
|extension_defaults||same as widget_defaults||Default settings for extensions.|
The default floating layout to use. This allows you to set custom floating rules among other things if you wish.
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.|
|main||None||This is a function which takes one argument, the qtile object, and is run after the qtile object has been initialized. This allows people to monkey patch in any code they want to before qtile actually starts. Note that we only consider the config objects and hooks to be public APIs, and reserve the right to refactor the internals at any time. Use at your own risk!|
||Default settings for bar widgets.|
|wmname||“LG3D”||Gasp! We’re lying here. In fact, nobody really uses or cares about this string besides java UI toolkits; you can see several discussions on the mailing lists, GitHub issues, and other WM documentation that suggest setting this string if your java app doesn’t work correctly. We may as well just lie and say that we’re a working one by default. We choose LG3D to maximize irony: it is a 3D non-reparenting WM written in java that happens to be on java’s whitelist.|
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: