Installing on NixOS

Qtile is available in the NixOS repos. To set qtile as your window manager, include this in your configuration.nix file:

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

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

You may add extra packages in the qtile python environment by putting them in the extraPackages list.

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

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.

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

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

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

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;
};

Flake

Qtile also has a flake in the repository. This can be used for the following use cases:

• Run a bleeding edge version of Qtile by using it as an overlay in your flake config

• Hack on Qtile with a Nix develop shell

Note that flakes are an experimental NixOS feature but they are already widely used. This section is meant for users that already use flakes.

To run a bleeding edge version of Qtile with the flake, add the Qtile repo to your inputs and define the overlay. An example flake is the following:

{
   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 = [
         (_: { nixpkgs.overlays = [ qtile-flake.overlays.default ]; })
         ({ config, pkgs, lib, ...}: {
           services.xserver = {
             enable = true;
             windowManager.qtile.enable = true;
           };

           # 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 vm:

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

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 repo. In the development shell, there are a few useful things:

• qtile-run-tests-wayland: Run all Wayland tests

• qtile-run-tests-x11: Run all X11 tests