marceloeatworld/hyprland-ai-skill
hyprland
FlaggedThis skill should be used when the user asks about "Hyprland configuration", "hyprland.lua", "hyprland.conf", "Hyprland Lua config", "hyprctl", "Hyprland keybinds", "Hyprland window rules", "Hyprland monitors", "Hyprland dispatchers", "Hyprland animations", "Hyprland workspaces", "Hyprland IPC", "Hyprland plugins", "hyprlock", "hypridle", "hyprpaper", "hyprcursor", "hyprpicker", "hyprsunset", "xdg-desktop-portal-hyprland", "Hyprland on NixOS", "Hyprland Home Manager", "Hyprland layouts", "Hyprland dwindle", "Hyprland master layout", "Hyprland FAQ", "Hyprland performance", "Hyprland Nvidia", "Hyprland screen sharing", "Hyprland special workspace", "Hyprland smart gaps", "Hyprland multi-monitor", "Hyprland tearing", or any topic related to configuring, troubleshooting, or extending the Hyprland Wayland compositor and its ecosystem tools.
references/nix.md
View on GitHub<!-- source: https://wiki.hypr.land/nix -->
<!-- wiki commit: 41c7222 (2026-11-20 18:16:21 +0100) -->
<!-- auto-generated by scripts/generate-references.sh - DO NOT EDIT MANUALLY -->
# Hyprland on NixOS / Nix Reference
---
weight: 80
title: Nix
---
## Installing Hyprland on NixOS
If you are already on NixOS or plan on writing a config for it, see [Hyprland on NixOS](./installing-hyprland-on-nixos).
## Using Hyprland on any other distro with the Nix package manager
If you want to use Hyprland but you are on a distro without official support, you can install just Nix itself --- the package manager.
This will provide a better experience and be guaranteed to be up to date, especially on point-release distros.
It is also simpler than compiling from source and allows you to use the binary cache, which is important for lower-spec devices.
See [this page](./hyprland-on-any-distro-using-nix).
## Advanced
The section [Advanced](./advanced) contains tweaks such as options, overrides, overlays, building plugins with Nix, ...
## Contributing and debugging Hyprland
See this page if you want to debug some issue or contribute code to Hyprland: [Contributing and debugging](./contributing-and-debugging).
---
---
weight: 20
title: Hyprland on NixOS
---
## Installing Hyprland on NixOS
You can install Hyprland from:
- the Hyprland flake if you want the latest git commit available at the moment;
- flake-compat if you want to use the Hyprland flake, but don't want to enable the use of flakes in your NixOS system;
- the Nixpkgs repository.
{{< tabs >}}
{{< tab name="The Hyprland flake" >}}
> [!NOTE]
> If you don't want to compile Hyprland yourself, make sure to enable [Cachix](../cachix).
In case you want to use the _development_ version of Hyprland, you can add it like this:
```nix {filename="flake.nix"}
{
inputs.hyprland.url = "github:hyprwm/Hyprland";
# ...
outputs = {nixpkgs, ...} @ inputs: {
nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs; }; # this is the important part
modules = [
./configuration.nix
];
};
};
}
```
Don't forget to change the `HOSTNAME` to your actual hostname!
```nix {filename="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;
};
}
```
If you start experiencing lag and FPS drops in games or programs like Blender on **stable** NixOS when using the Hyprland flake, it is most likely a `mesa` version mismatch between your system and Hyprland.
You can fix this issue by using `mesa` from Hyprland's `nixpkgs` input:
```nix {filename="configuration.nix"}
{pkgs, inputs, ...}: let
pkgs-unstable = inputs.hyprland.inputs.nixpkgs.legacyPackages.${pkgs.stdenv.hostPlatform.system};
in {
hardware.graphics = {
package = pkgs-unstable.mesa;
# if you also want 32-bit support (e.g., for Steam)
enable32Bit = true;
package32 = pkgs-unstable.pkgsi686Linux.mesa;
};
}
```
For more details, see [issue #5148](https://github.com/hyprwm/Hyprland/issues/5148).
{{< /tab >}}
{{< tab name="flake-compat" >}}
This section is for using the Hyprland flake in a NixOS system without support for Nix flakes.
> [!NOTE]
> If you don't want to compile Hyprland yourself, make sure to enable [Cachix](../cachix).
```nix {filename="configuration.nix"}
{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/main.tar.gz";
}).defaultNix;
in {
programs.hyprland = {
enable = true;
# set the flake package
package = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
# make sure to also set the portal package, so that they are in sync
portalPackage = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
};
}
```
{{< /tab >}}
{{< tab name="Nixpkgs repository" >}}
```nix {filename="configuration.nix"}
{
programs.hyprland.enable = true;
}
```
This will use the Hyprland version included in the Nixpkgs release you're using.
{{< /tab >}}
{{< /tabs >}}
## Configuring Hyprland on NixOS
There are two ways to configure Hyprland in Nix declaratively.
You can still do it imperatively by simply putting your `hyprland.lua` in `~/.config/hypr/`.
While that is not the recommended method, it is still an option in which neither of the two ways described below are needed.
### Hjem
Hjem is a simple, lightweight home management tool designed for linking files into your home directory and setting systemd units and environment variables at the user level.
[Configuring Hyprland with Hjem](../configuring-hyprland-with-hjem).
### Home Manager
Home Manager is a popular home management tool for Nix that comes with a lot of bells and whistles.
It allows for configuring a range of apps with pure Nix code, which may be desired.
[Configuring Hyprland with Home Manager](../configuring-hyprland-with-home-manager).
For the adventurous, [@spikespaz](https://github.com/spikespaz) has made a Hyprland module that can be used in Home Manager and NixOS.
It can be found [here](https://github.com/hyprland-community/hyprnix).
---
---
weight: 40
title: Configuring Hyprland with Home Manager
---
For a list of available options, check the [Home Manager options](https://nix-community.github.io/home-manager/options.xhtml#opt-wayland.windowManager.hyprland.enable).
> [!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
{{< tabs >}}
{{< tab name="Home Manager" >}}
```nix {filename="home.nix"}
{
wayland.windowManager.hyprland.enable = true;
}
```
{{< /tab >}}
{{< tab name="The Hyprland flake" >}}
The following snippet of code tries to show how to bring the Hyprland flake from the flake input and use its packages with Home Manager.
Feel free to make any adjustment for your setup.
Don't forget to replace `user@hostname` with your username and hostname!
```nix {filename="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 = {nixpkgs, home-manager, hyprland, ...}: {
homeConfigurations."user@hostname" = home-manager.lib.homeManagerConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
{
wayland.windowManager.hyprland = {
enable = true;
# set the flake package
package = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
portalPackage = inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
};
}
# ...
];
};
};
}
```
{{< /tab >}}
{{< tab name="flake-compat" >}}
This section is for using the Hyprland flake in a NixOS system without support for Nix flakes.
> [!WARNING]
> The flake module is merely an extension to the Home Manager downstream module.
> It is mainly used as a staging area for new options, so unless you're a tester, you should use the downstream Home Manager module.
The following snippet of code tries to show how to bring the Hyprland flake from the flake input and use the package in the Home Manager option.
Feel free to make any adjustment for your setup.
```nix {filename="home.nix"}
{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/main.tar.gz";
}).defaultNix;
in {
wayland.windowManager.hyprland = {
enable = true;
# set the flake package
package = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland;
portalPackage = hyprland.packages.${pkgs.stdenv.hostPlatform.system}.xdg-desktop-portal-hyprland;
}
}
```
{{< /tab >}}
{{< /tabs >}}
## Usage
Once the module is enabled, you can use it to declaratively configure Hyprland.
Here is an example config:
<!-- TODO: this is outdated, needs rewrite -->
```nix {filename="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](../configuring-hyprland-with-home-manager) or the [upstream NixOS module](../installing-hyprland-on-nixos).
## Using plugins from Nixpkgs
In Nixpkgs, there are Hyprland plugins packaged for the Hyprland version in Nixpkgs.
You can use them like this:
```nix {filename="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:
```nix {filename="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:
```nix {filename="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:
```nix {filename="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`](https://github.com/nix-community/home-manager/commit/5dc1c2e40410f7dabef3ba8bf4fdb3145eae3ceb) or later by setting your `package` and `portalPackage` to `null`.
```nix {filename="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:
```nix {filename="home.nix"}
{
wayland.windowManager.hyprland.systemd.variables = ["--all"];
}
```
This setting will produce the following entry in the Hyprland config:
```lua {filename="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.
---
---
weight: 30
title: Configuring Hyprland with Hjem
---
Hjem ("home" in Danish) is a module system that implements a simple and streamlined way to manage files in your `$HOME`, such as but not limited to files in your `~/.config`.
Hjem aims to serve as an alternative and easy-to-grasp utility for managing your `$HOME` purely and safely.
You can read the wonderful [Hjem documentation](https://hjem.feel-co.org/) to learn how to install and use it.
## Writing your hyprland.lua directly inside your Nix config
Here follows an example of how to write your `hyprland.lua` contents directly inside your Nix config using Hjem, which will allow you to use Nix string interpolation.
```lua {filename="hyprland.nix"}
{
hjem.users.youruser.xdg.config.files."hypr/hyprland.lua".text = /* lua */ ''
# Your hyprland.lua content goes here.
# You can use string interpolation for Nix to evaluate variables at build time.
# A snippet of a hyprland.lua config using string interpolation for some variables to be interpreted by Nix:
local monitor1 = "${config.custom.host.monitors."1"}"
local monitor2 = "${config.custom.host.monitors."2"}"
hl.monitor({
output = monitor2,
${lib.optionalString (hostName == "deck") "transform = 3"}
})
''
}
```
## Sourcing a hyprland.lua file at your Nix config
Instead of writing your `hyprland.lua` contents directly inside your Nix config, you also have the possibility of sourcing an already existing `hyprland.lua` file using Hjem, to link it into its place at `~/.config/hypr/`.
If using version control, make sure this `hyprland.lua` is in the same repository as your config.
However, you can't use Nix string interpolation this way.
```nix {filename="hyprland.nix"}
{
hjem.users.youruser.xdg.config.files."hypr/hyprland.lua".source = ./relative/path/to/file;
}
```
If you have already split your `hyprland.lua` into multiple files, you may source them the same way.
```nix {filename="hyprland.nix"}
{
hjem.users.youruser.xdg.config.files = {
"hypr/hyprland.lua".source = ./relative/path/to/hyprland.lua;
"hypr/rules.lua".source = ./relative/path/to/rules.lua;
"hypr/keybinds.lua".source = ./relative/path/to/keybinds.lua;
"hypr/animations.lua".source = ./relative/path/to/animations.lua;
};
}
```
For multi-file examples such as the one above, you may prefer to just link a whole directory.
While you can do that in Hjem, it comes with the caveat that it makes the whole directory read-only.
This can be undesirable as it blocks any new files from being made inside that directory, breaking certain apps.
If you would like to recursively link only the files from inside a directory, [FindFiles](#findfiles) will interest you.
## Hjem-impure
Your `hyprland.lua` file will most likely change frequently.
What if you want to try a new change in your Hyprland config without having to build switch your NixOS config?
After `hyprland.lua` is deployed by Hjem, it will write a link into `~/.config/hyprland.lua` from the Nix store.
This file is read-only by default, but we can easily get to rewrite it by using a tool called [`hjem-impure`](https://github.com/Rexcrazy804/hjem-impure).
Executing `hjem-impure` replaces every Hjem symlink with writable normal files and directories.
So after that, you can write into your `~/.config/hyprland.lua` file deployed by Hjem.
**This enables experimentation.**
What this means is that, after a NixOS build switch or after a system reboot, the changes that you made in `~/.config/hyprland.lua` **will be gone**.
So after you are happy with your changes, write them into your Nix config for them to be persisted.
## FindFiles
[FindFiles](https://github.com/Michael-C-Buckley/findFiles.nix) is a small Nix library that allows you to easily link whole directories from inside your configuration to the correct locations.
It combines with a home management tool such as Hjem, which manages the linking itself, but it recursively finds files inside a directory.
This way you are linking every file in a folder instead of the folder itself all with one line of code.
Normal directory linking with Hjem links the whole folder, meaning the folder becomes read-only.
It works well with Hjem-impure if you desire hot reloading.
An example of what you can do with FindFiles:
- Have a config directory inside your repository and have it overlay on your entire `~/.config`.
- Have a Hyprland directory that gets auto-placed at `~/.config/hypr/`.
---
---
weight: 10
title: Hyprland on any distro using Nix
---
Using Hyprland via the Nix package manager on distros that aren't NixOS is very simple.
## Installing Nix
The first step is to install Nix itself.
There are two primary ways to install the Nix package manager:
{{% tabs %}}
{{% tab name="From Upstream" %}}
Nix upstream recommends the multi-user installer, which can be found in their [official documentation](https://nixos.org/manual/nix/stable/installation/index.html).
It operates outside of your package manager's control and modifies your shell profiles directly.
Uninstalling this method is harder.
The install script requires a distro that uses systemd.
{{% /tab %}}
{{% tab name="From Your Distro" %}}
Install Nix using your package manager, be that `apt`, `pacman`, `dnf`, etc.
The package is almost always called `nix`.
This integrates cleanly with your OS and is as easy to uninstall as any other package.
However, because it relies on dynamically linked libraries, an incompatible system update could potentially break Nix.
Additionally, you must rely on your distro's maintainers to package and push Nix updates rather than getting them directly from upstream.
For example, to install with pacman:
```sh
sudo pacman -S nix
```
After installing, you must manually enable the daemon.
For users on a systemd distro, use this command:
```sh
sudo systemctl enable --now nix-daemon
```
{{% /tab %}}
{{% /tabs %}}
## Installing Hyprland
Before you do anything, [enable flakes](https://nixos.wiki/wiki/Flakes#Enable_flakes), by adding this to `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`:
```nix
experimental-features = nix-command flakes
```
Once that is done, install Hyprland through `nix profile`:
{{< tabs >}}
{{< tab name="From hyprnix (Recommended)" >}}
Installing Hyprland (and other hypr\* tools) can be done like so:
```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:hyprwm/hyprnix#hyprland
```
Replace `#hyprland` with a different app from the flake to install it (e.g. `#hyprpaper`)
{{< /tab >}}
{{< tab name="From Nixpkgs" >}}
You can get Hyprland directly from Nixpkgs:
```sh
sudo nix profile install --profile /nix/var/nix/profiles/default nixpkgs#hyprland
```
{{< /tab >}}
{{< tab name="From the Flake" >}}
> [!NOTE]
> Make sure to enable [Cachix](../cachix) first.
> [!WARNING]
> This builds the latest, unstable git branch.
```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:hyprwm/Hyprland
```
{{< /tab >}}
{{< /tabs >}}
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](https://github.com/guibou/nixGL).
Just install it like so:
```sh
sudo nix profile add --profile /nix/var/nix/profiles/default github:guibou/nixGL --impure
```
`--impure` is needed due to `nixGL`'s reliance on hardware information.
Since 0.53.2, `start-hyprland` will automatically use `nixGL` if needed.
For versions before that, you must use `nixGL start-hyprland`.
Lastly, if you are using a Login Manager, like SDDM or GDM, you need to symlink the `.desktop` file like so:
```sh
sudo mkdir -p /usr/share/wayland-sessions
sudo ln -sf /nix/var/nix/profiles/default/share/wayland-sessions/hyprland.desktop /usr/share/wayland-sessions/hyprland.desktop
```
so that the login manager can find Hyprland.
## Upgrading / updating
In order to upgrade all your packages, you can run:
```sh
sudo nix profile upgrade --profile /nix/var/nix/profiles/default '.*'
```
Check the [Nix profile](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-profile.html) command documentation for other upgrade options if that interests you.
---
---
weight: 50
title: Cachix
---
> [!WARNING]
> Do **not** override Hyprland's `nixpkgs` input unless you know what you are doing.
> Doing so will render the cache useless, since you're building from a different Nixpkgs commit.
> [!NOTE]
> This page only applies to the flake package.
> You can safely skip this if you use the Nixpkgs package.
The Hyprland flake is not built by Hydra, so it is not cached in [cache.nixos.org], like the rest of Nixpkgs.
Instead of requiring you to build Hyprland (and its dependencies, which may include `mesa`, `ffmpeg`, etc.), we provide a Cachix cache that you can add to your Nix configuration.
The [Hyprland Cachix](https://app.cachix.org/cache/hyprland) exists to cache the `hyprland` packages and any dependencies not found in [cache.nixos.org].
> [!WARNING]
> In order for Nix to take advantage of the cache, it has to be enabled **before** using the Hyprland flake package.
```nix {filename="configuration.nix"}
{
nix.settings = {
substituters = ["https://hyprland.cachix.org"];
trusted-substituters = ["https://hyprland.cachix.org"];
trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
# Required so non-root users are allowed to use the above substituter/keys.
# Use @wheel for all sudo users, or list your username explicitly.
trusted-users = ["root" "@wheel"];
};
}
```
> [!NOTE]
> If you see `ignoring the client-specified setting 'trusted-public-keys', because it is a restricted setting and you are not a trusted user`, your user is not in `trusted-users`.
> Add it as shown above and rebuild.
[cache.nixos.org]: https://cache.nixos.org
---
---
weight: 60
title: Advanced
---
## Overlays
### default
The `default` Hyprland overlay only contains the Hyprland package along with xdg-desktop-portal-hyprland, and Hyprland's internal dependencies (udis86-hyprland and glaze-hyprland).
This means you need to import all the overlays for the hypr\* dependencies yourself if you want them up to date.
Otherwise, Hyprland will build with the versions available in Nixpkgs.
### hyprland-packages
If you instead want an overlay with all dependencies, import both `hyprland-packages` and `hyprland-extras` overlays.
> [!NOTE]
> The dependencies can sometimes be out of date and impact other hypr\* apps, e.g. <https://github.com/hyprwm/Hyprland/discussions/13396>.
> In such cases, either ping the maintainers to update the lockfiles, or use the `default` overlay.
## Package options
These are the default options that the Hyprland package is built with.
These can be changed by setting the appropriate option to `true` or `false`.
For additional options, see [module options](https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=hyprland).
### Package
You can override the package through the `.override` or `.overrideAttrs` mechanisms.
```nix
(pkgs.hyprland.override { # or inputs.hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland
enableXWayland = true; # whether to enable Xwayland
withSystemd = true; # whether to build with systemd support
})
```
### NixOS & HM modules
```nix
{
programs.hyprland = { # or wayland.windowManager.hyprland for home manager
enable = true;
xwayland.enable = true;
};
}
```
## Using Nix repl
If you're using Nix (and not NixOS or Home Manager) and you want to override, you can do it like this:
```nix
$ nix repl
nix-repl> :lf github:hyprwm/Hyprland
nix-repl> :bl outputs.packages.x86_64-linux.hyprland.override { /* flag here */ }
```
Then you can run Hyprland from the built path.
You can also use `overrideAttrs` to override `mkDerivation`'s arguments, such as `cmakeBuildType`:
```nix
$ nix repl
nix-repl> :lf github:hyprwm/Hyprland
nix-repl> :bl outputs.packages.x86_64-linux.hyprland.overrideAttrs (self: super: { cmakeBuildType = "Debug" })
```
## 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:
```nix {filename="plugin.nix"}
{
lib,
fetchFromGitHub,
cmake,
hyprland,
hyprlandPlugins,
}:
hyprlandPlugins.mkHyprlandPlugin (finalAttrs: {
pluginName = "hy3";
version = "0.39.1";
src = fetchFromGitHub {
owner = "outfoxxed";
repo = "hy3";
rev = "hl${finalAttrs.version}";
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;
};
})
```
```nix {filename="home.nix"}
{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.
## Fixing problems with themes
If your themes for your mouse cursors, icons or windows don't load correctly, see the relevant section in [Hyprland with Home Manager](../configuring-hyprland-with-home-manager).
If you prefer not to use Home Manager, you can also resolve the issues with GTK themes using dconf like so:
```nix {filename="configuration.nix"}
{
programs.dconf.profiles.user.databases = [
{
settings."org/gnome/desktop/interface" = {
gtk-theme = "Adwaita";
icon-theme = "Flat-Remix-Red-Dark";
font-name = "Noto Sans Medium 11";
document-font-name = "Noto Sans Medium 11";
monospace-font-name = "Noto Sans Mono Medium 11";
};
}
];
}
```
---
---
weight: 70
title: Contributing and Debugging
---
Everything needed to build and debug Hyprland and other hyprwm programs is included inside the provided `devShell`s.
To use it in the cloned repo, simply run `nix develop`.
## Build in debug mode
### Through `nix build`
A debug build is already provided through the hyprland flake: `hyprland.packages.${pkgs.stdenv.hostPlatform.system}.hyprland-debug`.
Most hyprwm apps also provide their own `-debug` versions.
For those that don't, one can build the debug version from the CLI by using [overrideAttrs](../advanced/#using-nix-repl) with `cmakeBuildType = "Debug";` or `mesonBuildType = "debug";`, depending on the program.
If you don't want to use the Hyprland flake, you can build the Nixpkgs derivation in debug mode.
To do so, use the following code in the `package` attribute of the NixOS/Home Manager modules:
```nix
hyprland.override {
debug = true;
};
```
### Through `cmake`
You can build Hyprland by directly calling `cmake` instead of through `nix build`.
The advantage is being able to do incremental builds (just building whatever little change you made instead of the entire repo).
1. Clone the Hyprland repo including its submodules.
1. Enter the directory and execute `nix develop` in your shell.
1. Run `make debug` (check the Makefile for other options).
## Bisecting an issue
Follow the [Bisecting an issue](../../crashes-and-bugs/#bisecting-an-issue) guide.
To build, run `nix build`.
> [!WARNING]
> To build with Tracy support, modify `nix/default.nix` to enable the flag, then run `nix build '.?submodules=1'`.
To view logs, pass the `--print-build-logs` (`-L`) flag.
To keep a failed build directory, pass the `--keep-failed` flag.
### Using Cachix to bisect
If you enable [Cachix](../cachix), you can call `nix run github:hyprwm/Hyprland/commit_hash` to execute that commit without compiling it, because cachix stores binaries for every commit from Hyprland.
## Building the Wayland stack with ASan
Run `nix develop` first, then follow the [Building with ASan](../../crashes-and-bugs/#building-the-wayland-stack-with-asan) guide.
## Getting a debug stacktrace
Debug stacktraces provide useful info on why a program crashed.
To get proper stacktraces from Hyprland, make sure it was [built in debug mode](#build-in-debug-mode).
After a crash, perform the following steps:
```sh
nix shell nixpkgs#gdb # get GDB temporarily
coredumpctl # check the PID of the recent crash
coredumpctl debug <PID> # using the PID found in the previous step
```
The rest of the process is the same as [here](../../crashes-and-bugs#obtaining-a-debug-stacktrace), from step 3 onwards.
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |