Hyprland

Hyprland is an independent, extensible, bleeding-edge Wayland compositor written in modern C++ with an emphasis on looks. In addition, Hyprland also offers a number of first-party tools as well as a custom plugin system. The most up-to-date and complete documentation can be found in the project's own wiki.

Some of the most notable features of Hyprland are:

• Independent Wayland implementation: does not rely on wlroots or other external libraries and provides in-house alternatives to common components (screen locking, idle daemon, etc).
• Easy to configure: uses a live reloading config file in plain-text with useful defaults.
• Dynamic tiling support: supports both automatic tiling and floating mode with multiple layouts.
• Socket-based IPC: allows controlling the compositor at runtime via UNIX socket.
• Global shortcuts: permits setting global keybinds for any application (for apps such as OBS Studio).
• Window/Workspace Rules: set special behaviors for certain windows and workspaces.

Installation

NixOS 24.11 and Onwards

NixOS 24.11 added support for launching Hyprland with Universal Wayland Session Manager and is the recommended way to launch Hyprland as it neatly integrates with Systemd.

❄︎ configuration.nix

{
  programs.hyprland = {
    enable = true;
    withUWSM = true; # recommended for most users
    xwayland.enable = true; # Xwayland can be disabled.
  };
}

Copy

NixOS 24.05 and Below

❄︎ configuration.nix

{
  programs.hyprland = {
    enable = true;
    xwayland.enable = true; # Xwayland can be disabled.
  };
}

Copy

Nix on Non-NixOS Systems

If you use the Nix package manager on-top of a non-NixOS distribution then Hyprland can still be installed (albeit with less support than the NixOS module).

Firstly, enable flakes in your Nix installation. Then install Hyprland through nix profile:

nix profile install nixpkgs#hyprland

In order for Hyprland to find graphics drivers on a non-NixOS system, you will need to install nixGL:

nix profile install github:guibou/nixGL --impure

Now you can run Hyprland by invoking it with NixGL:

nixGL Hyprland

Hypr Ecosystem

You may also be interested in the Hypr project's collection of tools:

• hyprlock: Hyprland's GPU-accelerated screen locking utility.
• hypridle: Hyprland's idle daemon.
• hyprpaper: Hyprland's wallpaper utility.
• hyprsunset: Application to enable a blue-light filter on Hyprland.
• hyprpicker: Wayland color picker that does not suck.
• hyprpolkitagent: Polkit authentication agent written in QT/QML.

All official Hypr* programs are listed in the project's wiki page along with documentation.

Hyprland Flake

⚠︎

Warning: Installing Hyprland through a Nix flake will require the system to recompile Hyprland and all of its dependencies each time it updates. To avoid this, setup Hyprland's Cachix settings before adding Hyprland as a flake input.

If you wish to run a development version of Hyprland, you can easily do so by adding its flake to your flake inputs as demonstrated below:

❄︎ flake.nix

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

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

Copy

❄︎ 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;
  };
}

Copy

If you experience performance drops in video games or graphics tools like Blender on stable NixOS, then it's likely a Mesa version mismatch with Hyprland and the rest of your system. This can be fixed by substituting the system's mesa package with Hyprland's own.

❄︎ configuration.nix

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

Copy

Cachix

If you use the Hyprland flake, you'll have to rebuild Hyprland as well as any of its dependencies (mesa, ffmpeg, etc). To avoid this, use the Cachix cache provided by Hyprland to supplement any dependency not supplied by Hydra. Note that the setting has to be enabled before using the Hyprland flake package (meaning you should rebuild at least once before adding the flake input).

❄︎ configuration.nix

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

Copy

Display Manager Support

By default, Hyprland does not come with a display manager and does not advertise support for one. Though one can start hyprland directly from tty with Hyprland or with uwsm start select, some display managers packaged in NixOS are compatible including but may not be limited to:

• SDDM
• GDM (works but crashes Hyprland on first launch)
• greetd (especially with ReGreet)
• ly (not recommended but works)

Configuration

On first run, Hyprland will create a configuration file with autogenerated defauts in $XDG_CONFIG_HOME/hypr/hyprland.conf if it does not exist. An example configuration can be found in the project's git repository.

Using Home Manager

Home Manager allows for declarative configuration of Hyprland using Nix syntax.

❄︎ /etc/nixos/home.nix or ~/.config/home-manager/home.nix

{
  wayland.windowManager.hyprland.settings = {
    decoration = {
      shadow_offset = "0 5";
      "col.shadow" = "rgba(00000099)";
    };

    "$mod" = "SUPER";

    bindm = [
      # mouse movements
      "$mod, mouse:272, movewindow"
      "$mod, mouse:273, resizewindow"
      "$mod ALT, mouse:272, resizewindow"
    ];
  };
  # ...
}

Copy

Plugin Support

Hyprland boasts a growing plugin ecosystem that extends the functionality of the compositor such as adding support for window decorations or a GNOME-like workspaces design. However, hyprpm is unsupported on NixOS due to the way Hyprland is built.

The Home Manager module for Hyprland should be used instead:

❄︎ /etc/nixos/home.nix or ~/.config/home-manager/home.nix

{
  wayland.windowManager.hyprland.plugins = [
    pkgs.hyprlandPlugins.PLUGIN_NAME
  ];
}

Copy

hyprland-plugins

hyprland-plugins is a repository of first-party plugins. If you wish to use these plugins then it's recommended to use the Hyprland flake instead of the Nixpkgs version as well as using the Home Manager module.

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"; # Prevents version mismatch.
    };

    # ...
  }
}

Copy

And then add the plugin using the hyprland-plugins input:

❄︎ /etc/nixos/home.nix or ~/.config/home-manager/home.nix

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

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

Copy

List of plugins

Troubleshooting

Swaylock

If swaylock cannot be unlocked with the correct password: security.pam.services.swaylock = {};

See also

• Hyprland Website
• The official documentation
• Hyprland Github Page
• Community-maintained list of tools, plugins and extensions