Skip to content
Nix
Configuring Hyprland with Home Manager

Configuring Hyprland with Home Manager

For a list of available options, check the Home Manager options.

Warning

Required:

  • NixOS Module: enables critical components needed to run Hyprland properly. Without this, you may have issues with missing session files in your Display Manager.

Optional:

  • Home Manager module: lets you configure Hyprland declaratively through Home Manager.
  • Configures Hyprland and adds it to your user’s $PATH, but does not make certain system-level changes such as adding a desktop session file for your display manager. This is handled by the NixOS module, once you enable it.

Installation

home.nix
{
  wayland.windowManager.hyprland.enable = true;
}

Usage

Once the module is enabled, you can use it to declaratively configure Hyprland. Here is an example config:

home.nix
{
  wayland.windowManager.hyprland.settings = {
    "$mod" = "SUPER";
    bind =
      [
        "$mod, F, exec, firefox"
        ", Print, exec, grimblast copy area"
      ]
      ++ (
        # workspaces
        # binds $mod + [shift +] {1..9} to [move to] workspace {1..9}
        builtins.concatLists (builtins.genList (i:
            let ws = i + 1;
            in [
              "$mod, code:1${toString i}, workspace, ${toString ws}"
              "$mod SHIFT, code:1${toString i}, movetoworkspace, ${toString ws}"
            ]
          )
          9)
      );
  };
}

Plugins

Hyprland plugins are managed differently on Nix than on other distros. The most notable change is that hyprpm is unsupported, but we have our own way of building and managing plugins.

Warning

Using plugins using the syntax below requires you to be using Hyprland through the Home Manager module or the upstream NixOS module.

Using plugins from Nixpkgs

In Nixpkgs, there are Hyprland plugins packaged for the Hyprland version in Nixpkgs. You can use them like this:

home.nix
{pkgs, ...}: {
  wayland.windowManager.hyprland.plugins = [
    pkgs.hyprlandPlugins.<plugin>
  ];
}

You can find which plugins are included using nix search nixpkgs#hyprlandPlugins ^.

hyprland-plugins

Official plugins made/maintained by vaxry.

To use these plugins, it is recommended to be already using the Hyprland flake, and not the Nixpkgs version.

First, add the flake to your flake inputs:

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

    hyprland-plugins = {
      url = "github:hyprwm/hyprland-plugins";
      inputs.hyprland.follows = "hyprland";
    };

    # ...
  }
}

The inputs.hyprland.follows line makes hyprland-plugins use the exact Hyprland revision you have locked. This means there aren’t any version mismatches, as long as you update both inputs at once.

The next step is adding the plugins to Hyprland:

home.nix
{inputs, pkgs, ...}: {
  wayland.windowManager.hyprland = {
    enable = true;

    plugins = [
      inputs.hyprland-plugins.packages.${pkgs.stdenv.hostPlatform.system}.<plugin>
    ];
  };
}

FAQ

Fixing problems with themes

If your themes for mouse cursors, icons or windows don’t load correctly, try setting them with home.pointerCursor and gtk.theme, which enable a bunch of compatibility options that should make the themes load in all situations.

Example configuration:

home.nix
{
  home.pointerCursor = {
    gtk.enable = true;
    # x11.enable = true;
    package = pkgs.bibata-cursors;
    name = "Bibata-Modern-Classic";
    size = 16;
  };

  gtk = {
    enable = true;

    theme = {
      package = pkgs.flat-remix-gtk;
      name = "Flat-Remix-GTK-Grey-Darkest";
    };

    iconTheme = {
      package = pkgs.adwaita-icon-theme;
      name = "Adwaita";
    };

    font = {
      name = "Sans";
      size = 11;
    };
  };
}

Using the Home-Manager module with NixOS

If you want to use the Home Manager module while using the Hyprland package you’ve defined in your NixOS module, you can now do so as long as you’re running Home Manager 5dc1c2e40410f7dabef3ba8bf4fdb3145eae3ceb or later by setting your package and portalPackage to null.

home.nix
{
  wayland.windowManager.hyprland = {
    enable = true;
    # set the Hyprland and XDPH packages to null to use the ones from the NixOS module
    package = null;
    portalPackage = null;
  };
}

Make sure not to mix versions of Hyprland and XDPH. If your NixOS config uses Hyprland from the flake, you should also use XDPH from the flake. If you set the Home Manager Hyprland module package to null, you should also set the XDPH package to null.

Programs don’t work in systemd services, but do on the terminal

This problem is related to systemd not importing the environment by default. It will not have knowledge of PATH, so it cannot run the commands in the services. This most commonly affects user-configured services such as hypridle or swayidle.

To fix it, add to your config:

home.nix
{
  wayland.windowManager.hyprland.systemd.variables = ["--all"];
}

This setting will produce the following entry in the Hyprland config:

hyprland.lua
hl.on("hyprland.start", function()
    hl.exec_cmd("dbus-update-activation-environment --systemd --all")
end)

Make sure to use the above command if you do not use the Home Manager module.

Last updated on
Configuring Hyprland with HjemCachix