qtile.org

Qtile is configured entirely in Python: you write a config.py file that defines your key bindings, layouts, groups, screens, and window rules, and Qtile executes that file as code. That means any customization you can express in Python — loops, conditionals, functions, imports — is available to you, and you can reload the running window manager with lazy.reload_config() instead of restarting your session. This approach suits users comfortable reading and editing Python; if you prefer declarative config formats, Qtile's model will feel unusual.

The config file is a Python program

Qtile's own documentation describes it as "a full-featured, hackable tiling window manager written and configured in Python." The configuration is not a data file that Qtile parses — it is imported and run, so the structures you build (lists of keys, groups, layouts) are ordinary Python objects.

A typical config defines these pieces:

Because these are plain Python values, you can generate them programmatically. The default config itself does this for workspaces:

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}"),
    ])

One list comprehension creates nine groups, and the loop attaches a switch-to-group binding for each one. Writing the same thing by hand would be nine near-identical blocks.

Key bindings: actions are lazy

Bindings pair a key combination with an action. Qtile wraps actions in lazy, which defers execution until the key is actually pressed — this is why you can reference qtile and its objects in a binding before the window manager has fully started.

From the default config:

Key([mod], "Return", lazy.spawn(terminal), desc="Launch terminal"),
Key([mod], "w", lazy.window.kill(), desc="Kill focused window"),
Key([mod], "f", lazy.window.toggle_fullscreen(),
    desc="Toggle fullscreen on the focused window"),
Key([mod], "t", lazy.window.toggle_floating(),
    desc="Toggle floating on the focused window"),
Key([mod], "Tab", lazy.next_layout(), desc="Toggle between layouts"),
Key([mod, "control"], "r", lazy.reload_config(), desc="Reload the config"),
Key([mod, "control"], "q", lazy.shutdown(), desc="Shutdown Qtile"),

The desc argument is not decoration — it feeds the command prompt and documentation, so a binding without one is harder to discover later.

Layout manipulation gets its own set of bindings, which is where tiling behavior becomes tunable at runtime:

Key([mod, "shift"], "k", lazy.layout.shuffle_up(), desc="Move window up"),
Key([mod, "control"], "h", lazy.layout.grow_left(), desc="Grow window to the left"),
Key([mod, "control"], "l", lazy.layout.grow_right(), desc="Grow window to the right"),
Key([mod], "n", lazy.layout.normalize(), desc="Reset all window sizes"),
Key([mod, "shift"], "Return", lazy.layout.toggle_split(),
    desc="Toggle between split and unsplit sides of stack"),

The comment in the default config notes a useful edge case: if the focused window is already at the screen edge and you grow it in that direction, it shrinks instead. normalize() is the reset when your manual resizing has gotten away from you.

Conditional behavior with .when()

Not every binding makes sense on every backend. Qtile runs on both X11 and Wayland, and virtual-terminal switching only applies to Wayland. Rather than branching at config-load time — the config is loaded before Qtile starts, so qtile.core.name isn't available yet — the default config defers the check to keypress time:

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}"),
    )

The .when(func=...) wrapper means the action only fires if the lambda returns true when the key is pressed. This pattern generalizes: any binding whose validity depends on runtime state can be guarded the same way.

Reloading without losing your session

lazy.reload_config() re-reads and re-executes your config file while Qtile keeps running. In practice this means you edit config.py, press your reload binding, and see the change — no logout, no restarting applications. This is the main reason the Python-as-config model stays workable despite being more verbose than a declarative format: the edit-test loop is short.

Two caveats worth knowing before you rely on it:

• A syntax error or exception in the config will surface at reload time, and Qtile's behavior on a failed reload depends on where the error occurs. Keep a known-good copy of your config before large edits.
• Reload re-runs the file, so any state you built up in Python objects (counters, caches) resets. If you need persistent state across reloads, store it outside the config.

Where customization actually pays off

The Python model is most valuable in three situations:

• Repetitive definitions. Workspaces, monitor setups, and per-application rules are naturally generated by loops, as the default config demonstrates with its nine groups.
• Logic that depends on state. Bindings or rules that should behave differently on Wayland vs. X11, or on a laptop vs. a docked monitor, can be expressed directly rather than through a config-format workaround.
• Integration with other Python code. Since the config is a Python module, it can import from your own modules or the standard library.

If none of those apply and you just want a static set of bindings, the Python requirement is overhead rather than an advantage — a declarative config would be shorter. The tradeoff is explicit: Qtile gives you a general-purpose language in exchange for writing more lines.

Getting started

The Qtile site links a Download page, Release Notes, and an Install Guide, and the current release listed is v0.37.0 (Aug 7, 2026). The default config shown throughout this article is the reference point to start from — copy it, then change one thing at a time and reload to confirm each change. Screenshots, videos, documentation, and the issue tracker are linked from the same site if you want to see configurations others have built before writing your own.

Qtile is a full-featured, hackable tiling window manager written and configured in Python. It is aimed at users who want their window management logic expressed as Python code rather than a separate configuration language. The current release listed on the project site is v0.37.0 (Aug 7, 2026).

What "tiling window manager" means here

A tiling window manager arranges windows automatically so they fill the screen without overlapping, instead of letting you drag and resize floating windows by hand. Qtile applies this model and exposes the controls as key bindings and Python objects.

The project's own framing emphasizes the benefits of a tiling window manager, and Qtile's distinguishing feature is that both the window manager and its configuration are Python. That means your config is a real program: you can import modules, write loops, define functions, and compute bindings rather than only declaring static values.

How configuration works

Qtile's default configuration is a Python file. Key bindings are declared as Key objects, and actions are wrapped in lazy calls so they run when the key is pressed rather than at load time.

A representative excerpt from the documented default config:

Key([mod, "shift"], "k", lazy.layout.shuffle_up(), desc="Move window up"),
Key([mod, "control"], "h", lazy.layout.grow_left(), desc="Grow window to the left"),
Key([mod], "n", lazy.layout.normalize(), desc="Reset all window sizes"),
Key([mod], "Return", lazy.spawn(terminal), desc="Launch terminal"),
Key([mod], "Tab", lazy.next_layout(), desc="Toggle between layouts"),
Key([mod], "w", lazy.window.kill(), desc="Kill focused window"),
Key([mod], "f", lazy.window.toggle_fullscreen(), desc="Toggle fullscreen on the focused window"),
Key([mod], "t", lazy.window.toggle_floating(), desc="Toggle floating on the focused window"),
Key([mod, "control"], "r", lazy.reload_config(), desc="Reload the config"),
Key([mod, "control"], "q", lazy.shutdown(), desc="Shutdown Qtile"),

Two things are worth noting for anyone evaluating Qtile:

• Layout actions are first-class. Commands like shuffle_up, grow_left, normalize, and toggle_split are layout methods, so window behavior is scriptable in the same language as everything else.
• Config can be reloaded without restarting. lazy.reload_config() is bound by default, which shortens the edit-test loop while you tune bindings.

Groups, layouts, and display servers

The default config builds workspaces as Group objects and generates bindings for them in a loop:

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}"),
    ])

This is a small but telling example: because the config is Python, a list comprehension and a for loop replace what would otherwise be nine near-identical declarations.

Qtile also supports switching between layouts at runtime (lazy.next_layout()), and the default config includes Wayland-specific virtual terminal bindings. Those bindings are guarded so they only take effect on Wayland:

lazy.core.change_vt(vt).when(func=lambda: qtile.core.name == "wayland")

The comment in the config explains why: the core name can't be checked while the default config is being loaded, because Qtile hasn't started yet, so the check is deferred until the binding actually runs. If you write your own conditional bindings, this is the pattern to copy.

Who Qtile suits

Qtile is a reasonable choice if:

• You are comfortable in Python and would rather configure a window manager in a language you already use.
• You want window behavior that depends on logic — computed bindings, loops over groups, conditional actions — rather than a fixed set of options.
• You want to reload configuration changes without restarting the session.

It is a weaker fit if you don't want to read or write Python to change how your windows behave, or if you prefer a configuration format that is purely declarative.

Where to go next

The project site (qtile.org) links to screenshots, videos, documentation, the issue tracker, and GitHub, plus a download link, release notes, and an install guide for the current v0.37.0 release. The install guide is the right starting point for setup; the documentation covers layouts, widgets, and the configuration API referenced by the default config above.

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.

A tiling window manager arranges every window automatically so that nothing overlaps and no space is wasted, and Qtile applies that model while letting you define layouts, key bindings, and behavior in Python. The benefits are most concrete for people who keep many windows open at once and prefer the keyboard over the mouse: less time spent resizing and positioning, more predictable screen real estate, and a configuration that can be version-controlled and scripted like any other code.

Windows arrange themselves

In a traditional stacking window manager, opening a window gives you a floating rectangle you must move and resize by hand, and windows cover each other. A tiling manager instead places each new window into a slot determined by the current layout. Qtile ships with multiple layouts and lets you switch between them at runtime.

The practical effect is that the arrangement is a property of the layout, not of your last mouse drag. When you close a window, the remaining ones reflow to fill the gap.

Keyboard-first control

Qtile's default configuration binds actions to key combinations rather than menu clicks. The published default config includes bindings such as:

• [mod] + Return — launch a terminal
• [mod] + Tab — cycle to the next layout
• [mod] + w — kill the focused window
• [mod] + f — toggle fullscreen on the focused window
• [mod] + t — toggle floating on the focused window
• [mod] + control + r — reload the config
• [mod] + control + q — shut down Qtile
• [mod] + r — spawn a command using a prompt widget

Because these are ordinary Python objects, you can add, remove, or rebind them. The default config also shows layout-specific bindings, for example [mod, shift] + k to shuffle a window up, [mod, control] + h/j/k/l to grow a window in each direction, and [mod] + n to reset all window sizes. The result is that common window operations become single keystrokes instead of pointer gestures.

Better use of screen space

Tiling exists to avoid the two failure modes of floating windows: wasted gaps and covered content. Every managed window occupies a defined region, so a wide monitor can hold several readable columns instead of one maximized window with empty margins.

Qtile's layouts are not all-or-nothing. The default config includes a split/unsplit toggle ([mod, shift] + Return) that switches between showing all windows in the stack and showing one window at a time in a maximized-like view while keeping the other stack panes available. That lets you move between "see everything" and "focus on one" without leaving the tiling model.

Configuration as code

Qtile is described as a full-featured, hackable tiling window manager written and configured in Python. That has two consequences worth weighing:

• Customization is programmatic. Layouts, key bindings, groups, and hooks are Python, so you can compute bindings in loops, import helpers, and share snippets. The default config, for example, generates workspace groups from the string "123456789" and builds a key binding per group in a loop.
• It fits developer workflows. A config file can live in version control, be diffed, and be reviewed like other code. If you already work in Python, the editing model is familiar.

Where the trade-offs show up

The same properties that make tiling efficient also impose constraints:

• You adapt to the layout. Windows are placed for you, so learning the layouts and bindings is part of the deal. The default config's comments note that growing a window toward a screen edge can shrink it instead, which is the kind of behavior you learn by using it.
• Floating is the exception. Some dialogs and tools behave better as floating windows. Qtile provides a per-window floating toggle ([mod] + t), so you are not locked into tiling for every window.
• Platform details matter. The default config includes Wayland-specific key bindings for switching virtual terminals, guarded so they only apply when the core is Wayland. If you are choosing between X11 and Wayland, check that the bindings and behavior you rely on are supported on your session type.

Who gets the most out of it

Qtile is a reasonable fit if you keep several terminals, editors, and browsers open simultaneously, want window management driven from the keyboard, and are comfortable maintaining a Python configuration file. It is a weaker fit if you rely heavily on free-form window placement, prefer graphical settings panels over editing code, or do not want to learn a set of key bindings before the environment feels natural.

To evaluate it against your own habits, the site's documentation, screenshots, and videos show the layouts and default bindings in use, and the install guide covers getting a working session before you commit to rewriting the config.