hyprland-wiki/pages/Nix/_index.md

Table of contents

{{< toc format=html >}}

{{< hint type=warning >}} Hyprland is NOT supported on NixOS stable. It may (not) compile or work as intended. Please use the flake. {{< /hint >}}

Install and configure Hyprland on NixOS

First of all, it is a good idea to set up Cachix before enabling any of the modules/installing Hyprland.

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

Do note that the Nixpkgs Hyprland package is not actively maintained, and may be outdated. As such, installation using the Flake is recommended.

With flakes

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hyprland.url = "github:hyprwm/Hyprland";
  };

  outputs = {self, nixpkgs, hyprland, ...}: {
    nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
      # ...
      modules = [
        hyprland.nixosModules.default
        {programs.hyprland.enable = true;}
        # ...
      ];
    };
  };

Don't forget to replace HOSTNAME with your hostname!

Without flakes

{{< hint >}} If you're using Hyprland through an overlay, set programs.hyprland.package = pkgs.hyprland;. {{< /hint >}}

# configuration.nix
{config, 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/master.tar.gz";
  }).defaultNix;
in {
  imports = [
    hyprland.nixosModules.default
  ];

  programs.hyprland = {
    enable = true;
    package = hyprland.packages.${pkgs.system}.default;
  };
}

Install and configure through Home Manager

You can use the Home Manager module by adding it to your configuration:

With flakes

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    home-manager = {
      url = "github:nix-community/home-manager";
      inputs.nixpkgs.follows = "nixpkgs";
    };

    hyprland.url = "github:hyprwm/Hyprland";
  };

  outputs = {self, nixpkgs, home-manager, hyprland, ...}: {
    homeConfigurations."user@hostname" = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;

      modules = [
        hyprland.homeManagerModules.default
        {wayland.windowManager.hyprland.enable = true;}
        # ...
      ];
    };
  };

Don't forget to replace user@hostname with your username and hostname!

Without flakes

# home config
{config, pkgs, inputs, ...}: 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/master.tar.gz";
  }).defaultNix;
in {
  imports = [
    hyprland.homeManagerModules.default
  ];

  wayland.windowManager.hyprland.enable = true;
  # ...
}

For a list of available options, check the module file.

Modules mix'n'match

• If you're on NixOS and also use HM it's a good idea to use Hyprland modules for both. Make sure the package options are the same for both modules.

• If you don't plan on using the NixOS module, but want to use the HM module, you will have to enable all the options the NixOS module enables.

• If you don't plan on using any module, manually enable whatever options the modules set.

Non-NixOS install

With flakes

First, enable flakes.

Once you have flakes working, install Hyprland through nix profile:

nix profile install github:hyprwm/Hyprland

Since you're using Hyprland outside of NixOS, it won't be able to find graphics drivers. To get around that, you can use nixGL.

First, install it, in the same manner you installed Hyprland:

nix profile install github:guibou/nixGL --impure

Impure is needed due to nixGL's reliance on hardware information.

From now on, you can run Hyprland by invoking it with nixGL

nixGL Hyprland

or by creating a wrapper script that runs the above command inside.

Upgrading

In order to upgrade all your packages, you can run

nix profile upgrade '.*'

Check the nix profile command documentation for other upgrade options.

XWayland

XWayland is enabled by default in the Nix package. You can disable it either in the package itself, or through the module options.

Package

(inputs.hyprland.packages.${pkgs.default}.default.override {
  enableXWayland = false;
})

HM module

wayland.windowManager.hyprland = {
  enable = true;
  xwayland.enable = false;
}

NixOS module

programs.hyprland = {
  enable = true;
  xwayland.enable = false;
}

HiDPI

By default, the Nix package includes a patched wlroots that can render HiDPI XWayland windows.

In order to enable the functionality, you have to add:

exec-once=xprop -root -f _XWAYLAND_GLOBAL_OUTPUT_SCALE 32c -set _XWAYLAND_GLOBAL_OUTPUT_SCALE 2

This will make XWayland programs look as if they were unscaled. To fix this, you have to export different environment variables to make the specific toolkits render at the proper scaling. For example

export GDK_SCALE=2
export XCURSOR_SIZE=32

{{< hint >}} The GDK_SCALE variable won't conflict with wayland-native GTK programs. {{< /hint >}}

Usually, there's no reason to disable this functionality, as it won't affect people who don't have HiDPI screens.

If you do insist on disabling it though (e.g. for adding your own patches to wlroots), you can do so by either using the hyprland-no-hidpi package, or by passing the hidpiXWayland = false; flag, the same way as disabling XWayland

Cachix

Hyprland often needs dependencies which aren't yet cached in cache.nixos.org. Instead of requiring you to build those dependencies (which may include mesa, ffmpeg, etc), we provide a Cachix cache that you can add to your Nix substituters.

The Hyprland Cachix exists to cache the hyprland packages and any dependencies not found in cache.nixos.org.

{{< hint >}} In order for Nix to take advantage of the cache, it has to be enabled before enabling the Hyprland module(s) or adding the package. {{< /hint >}}

{{< hint type=important >}} Overriding Hyprland's nixpkgs input (inputs.hyprland.inputs.nixpkgs.follows = "nixpkgs";) will make the cache useless, since you're building from a different Nixpkgs commit. {{< /hint >}}

# configuration.nix
{
  nix.settings = {
    substituters = ["https://hyprland.cachix.org"];
    trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
  };
}

Overrides

You can override the package through .override or .overrideAttrs. This is easily achievable through NixOS or Home Manager.

If you're using Nix (and not NixOS or Home Manager) and you want to override, you can do it like this

$ nix repl
nix-repl> :lf "github:hyprwm/Hyprland"
nix-repl> :bl outputs.packages.x86_64-linux.hyprland.override {nvidiaPatches = true;} # option = value

Then you can run Hyprland from the built path.