Hyprland on NixOS

Installing Hyprland on NixOS

You can install Hyprland from:

The Nixpkgs repository if you want a proper released version from Hyprland.
The Hyprland flake if you want the latest git commit available at the moment.
Flake-compat if you want to use the Hyprland flake, but don’t want to enable the use of flakes in your NixOS system.

configuration.nix

{
  programs.hyprland.enable = true;
}

This will use the Hyprland version included in the Nixpkgs release you’re using.

Note

If you don’t want to compile Hyprland yourself, make sure to enable Cachix.

In case you want to use the development version of Hyprland, you can add it like this:

flake.nix

{
  inputs.hyprland.url = "github:hyprwm/Hyprland";
  # ...

  outputs = {nixpkgs, ...} @ inputs: {
    nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit inputs; }; # this is the important part
      modules = [
        ./configuration.nix
      ];
    };
  };
}

Don’t forget to change the HOSTNAME to your actual hostname!

configuration.nix

{inputs, pkgs, ...}: {
  programs.hyprland = {
    enable = true;
    # set the flake package
    package = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
    # make sure to also set the portal package, so that they are in sync
    portalPackage = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
  };
}

If you start experiencing lag and FPS drops in games or programs like Blender on stable NixOS when using the Hyprland flake, it is most likely a mesa version mismatch between your system and Hyprland.

You can fix this issue by using mesa from Hyprland’s nixpkgs input:

configuration.nix

{pkgs, inputs, ...}: let
  pkgs-unstable = inputs.hyprland.inputs.nixpkgs.legacyPackages.${pkgs.stdenv.hostPlatform.system};
in {
  hardware.graphics = {
    package = pkgs-unstable.mesa;

    # if you also want 32-bit support (e.g., for Steam)
    enable32Bit = true;
    package32 = pkgs-unstable.pkgsi686Linux.mesa;
  };
}

For more details, see issue #5148.

This section is for using the Hyprland flake in a NixOS system without support for Nix flakes.

Note

If you don’t want to compile Hyprland yourself, make sure to enable Cachix.

configuration.nix

{pkgs, ...}: let
  flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";

  hyprland = (import flake-compat {
    src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/main.tar.gz";
  }).defaultNix;
in {
  programs.hyprland = {
    enable = true;
    # set the flake package
    package = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
    # make sure to also set the portal package, so that they are in sync
    portalPackage = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
  };
}

Configuring Hyprland on NixOS

There are two ways to configure Hyprland in Nix declaratively. You can still do it imperatively by simply putting your hyprland.lua in ~/.config/hypr/. While that is not the recommended method, it is still an option in which neither of the two ways described below are needed.

Hjem

Hjem is a simple, lightweight home management tool designed for linking files into your home directory and setting systemd units and environment variables at the user level. Configuring Hyprland with Hjem.

Home Manager

Home Manager is a popular home management tool for Nix that comes with a lot of bells and whistles. It allows for configuring a range of apps with pure Nix code, which may be desired. Configuring Hyprland with Home Manager.

For the adventurous, @spikespaz has made a Hyprland module that can be used in Home Manager and NixOS. It can be found here.

Last updated on October 12, 2026

Hyprland on any distro using Nix Configuring Hyprland with Hjem