hyprland-wiki/pages/Nix/Plugins.md

title
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 plugins.

{{< callout type=warning >}}

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

{{< /callout >}}

Using plugins from Nixpkgs

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

{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 that you are already using the Hyprland flake, and not the Nixpkgs version.

First, add the flake to your flake inputs:

{
  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:

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

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

Building plugins with Nix

The plugins inside Nixpkgs, as well as the ones in hyprland-plugins, are built using a general function, mkHyprlandPlugin. Any plugin can be made to work with it. The general usage is presented below, exemplified through hy3's derivation:

{
  lib,
  fetchFromGitHub,
  cmake,
  hyprland,
  hyprlandPlugins,
}:
hyprlandPlugins.mkHyprlandPlugin hyprland {
  pluginName = "hy3";
  version = "0.39.1";

  src = fetchFromGitHub {
    owner = "outfoxxed";
    repo = "hy3";
    rev = "hl0.39.1";
    hash = "sha256-PqVld+oFziSt7VZTNBomPyboaMEAIkerPQFwNJL/Wjw=";
  };

  # any nativeBuildInputs required for the plugin
  nativeBuildInputs = [cmake];

  # set any buildInputs that are not already included in Hyprland
  # by default, Hyprland and its dependencies are included
  buildInputs = [];

  meta = {
    homepage = "https://github.com/outfoxxed/hy3";
    description = "Hyprland plugin for an i3 / sway like manual tiling layout";
    license = lib.licenses.gpl3;
    platforms = lib.platforms.linux;
  };
}

{pkgs, ...}: {
  wayland.windowManager.hyprland.plugins = [
    (pkgs.callPackage ./plugin.nix {})
  ];
}

In a similar manner to stdenv.mkDerivation, mkHyprlandPlugin takes an attrset with mostly the same options as mkDerivation, as it is essentially a wrapper around it.

The exception is that it also takes a hyprland package before the attrset, in case you want to build with a different package than the one in Nixpkgs.

This is not always the best way to build for a different version, and it is recommended that you use an overlay to apply your desired Hyprland package in Nixpkgs instead.