Qtile: the window manager you configure in Python

The configuration file is a Python program

Qtile's defining property is in its own tagline, a full-featured, hackable tiling window manager written and configured in Python, and the consequences run deeper than syntax preference. The configuration is not a file parsed by a generic engine, it is Python code executed as the session starts, so keys can be bound with loops, layouts chosen by hostname, and any logic a desktop requires expressed with ordinary conditionals and imports. The extension surface follows the same grain, the project describes writing your own layouts, widgets and commands as easy, because each is a Python class in a codebase the user already speaks. The implementation itself is pure Python per the package manifest, MIT licensed, with the project describing itself as simple, small and extensible, three adjectives that survive contact with the source tree, and the current line is v0.37.1, released the same September day as the last repository push.

Two display protocols, one window manager

Qtile runs as an X11 window manager or as a Wayland compositor, a dual role few projects attempt from one codebase, and the acknowledgements section is candid about how the Wayland half was built, thanking the authors of Sway, LabWC and DWL, whose implementations and source served as inspiration and reference for the protocol implementations and architectural patterns behind the wayland backend the project calls wayc. Standing on the shoulders of the C compositors that defined Wayland conventions, then reimplementing in Python, is a pragmatic path, the protocol semantics are hard-won knowledge while the surrounding system benefits from Python's hackability. For users, the practical question is which session type to run, and for contributors the backend split is visible everywhere, the Makefile's test runs accepting a backend selection and the CI Docker image carrying both Xorg utilities and Wayland plus wlroots development libraries. The X11 side, older and battle-tested through more than a decade of releases, remains the conservative choice, while the Wayland side tracks the protocol's maturation and inherits patterns the C compositors already proved.

A command shell for a live session

The command shell allows all aspects of Qtile to be managed and inspected, and that sentence deserves unpacking because it is the runtime story. A running session exposes its state, windows, groups, layouts, bars and widgets, as addressable objects with commands, so inspection and manipulation share one interface, the shell for interactive use and the same command tree for scripts. Complete remote scriptability extends the surface outward, scripts can set up workspaces, manipulate windows and update status bar widgets from outside the process, which is how sophisticated session automation gets written without touching internals. The project then makes a claim few window managers could, this remote scriptability makes it one of the most thoroughly unit-tested window managers around, because the same command interface that serves scripts also serves the test suite, the window manager can be driven and verified programmatically rather than screenshot by screenshot.

The Python 3.12 floor and a lean core

The package manifest states the requirements plainly, Python 3.12 or newer, CPython or PyPy, with a core of exactly three dependencies, cairocffi for drawing, cffi as its substrate, and xcffib for the X protocol binding. Everything heavier is optional and grouped, a widgets extra pulls in the integrations status bars actually use such as psutil for system metrics, pulsectl for volume, keyring and the IMAP library for mail, an optional_core group adds dbus-fast, prompt_toolkit and setproctitle, and the dev group carries the full testing and typing toolkit including pytest-asyncio, mypy and pre-commit. That discipline, a drawable core plus opt-in surface, is what lets the same package install minimally on a spare machine or fully on a daily driver, and the Python 3.12 floor signals a project that moves with the language rather than carrying a decade of compatibility shims.

CI in Fedora with Xephyr, Xvfb and gdb

Testing a window manager is an unusual engineering problem, and Qtile's answer is visible in its container and Makefile. The CI Dockerfile starts from Fedora 44 and installs a small display server farm, Xorg proper, Xephyr for nested sessions, Xvfb for headless frames, Xwayland for the compatibility path, alongside wayland and wlroots development libraries and the three Python versions 3.12 through 3.14 in parallel. The Makefile's check target builds the Wayland CFFI bindings, runs pytest through uv with a selectable backend, and, when running under GitHub Actions, dumps full backtraces from any core files using gdb in batch mode, the fingerprint of maintainers who debug native crashes in a Python process. Coverage combines across runs and reports to Coveralls, and a separate ci-check target reproduces the entire pipeline inside the container, making the test environment reproducible for any contributor.

Governance with GPG keys attached

The maintainers section is a small governance document in itself, four active maintainers listed with their GitHub handles and full GPG fingerprints, and a maintainers emeritus section honoring past leads the same way, an arrangement that lets anyone verify signed tags against a published identity. Community support runs through a mailing list, IRC on the OFTC network, a Discord server bridged to that IRC so both populations share one conversation, and a GitHub discussions board with a dedicated Q&A category, a topology that keeps the historical channels alive without fragmenting answers. Contributions follow an issue tracker plus documentation, with tips and tricks in a hacking section of the docs and formal guidelines alongside, and useful scripts are explicitly asked to go to the qtile-examples repository rather than the main tree, keeping the core clean while the ecosystem accumulates.

qtile-examples and the way people actually adopt it

The qtile-examples repository collects users' configurations, scripts and other links, and pointing newcomers there is the project's implicit admission of how tiling window managers are really adopted, by starting from someone else's working config and bending it. The package is published on PyPI with the qtile entry point, documentation builds on Read the Docs, and the codebase carries a Nix flake for reproducible environments, stubs for type checking, and a clang-format file for the C fragments of the Wayland bindings. Development ergonomics run through uv for dependency syncing and a docs target that builds the Sphinx site locally. Set against its peers, i3 and Sway configured in plain text, Hyprland a curated compositor, Qtile's bet remains that the people most invested in their desktops are also the people happiest to open a Python file, and fifteen years of releases suggest the bet keeps paying.

Editorial conclusion

Choose Qtile when you want your window manager to be a Python program you edit at runtime, layouts and widgets as importable classes, and a single configuration that follows your dotfiles like any other script. Choose i3 or Sway when config-as-INI simplicity matters more than programmability, or Hyprland for a batteries-included Wayland compositor with animated defaults. Verify first whether your session will run X11 or Wayland, since Qtile supports both but the backends differ in maturity, read the documentation at docs.qtile.org for the installation path matching your distribution, and start from a known-good configuration in the qtile-examples repository before writing your own from scratch.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. qtile/qtile on GitHub
4. README
5. Releases