qtile

Start the window manager, if it is not running already (should ideally be run from .xsession or similar)

$ qtile start

$ qtile check

$ qtile top --force

$ qtile run-cmd --group [test-group] --float [xterm]

$ qtile cmd-obj --object cmd --function restart

qtile subcommand [options] [arguments]
qtile start [options]
qtile cmd [options] [command]
qtile check [options]

start
    Starts the Qtile window manager session. This is the most common use of the command.

start --config <file>
    Specifies an alternative configuration file to use instead of the default config.py.

start --no-spawn
    Prevents Qtile from spawning any X applications on startup.

start --display <display>
    Connects Qtile to a specified X display.

cmd
    Connects to a running Qtile instance via its IPC socket to send commands or query its state.

cmd -c <command>
    Executes a specified IPC command directly, e.g., 'qtile cmd -c shutdown'.

cmd --list-commands
    Lists all available commands that can be sent to the running Qtile instance.

cmd --json
    Formats the output of commands as JSON, useful for scripting.

shell
    Opens an interactive Python shell connected to the running Qtile instance, allowing direct manipulation.

check
    Checks the default Qtile configuration file for syntax errors without starting Qtile.

check --file <file>
    Checks a specified configuration file for syntax errors.

run-cmd
    Executes an arbitrary Python command string within the running Qtile process.

top
    Displays a list of currently managed windows and their properties, similar to 'xwininfo -tree'.

migrate
    Assists in migrating older Qtile configuration files to be compatible with newer versions.

Qtile is a dynamic, full-featured tiling window manager written and configured in Python. It aims to be simple, flexible, and extensible, allowing users to tailor their desktop environment precisely to their needs through straightforward Python code.

Unlike many other window managers, Qtile's configuration is not a declarative file but rather executable Python code, enabling complex logic, custom widgets, and dynamic behaviors. It supports both X11 and Wayland (through its Wayland compositor functionality). The qtile command itself is the primary interface for managing and interacting with the Qtile session, used for starting the window manager, sending commands to a running instance, checking configuration files, and more. It provides a robust and powerful environment for developers and power users who prefer a highly customizable and scriptable desktop.

Qtile requires a working Python installation and a graphical environment (X11 or Wayland). Its configuration file, config.py, is a Python script; therefore, syntax errors or runtime exceptions in this file will prevent Qtile from starting correctly. Debugging these issues often requires checking the log files. Users unfamiliar with Python or the concepts of tiling window managers may face a steeper learning curve initially.

Qtile's configuration is managed through a Python script, typically located at ~/.config/qtile/config.py. This file is loaded and executed by Qtile at startup, allowing users to define keybindings, layouts, widgets, screens, and custom behaviors using standard Python syntax and libraries.

The qtile cmd and qtile shell subcommands communicate with a running Qtile instance via a Unix domain socket. This IPC mechanism allows external scripts or user commands to interact with the window manager, send commands, query its state, or trigger actions without needing to restart the session.

Qtile generates log files (usually in ~/.local/share/qtile/qtile.log or a path specified by --log-path) that are crucial for debugging startup issues or runtime errors. The qtile check command can also be used to pre-validate the configuration file for basic syntax errors before attempting to start Qtile.

Qtile was originally developed by Aldric Giacomoni and released in 2009. Its core design principle was to provide a highly flexible and programmable window manager by leveraging the power of Python for its configuration and extensibility. Over the years, it has evolved significantly, gaining features like a built-in status bar with a wide range of widgets, support for multiple screens, and more recently, experimental but functional Wayland compositor capabilities, broadening its applicability beyond just X11 environments. Its development continues to be community-driven, focusing on stability, performance, and user-friendliness for Python enthusiasts.

i3(1), dwm(1), awesome(1), xinit(1), python(1)