Qtile

Qtile is a full-featured, hackable tiling window manager written and configured in Python. It's available both as an X11 window manager and also as a Wayland compositor.

Setup

To enable Qtile as your window manager, include this in your configuration:

services.xserver.windowManager.qtile.enable = true;

Note: The Qtile package creates desktop files for both X11 and Wayland, to use one of the backends choose the right session in your display manager.

Other options for Qtile can be declared within the services.xserver.windowManager.qtile attribute set.

Config File

The configuration file can be changed from its default location $XDG_CONFIG/qtile/config.py by setting the configFile attribute:

services.xserver.windowManager.qtile = {
  enable = true;
  configFile = ./my_qtile_config.py;
};

Home manager

If you are using home-manager, you can copy your qtile configuration by using the following:

xdg.configFile."qtile/config.py".source = ./my_qtile_config.py;

Or, if you have a directory containing multiple python files:

xdg.configFile."qtile" = {
  source = ./src;
  recursive = true;
};

Extra Packages

You may add extra packages in the Qtile python environment by putting them in the extraPackages list. For example:

services.xserver.windowManager.qtile = {
  enable = true;
  extraPackages = python3Packages: with python3Packages; [
    qtile-extras
    qtile-bonsai
  ];
};

Note: Some options may change over time, please refer to see all the options for the latest stable: search.nixos.org if you have any doubt

Wayland

Screen sharing & desktop portals

Screen sharing is supported with xdg desktop portals.

You need to have the following dependencies installed:

• xdg-desktop-portal (NEEDED)
• xdg-desktop-portal-wlr (NEEDED), the wlroots "portal"
• xdg-desktop-portal-gtk (RECOMMENDED) for proper GTK popup support

It's recommended to acquire them as shown:

xdg.portal = {
  enable = true;
  config.common.default = "*";
  extraPortals = with pkgs; [
    xdg-desktop-portal-wlr
    xdg-desktop-portal-gtk
  ];
};

Making apps use Wayland

Qtile has support for running X11 applications through XWayland. Whilst XWayland works, it is often not an optimal experience. Due to this we recommend to set some environment variables such that some applications use Wayland rather than X11.

Note: Note that in some systems these wayland backends can be experimental, so use these configurations with caution.

Environment variables:

environment.sessionVariables = {
  WLR_NO_HARDWARE_CURSORS = 1;
  NIXOS_OZONE_WL = 1;
  MOZ_ENABLE_WAYLAND = 1;
  GDK_BACKEND = "wayland,x11";
  ELECTRON_OZONE_PLATFORM_HINT = "auto";
  SDL_VIDEODRIVER = "wayland,x11";
};

Flakes

Qtile provides a Nix flake in its repository. This can be useful for:

• Running a bleeding-edge version of Qtile by specifying the flake input as the package.
• Hacking on Qtile using a Nix develop shell.

Note: Nix flakes are still an experimental NixOS feature, but they are already widely used. This section is intended for users who are already familiar with flakes.

To run a bleeding-edge version of Qtile with the flake, add the Qtile repository to your flake inputs and define the package. For example:

{
  description = "A very basic flake";
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";

    qtile-flake = {
      url = "github:qtile/qtile";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs =
    {
      self,
      nixpkgs,
      qtile-flake,
    }:
    {
      nixosConfigurations.demo = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";

        modules = [
          (
            {
              config,
              pkgs,
              lib,
              ...
            }:
            {
              services.xserver = {
                enable = true;
                windowManager.qtile = {
                  enable = true;
                  package = qtile-flake.packages.${pkgs.system}.default;
                };
              };

              # make qtile X11 the default session
              services.displayManager.defaultSession = lib.mkForce "qtile";

              # rest of your NixOS config
            }
          )
        ];
      };
    };
}

This flake can also be tested with a virtual machine:

sudo nixos-rebuild build-vm --flake .#demo

This gives you a script to run that runs Qemu to test your config. For this to work you have to set a user with a password.

To hack on Qtile with Nix, simply run nix develop in a checkout of the Qtile repository. In the development shell, there are a few useful commands:

• qtile-run-tests-wayland: Run all Wayland tests.
• qtile-run-tests-x11: Run all X11 tests.

Note: For a detailed walkthrough on setting up Qtile with flakes—from basic installation to package overrides, see Gurjaka's Qtile Flake Guide.

Credits

• Based on the official Qtile Documentation.
• Wayland details from Gist by Jwijenbergh.
• Flake config details from Gurjaka's Qtile Flake Guide.
• NixOS implementation details maintained by the community.