NixOS Wiki

Hyprland: Difference between revisions

← Older editNewer edit →
Visual
Unabomberlive (talk | contribs)
trusted
1,173 edits
m Proper way to write in XDG config directory
Normalcea (talk | contribs)
12 edits
This is a near complete rewrite of the wiki entry that's mostly adapted from the https://wiki.hyprland.org/Nix/ wiki page on the project's official site with necessary modifications.
Line 1: Line 1:
{{Expansion|Incomplete (reason: (Adding incrementally through testing and verification.))}}
[https://hyprland.org/ 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 [https://wiki.hyprland.org/ wiki].  
{{Warning|At the moment, [https://wiki.hyprland.org/Nix/ upstream] provides a better documentation regarding installation and configuration. Please refer to it instead.}}


[https://hyprland.org/ Hyprland] is a wlroots-based tiling [[Wayland]] compositor written in C++. Noteworthy features of Hyprland include dynamic tiling, tabbed windows, a clean and readable C++ code-base, and a custom renderer that provides window animations, rounded corners, and Dual-Kawase Blur on transparent windows. General usage and configuration is thoroughly documented at [https://wiki.hyprland.org/ Hyprland 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 ==
== Installation ==
{{Note|The respective modules should already take care of the majority of mentioned items in this list. }}
=== NixOS 24.11 and Onwards ===
To run Hyprland properly you need to enables critical components, such as:
NixOS 24.11 added support for launching Hyprland with [https://github.com/Vladimir-csp/uwsm Universal Wayland Session Manager] and is the recommended way to launch Hyprland as it neatly integrates with [[Systemd]].
* [[polkit]]
* xdg-desktop-portal-hyprland
* graphics drivers : [[Nvidia]], [[AMD_GPU|AMD]]
* [[fonts]]
* [[dconf]]
* [[xwayland]]
* [[display manager]]
If you use [[gdm]] or [[ldm]]: add a proper [[Desktop Entry]] to your [[display manager]].


=== Using [[NixOS]] ===
{{file|configuration.nix|nix|<nowiki>
{pkgs, ...}:
{
  programs.hyprland = {
    enable = true;
    withUWSM = true; # recommended for most users
    xwayland.enable = true; # Xwayland can be disabled.
  };
}
</nowiki>}}
 
=== NixOS 24.05 and Below ===


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{{file|configuration.nix|nix|<nowiki>
{pkgs, ...}:  
{pkgs, ...}:
{
{
   programs.hyprland = {
   programs.hyprland = {
    # Install the packages from nixpkgs
     enable = true;
     enable = true;
    # Whether to enable XWayland
     xwayland.enable = true; # Xwayland can be disabled.
     xwayland.enable = true;
   };
   };
  # ...
}
}
</nowiki>}}
</nowiki>}}
[https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=hyprland See all modules for NixOS]


=== Using [[Home Manager]] ===
=== 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 [https://wiki.nixos.org/wiki/Flakes#Other_Distros,_without_Home-Manager flakes] in your Nix installation. Then install Hyprland through <code>nix profile</code>:
 
<syntaxHighlight lang=text>
nix profile install nixpkgs#hyprland
</syntaxHighlight>
 
In order for Hyprland to find graphics drivers on a non-NixOS system, you will need to install [[nixGL]]:
 
<syntaxHighlight lang=text>
nix profile install github:guibou/nixGL --impure
</syntaxHighlight>
 
Now you can run Hyprland by invoking it with NixGL:
 
<syntaxHighlight lang=text>
nixGL Hyprland
</syntaxHighlight>
 
==== 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 [https://wiki.hyprland.org/Hypr-Ecosystem/ 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#Cachix|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:


{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{{file|flake.nix|nix|<nowiki>
{config, pkgs, ... }:
{
{
   wayland.windowManager.hyprland = {
   inputs.hyprland.url = "github:hyprwm/Hyprland";
     # Whether to enable Hyprland wayland compositor
  # ...
 
  outputs = {nixpkgs, ...} @ inputs: {
     nixosConfigurations.YOUR_HOSTNAME = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit inputs; }; # this is the important part
      modules = [
        ./configuration.nix
        # ...
      ];
    };
  };
}
</nowiki>}}
 
{{file|configuration.nix|nix|<nowiki>
{inputs, pkgs, ...}: {
  programs.hyprland = {
     enable = true;
     enable = true;
     # The hyprland package to use
     # set the flake package
     package = pkgs.hyprland;
     package = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
     # Whether to enable XWayland
     # make sure to also set the portal package, so that they are in sync
     xwayland.enable = true;
     portalPackage = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
  };
}
</nowiki>}}
 
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.
 
{{file|configuration.nix|nix|<nowiki>
{pkgs, inputs, ...}: let
  pkgs-unstable = inputs.hyprland.inputs.nixpkgs.legacyPackages.${pkgs.stdenv.hostPlatform.system};
in {
  hardware.opengl = {
    package = pkgs-unstable.mesa.drivers;


     # Optional
     # if you also want 32-bit support (e.g for Steam)
     # Whether to enable hyprland-session.target on hyprland startup
     driSupport32Bit = true;
     systemd.enable = true;
    package32 = pkgs-unstable.pkgsi686Linux.mesa.drivers;
  };
}
</nowiki>}}
 
==== 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 [https://app.cachix.org/cache/hyprland 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).
 
{{file|configuration.nix|nix|<nowiki>
{
  nix.settings = {
    substituters = ["https://hyprland.cachix.org"];
     trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
   };
   };
  # ...
}
}
</nowiki>}}
</nowiki>}}
[https://mipmip.github.io/home-manager-option-search/?query=hyprland See all modules for Home Manager]


=== Using [[Flake]] ===
=== Display Manager Support ===
By default, Hyprland does not come with a [https://wiki.nixos.org/wiki/Wayland#Display_Managers display manager] and does not advertise support for one. Though one can start hyprland directly from tty with <code>Hyprland</code> or with <code>uwsm start select</code>, 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 ==
== Configuration ==
On first run, Hyprland will create a configuration file with autogenerated defauts in <code>$XDG_CONFIG_HOME/hypr/hyprland.conf</code> if it does not exist. An example configuration can be found in the [https://github.com/hyprwm/Hyprland/blob/main/example/hyprland.conf project's git repository].


=== Using [[Home Manager]] ===
=== Using [[Home Manager]] ===
Home Manager allows for  declarative configuration of Hyprland using Nix syntax.


You have two options for configuring the settings:
1. Compose the configuration using Nix syntax:
{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{config, pkgs, ... }:
{
{
   wayland.windowManager.hyprland.settings = {
   wayland.windowManager.hyprland.settings = {
Line 85: Line 164:
</nowiki>}}
</nowiki>}}


2. You can also use Hyprland's syntax to write the file like this: :
== 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:
 
{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{config, pkgs, ... }:
{
{
   xdg.configFile."hypr/hyprland.conf".text = ''
   wayland.windowManager.hyprland.plugins = [
     decoration {
     pkgs.hyprlandPlugins.PLUGIN_NAME
      shadow_offset = 0 5
   ];
      col.shadow = rgba(00000099)
    }
 
    $mod = SUPER
 
    bindm = $mod, mouse:272, movewindow
    bindm = $mod, mouse:273, resizewindow
    bindm = $mod ALT, mouse:272, resizewindow
   '';
  # ...
}
}
</nowiki>}}
</nowiki>}}


== Plugin ==
=== hyprland-plugins ===
You need use flake for her, example:
[https://github.com/hyprwm/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.


put this in your flake.nix
Add the flake to your flake inputs:
{{file|/etc/nixos/flake.nix or ~/.config/home-manager/flake.nix|nix|<nowiki>
{{file|flake.nix|nix|<nowiki>
{
{
   inputs = {
   inputs = {
    # ...
     hyprland.url = "github:hyprwm/Hyprland";
     hyprland.url = "github:hyprwm/Hyprland";
     plugin_name = {
 
        url = "github:maintener/plugin_name";
     hyprland-plugins = {
        inputs.hyprland.follows = "hyprland"; # IMPORTANT
      url = "github:hyprwm/hyprland-plugins";
      inputs.hyprland.follows = "hyprland"; # Prevents version mismatch.
     };
     };
   };
 
    # ...
   }
}
}
</nowiki>}}
</nowiki>}}


then, inside your home-manager module:
And then add the plugin using the hyprland-plugins input:
{{file|/etc/nixos/flake.nix or ~/.config/home-manager/flake.nix|nix|<nowiki>
 
{
{{file|/etc/nixos/home.nix or ~/.config/home-manager/home.nix|nix|<nowiki>
{inputs, pkgs, ...}: {
   wayland.windowManager.hyprland = {
   wayland.windowManager.hyprland = {
    enable = true;
     plugins = [
     plugins = [
        inputs.plugin_name.packages.${pkgs.system}.default
      inputs.hyprland-plugins.packages.${pkgs.stdenv.hostPlatform.system}.PLUGIN_NAME
     ];
     ];
   };
   };
}
}
</nowiki>}}
</nowiki>}}
[https://github.com/hyprland-community/awesome-hyprland#plugins List of plugins]
[https://github.com/hyprland-community/awesome-hyprland#plugins List of plugins]




== Usage ==


== Troubleshooting ==
== Troubleshooting ==
=== Swaylock ===
=== Swaylock ===
If swaylock cannot be unlocked with the correct password:
If swaylock cannot be unlocked with the correct password:
<code>  
<code>
security.pam.services.swaylock = {};  
security.pam.services.swaylock = {};
</code>
</code>


Retrieved from "https://wiki.nixos.org/wiki/Hyprland"