# QuickTile: window tiling hotkeys for an existing X11 desktop

> QuickTile is a Python utility that adds keyboard driven window tiling to an X11 desktop without replacing your window manager, using GTK and the Wnck window list to move and resize windows where a tiling manager would. It binds global hotkeys through a daemon, is configured by an INI file, and runs on Python 3.12 or newer under the GPL v2 or later.

**ssokolow/quicktile** — Adds window-tiling hotkeys to any X11 desktop. (An analogue to WinSplit Revolution)

- Repository: https://github.com/ssokolow/quicktile
- Website: https://ssokolow.com/quicktile/
- Stars: 913 · Forks: 90
- Language: Python
- License: GPL-2.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/ssokolow-quicktile

## Tiling without taking over the window manager

QuickTile describes itself as keyboard driven window tiling for your existing X11 window manager, and the project description compares it to WinSplit Revolution. That comparison sets the expectation correctly: this is a set of shortcuts for placing and resizing windows, not a window manager.

The distinction matters more than it sounds. A tiling window manager owns your windows, decides their positions, handles focus and stacking, and typically has its own workspace model. QuickTile leaves all of that alone and simply moves and resizes windows you already have, using the desktop's own window list to find them.

The mechanism for that is GTK and the Wnck library. The topic list names gtk, gtk3, pygobject, python3 and x11, and the dependencies in the project file are dbus-python, PyGObject and python-xlib. Wnck is what lets the tool enumerate the windows of the running desktop and ask the window manager to move them, which is why the same script works under GNOME, KDE and other X11 environments without being written for any one of them.

The practical result is that you keep your existing desktop behaviour, including its own window switching with something like Alt+Tab, and you add a tiling layer on top. The README makes that combination the recommended usage, precisely to avoid switching your hand between keyboard and mouse.

## Installing the runtime dependencies on Debian and Fedora

The dependency list is long because it spans both the X11 bindings and the desktop introspection data, and the README gives the exact package names for the two most common distribution families.

On Debian and derivatives, including Ubuntu and Mint, the install is an apt-get of python3, python3-pip, python3-setuptools, python3-gi, python3-xlib, python3-dbus, gir1.2-glib-2.0, gir1.2-gtk-3.0 and gir1.2-wnck-3.0.

On Fedora and derivatives the equivalent dnf install covers python3, python3-pip, python3-setuptools, python3-gobject, python3-xlib, python3-dbus, gtk3 and libwnck3.

The gir packages on the Debian side are the GObject introspection data for GTK 3 and for Wnck, and the Wnck one is the piece that makes the window list readable. Other distributions, and more detail, are covered in the dependencies section of the manual.

The project file adds two constraints worth noting. Python 3.12 or newer is required, and the package is marked as a GTK X11 application with the development status given as beta.

There is also a Debian packaging directory in the repository, along with a recompile_local_debian_package.sh script, so the project supports distribution packaging rather than only pip.

## Running from source or installing with pip3

QuickTile can be run straight from a source checkout with the bundled shell script, with no installation at all.

The launcher is the quicktile.sh script in the source folder.

For a system-wide install the current option is pip3, and the README notes that this is chosen because it records a log, which makes uninstallation easy.

The command is `sudo -H pip3 install https://github.com/ssokolow/quicktile/archive/master.zip`.

The manual notes that now that PyGObject is available on PyPI, other options are being explored, which implies the pip route was chosen partly because the other methods were not viable rather than because it is the nicest one.

Uninstalling is symmetric.

The two commands are `sudo pip3 uninstall --break-system-packages quicktile` and `sudo rm /usr/local/bin/quicktile`.

That --break-system-packages flag is not incidental. Without it, pip refuses to remove anything installed outside a virtualenv, including things it installed itself, because it may remove files the system package manager is managing. The manual explains what a safe use of the flag looks like and how to clean up files left behind by other installation methods.

The build system is setuptools with the version read from a VERSION file inside the package, and the entry point is registered as quicktile pointing at the main module.

## Four steps to working global hotkeys

The first-run instructions for global hotkeys are a short sequence and it is worth following it in order, because each step depends on the previous one.

First, run quicktile or the script once to generate your configuration file at ~/.config/quicktile.cfg. The tool writes its own defaults on first launch, so there is no configuration file to create by hand.

Second, edit the keybindings as you want them.

Third, run quicktile --daemonize, or the script with that flag, to bind the global hotkeys.

Fourth, if it all works, add the daemonized command to the list of commands your desktop runs at login.

There are two flags that make this self documenting. Running quicktile --show-actions lists the valid actions you can bind in the configuration file, and running quicktile --show-bindings lists your current keybindings. Both are the fastest way to answer the question of what a name like a window cycling action is actually called.

One warning applies to the daemonize step. If you run it from a terminal, QuickTile attempts to report any problems with claiming the global hotkeys for itself. That is deliberate: a hotkey that another application already owns fails silently otherwise, and the terminal is where you want to see that message.

The typical usage afterwards is three actions. Focus the window you want to tile. Hold the modifiers defined in ModMask, which is Ctrl+Alt by default. Then repeatedly press one of the keybindings to cycle through the window sizes available at that location on the screen. Under the defaults, repeatedly pressing Ctrl+Alt+7 places the active window in the top-left corner and cycles it through the width presets.

## The configuration file is the whole interface

The configuration lives in ~/.config/quicktile.cfg, an INI style file, and it is where keybindings, screen geometry and behaviour all live.

The key concept is the cycle. A single keybinding is not a fixed action but a set of related ones, and pressing the key repeatedly walks through the sizes available at that screen location. That is why the usage instructions say to press the binding repeatedly rather than once, and it is the design element that distinguishes QuickTile from a simple position hotkey.

The ModMask setting holds the modifier combination, Ctrl+Alt by default, and changing it is how you avoid a conflict with a shortcut your desktop already uses.

The repository ships the documentation as a Sphinx project in the docs/ directory, and the configuration section of the manual at ssokolow.com covers the full set of settings. The command reference page lists the default keybindings in detail.

The project file also configures the test tooling in a way that reflects the project layout. Pytest runs with --doctest-modules and coverage enabled with branch coverage, and the coverage report has an omit list. There is a run_tests.sh and a test_functional.sh at the repository root, plus a tests/ directory, and a dev_requirements.txt for the extra development dependencies.

## The maintainer's caveats about contributing

The contributing section carries two constraints that are unusual enough to be worth reading before you send a pull request.

The first is about Flathub. The author has plans to make Flathub into QuickTile's primary distribution channel, and Flathub disallows AI generated or AI assisted applications. The reasoning is that a project planning to live on Flathub cannot accept contributions whose provenance would violate the platform's rules.

The second is about time. The author states that his time for working on hobby projects is very limited, so it may take a while to accept any pull request that cannot be git pulled, reviewed and QA tested in 15 to 30 minutes between other things. He gives major architectural changes as an example of what falls outside that window, and also notes that some functionality can only be QA tested under GNOME, since GNOME runs badly under VirtualBox on KDE and requires a hand-me-down laptop to set up for testing.

The recommended approach is to open an issue first indicating interest, so that non-obvious design concerns can be raised before the work is done.

There is also a ready supply of simple tasks available through two mechanisms. Running grep -R TODO *.py quicktile/ in the project root finds the inline ones, and setting todo_include_todos to True in docs/conf.py and building the docs generates a version of the manual with a TODO listing on the top level API documentation page.

The project is not archived and the last push was on 2026-05-31, and it publishes no GitHub releases, with the ChangeLog file at the repository root carrying the version history.

## Conclusion

Adopt QuickTile if you like the idea of a tiling window manager but do not want to give up the window manager you already have, since it layers tiling shortcuts over GNOME, KDE or any other X11 setup without taking over window management. Do not adopt it if you want a full tiling workflow, because it deliberately does not manage windows for you and does not handle stacking, focus policy or workspaces. Verify first that your desktop still runs X11 rather than Wayland, that Python 3.12 or newer is available along with PyGObject, python-xlib and dbus-python, that the GTK and Wnck introspection packages are installed so the window list can be read, and that you read the maintainer's contribution caveat before sending a pull request.

## FAQ

### How do I install QuickTile's dependencies on Debian or Ubuntu?

Run sudo apt-get install python3 python3-pip python3-setuptools python3-gi python3-xlib python3-dbus gir1.2-glib-2.0 gir1.2-gtk-3.0 gir1.2-wnck-3.0. The Wnck introspection package is what lets QuickTile read the list of windows from the running desktop.

### How do I get global hotkeys working in QuickTile?

Run quicktile once to generate ~/.config/quicktile.cfg, edit the keybindings, then run quicktile --daemonize to bind them. Add that daemonized command to your desktop's login commands once it works. If run from a terminal, the daemonize option reports problems with claiming the hotkeys.

### Does QuickTile replace my window manager?

No. It adds keyboard driven window tiling to an existing X11 window manager by moving and resizing windows through GTK and Wnck, and it deliberately leaves window management itself alone. It is described as an analogue to WinSplit Revolution.

### How do I uninstall QuickTile?

Run sudo pip3 uninstall --break-system-packages quicktile and then sudo rm /usr/local/bin/quicktile. Without the break-system-packages flag pip refuses to remove packages installed outside a virtualenv because it may remove files the system package manager is managing.

## Sources

- [Issues](https://github.com/ssokolow/quicktile/issues)
- [License: GPL-2.0](https://github.com/ssokolow/quicktile/blob/master/LICENSE)
- [Project website](https://ssokolow.com/quicktile/)
- [README](https://github.com/ssokolow/quicktile/blob/master/README.md)
- [ssokolow/quicktile on GitHub](https://github.com/ssokolow/quicktile)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ssokolow-quicktile