hyprland-wiki/pages/Nix/Hyprland on NixOS.md

title
Hyprland on NixOS

The NixOS module enables critical components needed to run Hyprland properly, such as: polkit, xdg-desktop-portal-hyprland, graphics drivers, fonts, dconf, xwayland, and adding a proper Desktop Entry to your Display Manager.

Make sure to check out the options of the NixOS module.

{{< callout >}}

• (Required) NixOS Module: enables critical components needed to run Hyprland properly
• (Optional) Home-manager module: lets you declaratively configure Hyprland

{{< /callout >}}

{{< tabs items="Nixpkgs,Flake Package, No Flakes (with flake-compat)" >}}

{{< tab "Nixpkgs" >}}

# configuration.nix

{pkgs, ...}: {
  programs.hyprland.enable = true;
}

This will use the Hyprland version that Nixpkgs has.

{{< /tab >}}

{{< tab "Flake package" >}}

{{< callout >}}

Please enable Cachix before using the flake package, so you don't have to compile Hyprland yourself.

{{< /callout >}}

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

# configuration.nix

{inputs, pkgs, ...}: {
  programs.hyprland = {
    enable = true;
    package = inputs.hyprland.packages.${pkgs.system}.hyprland;
  };
}

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

{{< callout >}}

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

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

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

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

For more details, see issue #5148.

{{< /callout >}}

{{< /tab >}}

{{< tab "Flake package, Nix stable" >}}

{{< callout >}}

Please enable Cachix before using the flake package, so you don't have to compile Hyprland yourself.

{{< /callout >}}

# configuration.nix

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

  hyprland-flake = (import flake-compat {
    src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
  }).defaultNix;
in {
  programs.hyprland = {
    enable = true;
    package = hyprland-flake.packages.${pkgs.system}.hyprland;
  };
}

{{< /tab >}}

{{< /tabs >}}

Fixing problems with themes

If your themes for mouse cursors, icons or windows don't load correctly, see the relevant section in Hyprland on Home Manager.