I have put five different Hyprland dotfiles onto NixOS. Four of them have no NixOS support whatsoever, so every one was a port: read the installer, work out what it assumes, build that in Nix.

JaKooLit Hyprland Dotfiles on NixOS

JaKooLit is the exception. There is a real NixOS-Hyprland repo, with a flake, a host-config layout, the lot. I saved it for last expecting a relaxed afternoon.

It was the one that cost me an evening, and I think the reason generalises.

Unsupported software fails honestly. You know you are off-road, you expect friction, and when something breaks you look at the software. Half-supported software fails differently. The official path exists, so when it does not work you assume you made a mistake, and you go and re-read your own commands instead of the repo's.

Three gaps in the official NixOS path did that to me.

Gap 1: hosts/default is not a config

The repo ships hosts/default. It looks like the default configuration. It is a template, and nothing uses it directly.

cp -r hosts/default hosts/musabase 

The folder name has to match your actual hostname exactly, because the flake resolves a configuration by that name later. A near-miss here fails at build time with an error about a missing attribute, which does not obviously point back at a folder you named five steps ago.

Gap 2: flake.nix ships the maintainer's machine

Open flake.nix and you find this:

host = "jak-hl"; username = "dwilliams"; 

Those are real values for somebody else's computer, hardcoded. Both have to become yours:

host = "musabase"; username = "musabase"; 

This is not an unreasonable design, it is just not announced anywhere you would look first. And it has to agree with the folder name from gap 1 and with the --flake .#<name> argument later. Three places, one value, no validation until the build.

Gap 3: the one that actually got me

Step one of the whole process is this:

nix-shell -p git curl pciutils 

Temporary shell, temporary packages, nothing permanently installed. Very Nix, very clean. Everything from here until reboot runs inside it.

Then you reach the build:

git add -A NIX_CONFIG="experimental-features = nix-command flakes" sudo nixos-rebuild switch --flake .#musabase 

This downloads around 23GB, mostly Quickshell and its Qt dependencies, compiles for 25 to 40 minutes, and then the terminal closes on its own. That is normal. It is not a crash.

It is also the end of your nix-shell, and therefore the end of git.

So the next step, cloning the actual dotfiles, greets you with git: no such command. You just spent forty minutes building a system and the very first command afterwards fails on a tool you installed at the start.

What makes this a good trap rather than just an annoyance: step 5 destroyed your environment as a side effect of succeeding. Nothing went wrong. If the build had failed you would still have had git. Success is what took it away.

The fix is to stop being clever and install git permanently:

environment.systemPackages = with pkgs; [ git ]; 

Then sudo nixos-rebuild switch and carry on. In hindsight I would put git in configuration.nix before starting and skip the nix-shell for it entirely. The ephemeral-shell approach is the more idiomatic one and it is the wrong tool when a later step needs the same binary across a session boundary you did not know existed.

Check which account these repos live under

Worth a paragraph on its own, because getting this wrong means piping someone else's shell script into bash.

The repos are under LinuxBeginnings, not JaKooLit:

git clone --depth 1 https://github.com/LinuxBeginnings/NixOS-Hyprland.git ~/NixOS-Hyprland git clone --depth 1 https://github.com/LinuxBeginnings/GTK-themes-icons.git git clone --depth 1 https://github.com/LinuxBeginnings/Hyprland-Dots ~/Hyprland-Dots 

Maintenance of these moved, and plenty of older guides and forum answers still point at the previous owner. Before you run any install script from a tutorial, including this one, check that the repo it names is the one the project currently maintains. Repo attribution is a security question, not a tidiness question.

The rest is genuinely pleasant

Credit where it is due. Once past those three gaps the official path is good.

nixos-generate-config --show-hardware-config writes straight into your host folder. The host layout splits cleanly into config.nix for system settings, packages-fonts.nix for extras and users.nix for the account, so customising does not mean reading the whole tree. And copy.sh runs a real interactive installer that asks about keyboard layout, editor, monitor scaling for sub-1440p versus 1440p and up, clock format, temperature units, and whether you want the 1GB wallpaper pack.

That installer is better than what the other four dotfiles give you on NixOS, which is nothing. The support is real. It is the documentation around the support that has holes.

Budget 60GB on root, and expect the Quickshell download to dominate the whole experience.

The transferable bit

When a project says it supports your platform, that claim is about the code. It is not a claim about the documentation.

A supported path with three undocumented steps is more frustrating than no path at all, because the existence of the path tells you the problem must be you. If you are following an official guide for a less-common platform and something fails, give the repo the same suspicion you would give your own typing. Check what the template files actually are, check what is hardcoded, and check whether anything you installed earlier is still there.

The full walkthrough, with screenshots of every installer prompt, the DNS fix if your ISP blocks the Nix cache, the host-file customisation options and a long FAQ, is on my site: How to Install JaKooLit Hyprland Dotfiles on NixOS.

It is one of a set. The same treatment for Caelestia, End-4, ML4W and HyDE on NixOS, plus a comparison of all five.

If you have been bitten by a step that broke because an earlier step succeeded, I would like to hear it in the comments. That category seems underrated next to the ordinary kind of failure.

Originally published on MusaBase.