Ubuntu/Debian 上安装与启动 Qtile 平铺窗口管理器：依赖清单、uv 工具链与 X11/Wayland 双后端实践

• 桌面应用
• 操作系统

导读：本文基于 docs/manual/install/ubuntu.rst 与其父级安装指南 docs/manual/install/index.rst，系统讲解在 Ubuntu / Debian 系列发行版上安装、配置与启动 Qtile 的完整路径——包括新版发行版的软件包直装方案、旧版发行版的系统依赖准备、基于uv tool的现代 Python 工具链安装方式，以及 X11 / Wayland 双后端的启动方法与硬件权限（udev 规则）配置。读完本文，你可以在一台全新的 Ubuntu 或 Debian 机器上，从零把 Qtile 跑起来并接入自己的登录管理器。

Qtile 是一个使用 Python 编写和配置的全功能平铺窗口管理器（Tiling Window Manager），同时支持 X11 与 Wayland 两种后端（仓库描述见 README.rst）。由于它完全用 Python 驱动，安装环节的核心就是"把系统依赖和 Python 环境准备到位"。本文按照官方文档的顺序，把从系统包到 Python 工具链、从启动方式到硬件权限的全部环节串起来，并结合仓库源码给出可验证的实现细节。

一、两种安装时代：先判断你的发行版版本

ubuntu.rst明确区分了两个阶段，安装前请先确认自己的发行版版本：

• 新版发行版（Debian >= 13，Ubuntu >= 25.04）：仓库已经打包了 Qtile，直接使用系统包管理器安装即可。每个发行版发布版本对应的 Qtile 具体版本号，可以分别到packages.debian.org或packages.ubuntu.com的软件包搜索页（关键词qtile）查询。
• 旧版发行版（Debian / Ubuntu >= 11）：系统仓库中没有 Qtile 本体，但提供了运行 Qtile 所需的全部系统依赖，Qtile 本身需要从 PyPI 或 GitHub 仓库安装。

因此，本指南的默认前提是"旧版发行版场景"，这同时也覆盖了新版发行版中"想使用比系统包更新的 Qtile"的情况。

二、系统级依赖准备（旧版发行版）

从一份最小化的 Debian/Ubuntu 安装出发，官方文档给出的系统包清单如下：

sudo apt install xserver-xorg xinit sudo apt install libpangocairo-1.0-0 sudo apt install uv # 如果你的发行版没有 uv 包，可以尝试官方安装脚本： # curl -LsSf https://astral.sh/uv/install.sh | sh

这三组包分别解决三个问题：

需要注意的是libpangocairo-1.0-0是 C 库层面的依赖，python3-cairocffi才是 Python 绑定层，两者都要装齐，Qtile 的 bar 才能正常渲染文字。

完整依赖对照表

index.rst中给出了 Qtile 运行时的核心依赖与 Ubuntu 包名的完整对照表。Qtile 可以运行在两种后端之一（X11 或 Wayland），因此只需要满足其中一个后端的依赖：

从 pyproject.toml 的[project]段可以看到当前仓库声明的强制 Python 依赖为：

requires-python = ">=3.12" dependencies = [ "cairocffi >= 1.7.0", "cffi >= 1.1.0", "xcffib >= 1.4.0", ]

也就是说，任何后端场景下 cairocffi、cffi、xcffib 三者都会随包安装，Ubuntu 侧的python3-cffi/python3-cairocffi对应的是系统层面的同名包；如果你采用uv tool安装（见下文），Qtile 会被装入独立的环境，这些 Python 依赖由uv自行解决，系统包只需保证libpangocairo-1.0-0这类 C 库到位。

关于 Wayland 依赖还有一个重要提醒（原文明确强调）：wlroots 处于快速开发迭代中，部分发行版打包的 wlroots 版本可能过旧，Qtile 官方在努力跟进最新的 wlroots release。如果你的发行版 wlroots 版本太旧导致 Wayland 后端无法启动，优先考虑从较新的发行版仓库或源码构建 wlroots。

Python 解释器：CPython 与 PyPy

官方对 Python 解释器的支持策略（index.rst）是：始终支持 CPython 最近三个版本，同时通常支持 PyPy 的最新稳定版。当前仓库在 pyproject.toml 中声明requires-python = ">=3.12"，分类器（classifiers）明确标注支持 CPython 3.12 / 3.13 以及 PyPy。两者的取舍官方给出如下结论：

• PyPy：对"会被反复执行多次"的 Python 代码片段通常比对应版本的 CPython 更快；
• CPython：启动速度更快，且对外部 C 扩展库的兼容性更好。

配置文件中能否使用某些 Python 语言特性，会受解释器版本影响，这是两个解释器之间最主要的实际差异。

三、用 uv 工具链安装 Qtile

装好系统依赖后，安装 Qtile 本体最推荐的方式是uv tool（uv tool会把 Qtile 装进独立环境并为其创建可执行命令入口）：

# 安装稳定版（来自 PyPI） uv tool install qtile # 附带依赖集安装 uv tool install qtile[widgets] # 安装全部 widget 依赖 uv tool install qtile[all] # 安装全部可选依赖

从 GitHub 源码安装（qtile-git）

想跟进最新开发版，官方推荐直接 clone 仓库后用uv tool安装：

git clone https://github.com/qtile/qtile.git cd qtile uv tool install . # 最小依赖 uv tool install .[dev,widgets,optional-core] # 全部依赖

关于第二行的 extras 名称，仓库 pyproject.toml 中[project.optional-dependencies]实际定义的键为dev、optional_core、widgets、docs。optional-core与optional_core在 extras 归一化规则（PEP 685）下等价，均可使用。各 extras 的组成（以当前仓库为准）为：

其中setproctitle对应源码 libqtile/scripts/start.py 中的rename_process()：安装了它，Qtile 进程标题会被设为qtile，从而可以直接killall qtile；未安装时该函数静默失败，不影响运行。

给 Qtile 环境补装额外的 Python 模块

Qtile 的配置是 Python 代码，你很可能想在配置里 import 一些第三方模块。由于uv tool会创建独立的工具环境，任何要在配置中使用的 Python 模块都必须装进同一个环境。官方文档给出两种做法：

1. 安装时一并指定（推荐，最清晰）：

# 从 PyPI 安装额外包（qtile[widgets] 等 extras 同样适用） uv tool install --with package-name qtile # 从 GitHub 仓库安装 uv tool install --with git+https://github.com/elParaguayo/qtile-extras/ . # 从自定义 requirements 文件安装 uv tool install --with-requirements /path/to/requirements.txt .

2. 安装后补装：官方明确指出，安装后再往uv tool环境里补包"并没有被官方正式支持"，但以下命令在实践中可用：

cd $(uv tool dir)/qtile uv pip install package-name

四、启动 Qtile（X11 场景）

index.rst总结了四种进入 Qtile 会话的方式，由易到难排列如下。

方式一：通过登录管理器（显示管理器）菜单

最常规的方式，是在 X 会话管理器的菜单中加入 Qtile 条目——在/usr/share/xsessions目录下创建qtile.desktop文件。仓库自带的 resources/qtile.desktop 内容如下：

[Desktop Entry] Name=Qtile Comment=Qtile Session Exec=/usr/bin/qtile start Type=Application Keywords=wm;tiling

复制到目标位置后，SDDM、LightDM、GDM 等显示管理器的会话选择列表里就会出现 "Qtile" 条目。

方式二：自定义 X session（适合做启动前预处理）

当你需要在 Qtile 启动前执行自定义初始化（例如把 Caps Lock 映射为 Control、设置桌面壁纸、加载键盘映射等），可以走自定义 X session：

1. 创建custom.desktop（内容与qtile.desktop类似，但Exec=/etc/X11/xsession）；
2. 编写自己的~/.xsession，在文件末尾调用 Qtile。

这种方式允许你用任意参数启动 Qtile，官方仓库的 qtile-examples 中有大量社区成员分享的~/.xsession示例可供参考。

方式三：无显示管理器，直接从 ~/.xinitrc 启动

如果机器上没有安装任何显示管理器，在~/.xinitrc末尾加入一行即可：

exec qtile start

使用exec让 Qtile 取代 shell 进程成为会话主进程，会话结束时进程自然退出。

方式四：崩溃自愈循环（特殊情况）

在非常特殊的场景下（例如 Qtile 在会话中频繁崩溃），官方建议用循环包裹启动命令，从而在崩溃后自动拉起、保住已运行的应用：

while true; do qtile done

qtile start 的可选参数（源码级）

从 libqtile/scripts/start.py 可以看到qtile start子命令支持以下参数，在自定义 session 或.xinitrc中组合使用：

此外，libqtile/scripts/main.py 为全局命令定义了通用参数-l/--log-level（DEBUG/INFO/WARNING/ERROR/CRITICAL，默认 WARNING）与-p/--log-path，以及-v/--version。同文件还注册了shell、top、run_cmd、cmd_obj、check、migrate、launch、repl、x11_identify_output等子命令模块，安装完成后可运行qtile --help查看完整命令树。

一个值得留意的细节：start.py中若指定的配置文件不存在，Qtile 会尝试把内置的默认配置模板复制到该路径（日志提示Copied default_config.py to ...），也就是说首次启动没有配置文件也不会白屏，它会先给你一份可运行的默认配置。

五、Wayland 后端

除了作为 X11 窗口管理器，Qtile 也可以作为 Wayland 合成器运行。仓库的 Wayland 后端实现在 libqtile/backend/wayland/，底层基于 wlroots 合成器库。

在 Wayland 依赖齐全的前提下，从 TTY 直接启动，或在已有的 X11 / Wayland 会话内以嵌套窗口方式启动：

qtile start -b wayland

从 libqtile/scripts/start.py 的make_qtile()可以确认后端选择逻辑：-b未指定时，通过libqtile.backend.detect_backend()自动探测；显式指定后端后若检测到缺少必需 Python 依赖，会列出缺失项并退出。-b的合法取值即libqtile.backend.CORES的键。

与 X11 场景类似，登录管理器也可以使用 Wayland 会话文件：在/usr/share/wayland-sessions下创建qtile-wayland.desktop。仓库自带的 resources/qtile-wayland.desktop 内容为：

[Desktop Entry] Name=Qtile (Wayland) Comment=Qtile Session Exec=qtile start -b wayland Type=Application Keywords=wm;tiling

Wayland 场景还有几点官方提醒：

• XWayland：Qtile 支持 XWayland 运行 X11-only 程序，前提是 wlroots 编译时带上了 XWayland 支持、且系统装有 XWayland；XWayland 会在首次需要时自动启动。已知问题可参考仓库 issue #3675（切换焦点后指针事件偶发传播到错误窗口）。
• 配置按后端区分：若希望同一份配置在不同后端下采用不同设置，可以像 docs/manual/wayland.rst 中那样读取当前后端名：

from libqtile import qtile if qtile.core.name == "x11": term = "urxvt" elif qtile.core.name == "wayland": term = "foot"

• Wayland 下 wlroots 的版本兼容性是重点（见第二节末尾的提醒），更多 Wayland 运行细节参见 docs/manual/wayland.rst。

六、udev 规则：让硬件 widget 获得写权限

Qtile 有多个 widget 负责管理硬件——LCD 背光、键盘背光、电池充电阈值——它们通过内核暴露的 sysfs 端点（/sys/class/...）工作。要让这些 widget 能写入对应文件，需要给 Qtile 授予写权限，官方为此在仓库中维护了一份 udev 规则文件 resources/99-qtile.rules。

从源码安装的用户应将其安装到/etc/udev/rules.d/，官方给出的安装命令：

# 把仓库内的 udev 规则文件复制到正确位置，让 udev 生效 cat ./resources/99-qtile.rules | sudo tee /etc/udev/rules.d/99-qtile.rules

这份规则文件做了三件事（对照 resources/99-qtile.rules 内容）：

1. LCD 背光：对SUBSYSTEM=="backlight"的设备，把/sys/class/backlight/%k/brightness开放为o+w（对应 widget 实现见 libqtile/widget/backlight.py）；
2. 键盘背光：对SUBSYSTEM=="leds"的设备，开放/sys/class/leds/%k/brightness；
3. 电池充电阈值：按 ACPI 驱动名（asus-wmi、dell-laptop、huawei-wmi、lg-laptop、msi-ec、samsung-galaxybook、system76_acpi、thinkpad_acpi、toshiba_acpi）在设备加载时开放charge_control_start_threshold/charge_control_end_threshold两个 sysfs 文件（对应 widget 实现见 libqtile/widget/battery.py）。

规则文件中的注释也透露了两个实战细节：一是充电阈值文件由驱动加载时创建而非电池被识别时创建，因此规则里把设备名硬编码为BAT0——如果你有多个电池，可以按相同格式手动追加 BAT1 的规则；二是这些驱动的清单（含 Linux 内核版本号）会在规则文件中定期更新核对，使用前建议先确认自己内核对应的驱动名。

七、安装后的验证与常见问题

安装完成后，可以按以下顺序自查：

1. 确认命令可用：qtile --version应输出版本号（由 libqtile/scripts/main.py 的-v分支提供）；
2. 确认后端依赖：直接执行qtile start，若缺失后端必需 Python 依赖，libqtile/scripts/start.py 的make_qtile()会打印缺失项并以退出码 1 结束；
3. 检查配置文件语法与内容：仓库内置了配置检查工具（libqtile/scripts/check.py），可用于校验你的~/.config/qtile/config.py；
4. 日志定位：通过-l DEBUG与-p <路径>打开更详细日志，方便排查启动失败（start.py启动时也会把 Qtile 版本与库路径写入日志）；
5. xsession 无效时：确认qtile.desktop位于/usr/share/xsessions且Exec=中的路径与which qtile一致（例如uv tool安装时入口通常位于~/.local/bin/qtile，resources/qtile.desktop 中写的是/usr/bin/qtile start，实际路径不一致时可改用不带绝对路径的qtile start或qtile-generic.desktop写法，见 resources/qtile-generic.desktop）。

小结

在 Ubuntu / Debian 上部署 Qtile 的完整链路可以归纳为四步：先判断发行版是否自带 Qtile 包（Debian >= 13 / Ubuntu >= 25.04 可直装）；再按后端选型补齐系统依赖（X11 需要xserver-xorg+xinit+python3-xcffib，Wayland 需要 wlroots 系列，两者共用libpangocairo-1.0-0）；随后用uv tool install安装 Qtile 本体与附加模块；最后选定启动方式（显示管理器菜单、自定义 xsession、.xinitrc或崩溃循环）并按需安装 resources/99-qtile.rules 释放硬件 widget 权限。全部过程都以本仓库的 docs/manual/install/ubuntu.rst 和 docs/manual/install/index.rst 为官方基准，源码与资源文件可在上文各链接处继续深入查阅。

• 桌面应用
• 操作系统