How to Install and Configure Qtile

Qtile is a full-featured, hackable tiling window manager written and configured in Python. To get started, install it using the official install guide linked from qtile.org, then edit the Python configuration file to define your key bindings, layouts, and window rules. The current release shown on the site is v0.37.0 (Aug 7, 2026), and the project provides documentation, release notes, and an install guide as starting points.

Before You Install

Qtile is configured entirely in Python, so a working Python environment is part of the setup. The official site points you to the Install Guide and Release Notes rather than prescribing a single installation method, so follow those pages for your distribution or platform.

Two things worth knowing before you begin:

• Configuration is code. Your key bindings, layouts, and window behavior live in a Python config file, not a separate settings UI.
• You can reload without restarting. The default config includes a reload binding, so you can test changes quickly.

Installing Qtile

1. Open qtile.org and go to the Install Guide.
2. Follow the instructions for your operating system or distribution.
3. Check the Release Notes for the current version (v0.37.0) to confirm what you're installing.
4. After installation, start Qtile and confirm it launches. If you need help, the site links to Documentation, Issues, and GitHub.

The site also offers Screenshots and Videos, which are useful for seeing layouts in action before you commit to a setup.

Understanding the Configuration File

The configuration is written in Python and defines three main things: key bindings, layouts, and groups (workspaces). The default config that ships with Qtile is a working example you can edit directly.

Key bindings

Bindings are defined with Key, combining a modifier list, a key, and a lazy command. The default config includes practical examples:

Layout manipulation is also bound by default. For example, [mod, "shift"], "k" moves a window up, and the grow_left, grow_right, grow_down, and grow_up commands resize windows in each direction. [mod], "n" resets all window sizes, and [mod, "shift"], "Return" toggles between split and unsplit sides of the stack.

Groups and switching

Groups are created in a loop over the string "123456789", and each group gets a binding so mod plus a number switches to that group:

groups = [Group(i) for i in "123456789"]

for i in groups:
    keys.extend([
        Key([mod], i.name, lazy.group[i.name].toscreen(), desc=f"Switch to group {i.name}"),
    ])

Wayland-specific bindings

The default config includes virtual terminal (VT) switching for Wayland. Because the config loads before Qtile starts, the check for the Wayland core is deferred with .when(func=...):

for vt in range(1, 8):
    keys.append(
        Key(
            ["control", "mod1"],
            f"f{vt}",
            lazy.core.change_vt(vt).when(func=lambda: qtile.core.name == "wayland"),
            desc=f"Switch to VT {vt}",
        )
    )

This pattern matters if you run Qtile under Wayland: a plain check at config load time wouldn't work, so the condition is evaluated when the binding actually runs.

Editing and Reloading Your Config

1. Locate your Qtile config file (the install guide and documentation cover the expected location).
2. Edit the Python file — change key bindings, add or remove layouts, or adjust group definitions.
3. Save the file.
4. Press [mod, "control"], "r" to reload the config.
5. Test your changes. If something breaks, check the Issues page or Documentation on qtile.org.

Because reloading doesn't require a full restart, you can iterate on bindings and layouts incrementally rather than rebuilding your session each time.

Common Sticking Points

• Config errors block reload. Since the config is Python, a syntax or reference error will prevent it from loading. Keep changes small and reload often.
• Wayland vs. X11 differences. Some bindings, like VT switching, only apply under Wayland. The default config handles this with deferred checks rather than assuming a backend.
• Modifier key choice. The default config uses mod, which you can redefine to suit your keyboard. All the example bindings reference it consistently, so changing it in one place updates the whole set.
• Layout behavior on screen edges. As the default config notes, growing a window toward a screen edge can shrink it instead. Use normalize ([mod], "n") to reset sizes when layouts get awkward.

Where to Go Next

The qtile.org homepage links directly to Documentation, Install Guide, Release Notes, Screenshots, Videos, Issues, and GitHub. Start with the install guide for setup, use the documentation for configuration details, and check GitHub or Issues when something doesn't behave as expected.