Caelestia only ships an Arch installer, so I wrote the NixOS version with a flake and Home Manager

Caelestia is a Hyprland setup with its own shell and a small CLI for wallpapers and color schemes. Its official installer only targets Arch Linux, and NixOS has no AUR, so there is nothing to run.

I set it up by hand instead: a flake that pulls Caelestia's shell and CLI from the upstream repos, plus a Home Manager config that puts the dotfiles in place. This post walks through the pieces and the steps that matter. The complete files, screenshots and the full walkthrough are on my site, linked at the end.

Tested on: a base NixOS install with Budgie and LightDM as the starting desktop, built against nixos-unstable. Treat it as "works for me" until you've tried it on yours.

What you need

• A base NixOS install. I started from Budgie with LightDM.
• x86-64 CPU, 8 GB RAM minimum, and a 30 GB root partition or more. Caelestia itself takes about 15 GB.
• A GPU from 2015 or newer.

• A stable connection. The first build compiles quickshell from source.

  The three files

• flake.nix (new, in /etc/nixos): the inputs are nixpkgs on unstable, Home Manager, and Caelestia's shell and CLI taken straight from the caelestia-dots GitHub org. It defines one system that loads your configuration.nix and your Home Manager user.

• configuration.nix (your existing file, with additions): Hyprland with XWayland, the GTK desktop portal, polkit, GNOME Keyring, the fonts (JetBrains Mono and Caskaydia Cove Nerd Fonts, Material Symbols, Rubik, Noto), and the tools Caelestia leans on, such as foot, fish, Thunar, starship, fastfetch, btop, micro and a set of clipboard and screenshot utilities.

• home.nix (new, in /etc/nixos): enables Caelestia's Home Manager module together with its CLI, clones the caelestia-dots/caelestia repo once into ~/.local/share/caelestia-dots, and links its config folders (hypr, fish, foot, fastfetch, btop, micro, Thunar, starship) into ~/.config. The links point outside the Nix store, so you can edit the dotfiles live without rebuilding.
  Your username sits in both flake.nix and home.nix, and home.nix also needs your state version.

Get the three files: copy them from the full guide on MusaBase. I'm not pasting them here.

The steps

1. Enable flakes. Skip this if you already have them. Add this line to /etc/nixos/configuration.nix:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Then rebuild once, without --flake for now:

sudo nixos-rebuild switch

2. Look up your details. You need these for the two files that hold your user:

whoami
grep stateVersion /etc/nixos/configuration.nix

3. Create the three files. Take them from the guide. Add flake.nix and home.nix to /etc/nixos, then add the Caelestia section to your existing configuration.nix. Put your username and state version in.

4. Rebuild against the flake.

cd /etc/nixos
sudo nix-shell -p git --run "nixos-rebuild switch --flake .#nixos"

The nix-shell wrapper puts git on the path for the build, in case it isn't installed yet. Expect 10 to 25 minutes.

5. Reboot and log in. Pick Hyprland from your login manager's session list.

6. Set the color scheme. To have it follow your wallpaper:

caelestia scheme set -n dynamic

Or lock it to one wallpaper:

caelestia wallpaper -f path_to_wallpaper

What was tricky

No installer to lean on. The official route is Arch-only, so every dependency has to come from the flake inputs or nixpkgs.

Upstream names can move. The flake tracks Caelestia's repos without a pinned revision. If the shell, the CLI or the Home Manager module path gets renamed, the flake stops evaluating. Check the current upstream layout before assuming your own config is wrong.

Editable dotfiles on a read-only store. Caelestia expects to be edited live, so the dotfiles are cloned once and symlinked from outside the Nix store instead of being copied in.

Updating and going back

To pull newer dotfiles, run git pull inside ~/.local/share/caelestia-dots and rebuild. Updates can change the file layout, so look at what changed first.

Every rebuild creates a new generation. If something breaks, pick the previous one from the boot menu.

The full guide

The full guide on my site has the complete files to copy, screenshots of each step and the FAQ: How to Install Caelestia Hyprland Dotfiles on NixOS. The repo is caelestia-dots-nixos. If you want to compare it with other setups, I also wrote up End-4's dotfiles on NixOS, and the series starts at Best Hyprland Dotfiles 2026.

I wrote both the config and the site linked above, so weigh my testing with that in mind. If something breaks for you, leave a comment or open an issue on the repo with the first error line from the rebuild and I'll take a look.

Originally published on MusaBase.