Can we run Caelestia Hyprland dotfiles on NixOS without the AUR? Yes. By patching its Python CLI wheels and C++ dependencies directly, we can deploy Caelestia Dotfiles on NixOS in a fully immutable setup.
Hi all, and welcome back to MusaBase!. Previously, I installed JaKooLit Hyprland and ML4W Dotfiles on my NixOS and it's been a helluva experience. To continue this experience, I took a new challenge: installing Caelestia Dots on NixOS. It was a completely different ride than I expected but with this I learned a lot about NixOS. And in today's guide, I am going to show how you can also install Caelestia dotfiles on your NixOS system.
In this guide, we will cover how to:
- Enable flakes and Home Manager for Caelestia dots installation on NixOS.
- Create a system flake (/etc/nixos/flake.nix) to handle the Caelestia dots session on NixOS.
- Add Hyprland, Polkit, and Xserver services plus Caelestia packages to configuration.nix.
- Create a Caelestia dotfiles Home Manager (/etc/nixos/home.nix).
- Install Caelestia dotfiles on NixOS with a rebuild.
- And finally, log into our installed Caelestia dotfiles Hyprland session on NixOS.
By the end of this guide, we will have a Caelestia dotfiles Hyprland session running on our NixOS system without any errors.
⚡ TL;DR: Install Caelestia Hyprland Dotfiles on NixOS
A quick reference for installing Caelestia Hyprland dotfiles on a base NixOS system using flakes and Home Manager, including enabling experimental features, creating a system flake, adding packages and fonts, cloning dotfiles through activation scripts, rebuilding, and logging into the Caelestia session.
-
Enable flakes and experimental features in configuration.nix:
Add:sudo nano /etc/nixos/configuration.nixnix.settings.experimental-features = [ "nix-command" "flakes" ];(See the "Enable Flakes" section for details.) -
Create the system flake at /etc/nixos/flake.nix:
Add the flake with inputs forsudo nano /etc/nixos/flake.nixnixpkgs,home-manager,caelestia-shell, andcaelestia-cli. Include the Home Manager module and yourhome.niximport. (See the "Create Caelestia Dots System Flake" section for the full flake.) -
Add Hyprland, portals, fonts, and Caelestia packages to configuration.nix:
Add:sudo nano /etc/nixos/configuration.nix
lists with Caelestia dependencies. (See the "Add Hyprland and Caelestia Dotfiles Fonts and Packages" section for the full list.)programs.hyprland.enable = true; xdg.portal.enable = true; xdg.portal.extraPortals = [ pkgs.xdg-desktop-portal-gtk ]; security.polkit.enable = true; services.gnome.gnome-keyring.enable = true; fonts.packages environment.systemPackages -
Create the Home Manager config at /etc/nixos/home.nix:
Add:sudo nano /etc/nixos/home.nixprograms.caelestia.enable = true;,programs.caelestia.cli.enabled = true;, theimportsline forinputs.caelestia-shell.homeManagerModules.default, thehome.activation.cloneCaelestiaDotsscript that clones the dots repo, and thexdg.configFilesymlinks forhypr,fish,foot,fastfetch,btop,micro,Thunar, andstarship.toml. (See the "Create Caelestia's Home Manager Config" section for the full config.) -
Rebuild NixOS with the flake:
This takes roughly 10 to 25 minutes depending on your internet speed and CPU. Some packages like quickshell compile from source. The terminal may close automatically when done.cd /etc/nixos sudo nix-shell -p git --run "nixos-rebuild switch --flake .#nixos" -
Reboot and log into Caelestia Hyprland:
From your login manager's session menu, select Hyprland, enter your password, and enjoy your new Caelestia desktop!reboot
💡 If you encounter "Could not resolve host" errors while downloading packages or cloning repos, add custom nameservers (1.1.1.1 and 8.8.8.8) to your configuration.nix with networking.nameservers = [ "1.1.1.1" "8.8.8.8" ]; and networking.networkmanager.dns = "none";, then rebuild. Keep your root partition at 30GB+ (Caelestia takes about 15GB) to ensure enough space for all packages and dependencies.
Prerequisites
To install Caelestia Hyprland dotfiles on NixOS, we only need a base NixOS system installed. I'm installing it on my NixOS system with Budgie as its desktop environment. If you don't have NixOS installed, I would recommend you first follow my guide:
Install NixOS with Budgie or any desktop environment you want, then come back to this guide and continue. Make sure to give your root partition enough space, like around 30 GB+, because the total amount of space after installing Caelesita is around 15 GB. The remaining space is for your other data.
System Requirements for Caelestia Dotfiles on NixOS:
- Processor: Any x86-64 compatible
- RAM: Minimum 8GB (but more RAM is better)
- Storage: Minimum 30GB (it's only for NixOS system files and Caelestia files), you will need more storage space for additional packages and files
- GPU: Any 2015+ GPU
- OS: Minimal/base NixOS
- Stable internet connection
Step 1: Enable Flakes
In this step, we will enable flakes and rebuild the NixOS system. If you already have flakes enabled, then skip this step.
- To enable flakes, open a terminal and run:
sudo nano /etc/nixos/configuration.nix - Add the following line:
nix.settings.experimental-features = [ "nix-command" "flakes" ]; - After adding the experimental-features, press CTRL + O to save the file, then press ENTER to apply, then press CTRL + X to exit the file.
- Next, run the nixos-rebuild command to apply the changes system-wide:
sudo nixos-rebuild switch
- Next, to enable experimental-features, run:
sudo nixos-rebuild switch
Step 2: Create Caelestia Dots System Flake for Hyprland Session
In this step, we will create a system flake file for Caelestia dotfiles at /etc/nixos/flake.nix and add the data needed to run Caelestia dotfiles on NixOS.
2.1: Fetch Hostname, Username and stateVersion
- Before creating flake.nix, we need hostname, username and NixOS's stateVersion.
- These values are needed for the Caelestia flake data and should match our current values.
- Fetching these values is super simple. Just run the following command:
hostname whoami grep stateVersion /etc/nixos/configuration.nix
- Note the values that your system has. In the next step, we are going to use them.
2.2: Create System Flake for Caelestia Dotfiles
- In the terminal, run:
sudo nano /etc/nixos/flake.nix - You may get an empty file. Add the following to the file:
{ description = "NixOS + Caelestia (Hyprland Dotfiles Session)"; inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; home-manager = { url = "github:nix-community/home-manager"; inputs.nixpkgs.follows = "nixpkgs"; }; caelestia-shell = { url = "github:caelestia-dots/shell"; inputs.nixpkgs.follows = "nixpkgs"; }; caelestia-cli = { url = "github:caelestia-dots/cli"; inputs.nixpkgs.follows = "nixpkgs"; }; }; outputs = { self, nixpkgs, home-manager, caelestia-shell, caelestia-cli, ... } @ inputs : { nixosConfigurations.nixos = nixpkgs.lib.nixosSystem { system = "x86_64-linux"; specialArgs = { inherit inputs; }; modules = [ ./configuration.nix home-manager.nixosModules.home-manager { home-manager.useGlobalPkgs = true; home-manager.useUserPackages = true; home-manager.extraSpecialArgs = { inherit inputs; }; home-manager.users.musabase = import ./home.nix; # here replace musabase with your username } ]; }; }; }
- After adding the data, press CTRL + O to save the changes, then press ENTER to apply, then press CTRL + X to exit the file.
What are we actually adding in the flake.nix:
Important: The names and locations of inputs, modules, and user files used by Caelestia may change in future versions. Names such as caelestia-shell, caelestia-cli, home-manager, or home.nix may be renamed or reorganized. Always double-check the current Caelestia dotfiles repository structure before running this flake. If the names or paths have changed, update the flake accordingly or leave a comment on this guide for a quick fix.
Step 3: Add Hyprland and Caelestia Dotfiles Fonts and Packages on NixOS
In this step, we will add the Hyprland session, X server and Polkit services, and also add the core Caelestia packages with fonts at /etc/nixos/configuration.nix.
- In the terminal, run:
sudo nano /etc/nixos/configuration.nix - In the configuration.nix file, add Hyprland and xdg.portal like this:
programs.hyprland = { enable = true; xwayland.enable = true; }; xdg.portal = { enable = true; extraPortals = [ pkgs.xdg-desktop-portal-gtk ]; }; - Add polkit and keyring like this:
services.gnome.gnome-keyring.enable = true; security.polkit.enable = true; - Add fonts:
fonts.packages = with pkgs; [ nerd-fonts.jetbrains-mono nerd-fonts.caskaydia-cove material-symbols rubik noto-fonts noto-fonts-cjk-sans noto-fonts-color-emoji ]; - And finally, add Caelestia packages:
environment.systemPackages = with pkgs; [ wget git curl foot fish thunar starship fastfetch btop micro adw-gtk3 papirus-icon-theme papirus-folders wl-clipboard cliphist hyprpicker swappy grim slurp ]; - Here's the image of the complete addition to configuration.nix that I did on my NixOS system:
- After adding the data, press CTRL + O to save the changes, then press ENTER to apply, then press CTRL + X to exit the file.
Step 4: Create Caelestia's Home Manager Config on NixOS
In this step, we will create the Caelestia's Home Manager file at /etc/nixos/home.nix. In this file, we will add all the necessary data for Caelestia dotfiles, and from this file all of Caelestia's config will be symlinked with our NixOS system, such as fish, foot, starship.toml, etc.
- In the terminal, run:
sudo nano /etc/nixos/home.nix - This file will be empty. We will start by adding the configuration:
{ config, pkgs, inputs, ... }: { home.username = "musabase"; #replace with your actual username home.homeDirectory = "/home/musabase"; #replace with your actual homeDirectory home.stateVersion = "26.05"; #replace with your current NixOS's stateVersion that we fetched in Step 2.1 imports = [ inputs.caelestia-shell.homeManagerModules.default ]; programs.caelestia = { enable = true; systemd = { enable = true; target = "graphical-session.target"; }; cli.enabled = true; settings = { paths.wallpaperDir = "~/Pictures/Wallpapers"; }; }; home.activation.cloneCaelestiaDots = config.lib.dag.entryAfter [ "writeBoundary" ] '' if [ ! -d "$HOME/.local/share/caelestia-dots" ]; then $DRY_RUN_CMD ${pkgs.git}/bin/git clone \ https://github.com/caelestia-dots/caelestia.git \ "$HOME/.local/share/caelestia-dots" fi ''; xdg.configFile = { "hypr".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/hypr"; "fish".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/fish"; "foot".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/foot"; "fastfetch".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/fastfetch"; "btop".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/btop"; "micro".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/micro"; "Thunar".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/thunar"; "starship.toml".source = config.lib.file.mkOutOfStoreSymlink "${config.home.homeDirectory}/.local/share/caelestia-dots/starship.toml"; }; }
- After adding the data, press CTRL + O to save the changes, then press ENTER to apply, then press CTRL + X to exit the file.
What are we actually adding in the home.nix
Step 5: Install Caelestia Dotfiles on NixOS
In this step, the actual installation of Caelestia dotfiles on NixOS will take place. Before this step, we have added and configured several services, components, dependencies and packages that are necessary to install and launch the Caelestia dotfiles Hyprland session on NixOS.
- With all set, in the terminal run the following commands consecutively:
cd /etc/nixos sudo nix-shell -p git --run "nixos-rebuild switch --flake .#nixos"
- After running the rebuild command, NixOS will start reading the changes we have made and start downloading, installing and configuring the system to the new changes.
- Some packages will need to be compiled and built from source, such as quickshell.
- The whole process will take roughly 10 to 25 minutes depending on your internet connection speed and CPU cores for compiling.
- After the Caelestia dots installation is complete, the terminal will close automatically, which is expected, so don't panic.
- Next, reboot the system.
Could not resolve host during NixOS rebuild
If you hit errors like Could not resolve hostname (X) Could not resolve host or 1 dependency failed while downloading packages or repos from GitHub, this usually happens because of the default nameserver provided by your ISP, which may block access to certain packages or GitHub altogether. This issue might be region‑specific, but the fix below works for NixOS.
error: unable to download 'https://cache.nixos.org/...': Could not resolve host
OR
curl: (6) Could not resolve host: github.com
🔍 This does not mean your configuration is wrong. In most cases, it is caused by one of the following:
- Network or Firewall Restrictions: Your local firewall, ISP, or proxy may be blocking outbound connections on certain ports.
- Mirror Issues: The NixOS cache mirror you are using may be slow, temporarily down, or unreachable.
- DNS Problems: Your configured nameserver may be failing to resolve the mirror's or GitHub's IP address.
✅ Quick fix for NixOS: add custom nameservers to your configuration:
sudo nano /etc/nixos/configuration.nixThen add these lines inside the { ... } block:
networking.nameservers = [
"1.1.1.1"
"8.8.8.8"
];
networking.networkmanager.dns = "none";Save the file (CTRL+O, ENTER, then CTRL+X) and rebuild:
sudo nixos-rebuild switchThis sets Cloudflare and Google DNS as your resolvers and tells NetworkManager not to override them.
Step 6: Boot into Installed Caelestia Dotfiles on NixOS
I installed NixOS with Budgie as its desktop environment, so I already have a login manager installed. If you have the same setup or any login manager installed, then you should see an entry for the Hyprland session in your login manager's session dropdown. If you are using NixOS without any DE, then the default command to launch the Hyprland session is Hyprland.
Enter your password and log in.
And we are in!
Set Caelestia Color Scheme to Dynamic
Caelestia uses Google's Material You component to change the whole aesthetic of your desktop color scheme based on your current wallpaper. However, by default it's turned off. We can use this feature by two methods:
- To set the color scheme to a particular wallpaper, run:
caelestia wallpaper -f path_to_wallpaper - To set the color scheme to dynamically change with each wallpaper, run:
caelestia scheme set -n dynamic
❓ Frequently Asked Questions: Installing Caelestia Hyprland Dotfiles on NixOS
Why would I want to install Caelestia Hyprland dotfiles manually on NixOS instead of using the official installer?
The official Caelestia installer is designed specifically for Arch Linux and assumes an AUR-based environment with pacman. NixOS uses a completely different package management and system configuration approach (declarative, with configuration.nix and flakes). Installing manually with flakes and Home Manager gives you full control over which packages are added, how services are configured, and allows you to integrate Caelestia with your existing NixOS setup without breaking the declarative model. The caelestia-shell and caelestia-cli repositories both provide Nix flake support, which makes this integration possible.
What are the prerequisites for this manual installation?
You need a base NixOS system already installed (with or without a desktop environment). I used Budgie with LightDM as my login manager, but any desktop environment works. Make sure your root partition has at least 30 GB of free space (Caelestia itself takes about 15 GB after installation). You'll also need a stable internet connection, sudo/root access, and a basic understanding of Nix flakes and Home Manager.
Why do I need to use nix-shell -p git instead of a regular nixos-rebuild command?
Nix flakes require git to fetch and evaluate inputs from GitHub. On a fresh NixOS system, git may not be installed in your user environment yet. The command sudo nix-shell -p git --run "nixos-rebuild switch --flake .#nixos" temporarily provides git inside a Nix shell, then runs the rebuild inside that shell. This ensures the flake can resolve all inputs without permanently adding git to your system packages first.
What should I do if I get a "Could not resolve host" error while downloading packages or cloning repos?
This usually happens because your ISP's default nameserver is blocking or failing to resolve GitHub or NixOS cache domains. The fix is to add custom nameservers (like 1.1.1.1 and 8.8.8.8) to your /etc/nixos/configuration.nix with networking.nameservers = [ "1.1.1.1" "8.8.8.8" ]; and networking.networkmanager.dns = "none";, then rebuild your system. This is covered in detail in the "Could not resolve host during NixOS rebuild" section of the guide.
How long does the entire installation process take?
The nixos-rebuild step (Step 5) takes roughly 10 to 25 minutes depending on your internet speed and CPU, as some packages like quickshell compile from source. The whole process includes downloading packages, compiling C++ dependencies, cloning the dots repo, and setting up symlinks. Overall, the entire process should take 15 to 30 minutes on average.
What is the cloneCaelestiaDots activation script for, and how does it work?
The home.activation.cloneCaelestiaDots script in home.nix runs after the filesystem is set up. It checks if ~/.local/share/caelestia-dots exists. If not, it clones the official Caelestia dots repository into that path. This keeps your dotfiles fresh and lets you pull updates with a simple git command. The config.lib.dag.entryAfter [ "writeBoundary" ] part ensures the script runs at the right time during activation.
Can I dual-boot Caelestia Hyprland with my existing desktop environment on NixOS?
Yes, absolutely. Since NixOS allows you to have multiple desktop environments installed simultaneously, you can keep your existing desktop (like Budgie, GNOME, or KDE) and simply select Hyprland from your login manager's session menu. Your existing desktop environment remains untouched and fully functional. This is one of the biggest advantages of NixOS's declarative approach.
What if I don't have a login manager installed on my NixOS system?
If you installed NixOS without any desktop environment, you likely don't have a display/login manager installed. In that case, you can simply install a lightweight one like LightDM or SDDM, or you can start Hyprland directly from the terminal by running Hyprland after logging in. The guide explains both approaches.
Is the rollback feature included with this manual installation?
No, the rollback feature is not included by default in this manual installation because NixOS itself has a built-in rollback mechanism through its generations system. Every time you run sudo nixos-rebuild switch, a new generation is created, and you can boot into previous generations from the GRUB menu. You don't need Snapper or grub-btrfs on NixOS – the system already provides robust rollback capabilities.
What are the minimum system requirements for Caelestia Hyprland on NixOS?
Since Caelestia is a feature-rich Hyprland configuration with Quickshell, you need at least 8 GB RAM (16 GB recommended), a 64-bit processor (x86-64 compatible), and a GPU from 2015 or later with decent Vulkan support. For storage, make sure your root partition has at least 30 GB of free space, as the total installation (system + Caelestia) takes about 15 GB, and you'll need additional space for future packages.
Can I update Caelestia dotfiles after installation?
Yes. Since the activation script clones the dotfiles from the official GitHub repository into ~/.local/share/caelestia-dots, you can simply pull the latest changes by running git pull inside that directory. The symlinks in xdg.configFile point to those files, so changes take effect after a rebuild. However, keep in mind that future updates may change the directory structure or filenames, so always double-check the contents of the updated dotfiles before rebuilding.
What if I make a mistake during installation – can I start over?
Yes. Since NixOS is declarative, you can simply revert changes by editing your configuration.nix and home.nix to remove the Caelestia packages and services, then run sudo nixos-rebuild switch to roll back your system state. For the dotfiles themselves, you can delete the ~/.local/share/caelestia-dots directory and any related config directories, and start fresh from Step 4. Your base NixOS system remains intact.
🚀 Caelestia Hyprland on NixOS: Fully Set Up!
We now have Caelestia's fluid, morphing desktop environment running on a declarative NixOS base, blending the polished Material You aesthetics of the Caelestia shell with the rock-solid reproducibility of Nix flakes and Home Manager. Between the Quickshell-based bar, the dynamic color scheme engine, and the tiling Wayland workflow, your NixOS desktop is genuinely complete.
If this completed your NixOS Hyprland journey, stick around — MusaBase has plenty more Linux, BSD, and virtualization guides where this came from.
101 out, I'll see you in the next one! 🚀