HyDE delivers one of the most versatile multi-theme Hyprland experiences on Linux, but running its Arch-centric install scripts directly will break on NixOS's read-only filesystem. Here is how to package dependencies and deploy HyDE Hyprland Dotfiles on NixOS cleanly.
Hi all, and welcome back to MusaBase!. Previously, I was tinkering on NixOS with Hyprland and showed you guys how to install End4 dotfiles, Caelestia dotfiles, JaKooLit Hyprland dotfiles, and also ML4W setup on NixOS. So I thought only one of the top best Hyprland dotfiles was left, and that is the HyDE Project. HyDE is the most theme-rich, with over 70 built-in themes and the most cutting-edge effects, such as blur for all windows, glass effect, animations, and much more. HyDE also comes with a themed login manager (SDDM) and its unique lock screen. This makes it stand out among its counterparts. However, it is native to Arch Linux, which means the official installer only works on Arch Linux, where it installs automatically. But as I managed to install and run other Hyprland dotfiles on NixOS as mentioned above, I also made HyDE work on NixOS. Though you don't have to do all the manual work to install HyDE on your NixOS system, because I have configured the HyDE files for NixOS's ecosystem and uploaded them on GitHub, making it almost an auto setup.
In this guide, we will cover how to:
- Download pre-configured HyDE's flake.nix, and hyde.nix files from GitHub.
- Add your current username inside flake.nix to fix the username mismatch error during installation.
- Install HyDE Hyprland dotfiles on NixOS by rebuilding the NixOS system with the new HyDE .nix files.
- And finally, log into our installed HyDE Hyprland dotfiles on NixOS.
By the end of this guide, we will have HyDE Project Hyprland dotfiles running on our NixOS system seamlessly.
⚡ TL;DR: Install HyDE Hyprland Dotfiles on NixOS
A quick reference for installing HyDE Hyprland dotfiles on NixOS using flakes and pre-configured .nix files, including downloading the files, fixing the username mismatch, rebuilding the system, and logging into the themed SDDM session.
-
Download the pre-configured .nix files from GitHub:
cd /etc/nixos sudo curl -fLO https://raw.githubusercontent.com/musabase/hyde-hyprland-nixos/main/flake.nix sudo curl -fLO https://raw.githubusercontent.com/musabase/hyde-hyprland-nixos/main/hyde.nix sudo sed -i "s/CHANGEME/$(whoami)/" flake.nixSecurity note: These files run as root during the rebuild. Both are shown in full in the "What's in the HyDE Hyprland Nix Files" section below, so read them before you rebuild. Using a fixed commit instead of
(See the "Download HyDE Files" section for details.)mainmeans the files cannot change after you have reviewed them. -
Rebuild NixOS with the HyDE flake:
(See the "Install HyDE Dotfiles" section for details.)sudo NIX_CONFIG="experimental-features = nix-command flakes" \ nix-shell -p git --run "nixos-rebuild switch --flake /etc/nixos#nixos" - Reboot and log into the HyDE session: After the rebuild finishes, reboot your system. The themed SDDM login screen appears, and you enter your password to get into the HyDE Hyprland desktop. On the first login, HyDE imports its themes from GitHub, which takes a few minutes and needs an internet connection. A notification tells you when it finishes, so do not reboot until you see "Setup finished". (See the "Log In to HyDE" section for details.)
💡 The rebuild downloads packages and configures SDDM, Hyprland, and HyDE's theming components. On my PC, it took around 20 minutes. HyDE is not officially supported on NixOS through its Arch installer, so the pre-configured files on my GitHub handle the NixOS-specific work. If the rebuild fails, include the error line in a comment below and I will help you sort it out.
Prerequisites for HyDE Hyprland Dotfiles on NixOS
To install HyDE Hyprland dotfiles on NixOS, we only need a base NixOS system installed. I'm installing it on my NixOS system without any desktop environment, because the HyDE installation is going to override the login manager and display server with its own configuration. If you don't have NixOS installed, I recommend you first follow my guide:
Install NixOS without any desktop environment, then come back to this guide and continue. Make sure to give your root partition enough space, around 30 GB+, because the total space after installing HyDE Hyprland dotfiles is around 20 GB. The remaining space is for your other data.
System Requirements for HyDE Hyprland Dotfiles on NixOS:
- Processor: Any x86-64 compatible
- RAM: Minimum 8GB (but more RAM is better)
- Storage: Minimum 20GB (this is only for NixOS system files and HyDE files). You will need more storage space for additional packages and files
- GPU: Any 2015+ GPU
- OS: Minimal/base NixOS
- Hyprland: A current release. The flake follows nixos-unstable, which ships a recent Hyprland that HyDE's current dotfiles work with.
- Stable internet connection
- NVIDIA users: HyDE's Arch installer installs NVIDIA drivers automatically, but this NixOS setup does not. Add the following to your configuration.nix before the rebuild:
Check the NixOS NVIDIA wiki for the option that matches your card.services.xserver.videoDrivers = [ "nvidia" ]; hardware.graphics.enable = true; hardware.nvidia = { modesetting.enable = true; open = true; # use false for older GPUs that need the proprietary module };
Step 1: Download HyDE Hyprland Dotfiles from GitHub and Set Username
In this step, we will download two files from my GitHub repo called hyde-hyprland-nixos. The files are flake.nix and hyde.nix. I made these files so we don't have to write the code manually.
- Log in at the console (the text login screen) and run these commands one after another:
cd /etc/nixos sudo curl -fLO https://raw.githubusercontent.com/musabase/hyde-hyprland-nixos/main/flake.nix sudo curl -fLO https://raw.githubusercontent.com/musabase/hyde-hyprland-nixos/main/hyde.nix sudo sed -i "s/CHANGEME/$(whoami)/" flake.nix
Step 2: Install HyDE Hyprland Dotfiles on NixOS
In this step, we will install the HyDE Hyprland Dotfiles by rebuilding the NixOS system with the new files and configuration. This process will automatically install the custom themed SDDM, HyDE configs, and all the other perks we get from HyDE.
- To install HyDE Hyprland dotfiles, run:
sudo NIX_CONFIG="experimental-features = nix-command flakes" \ nix-shell -p git --run "nixos-rebuild switch --flake /etc/nixos#nixos"
- After running the rebuild command, the NixOS system will read the new files and changes to its own configuration.nix file and start downloading the official HyDE Hyprland repo and implementing the new packages, components, and configurations as written in the hyde.nix file.
- The whole process took roughly 20 minutes on my PC. It can vary on your PC depending on the speed of your internet connection.
- After the installation is complete, simply reboot the system with reboot.
Step 3: Log into Installed HyDE Hyprland Dotfiles on NixOS
After rebooting the system, we will have our themed SDDM screen to log into our freshly installed HyDE Hyprland dotfiles on NixOS:
First login takes a few minutes. The desktop may look half-styled at first. HyDE is deploying its dotfiles and importing its theme pack from GitHub in the background, and it needs internet for this. A notification says "First login: importing themes", and another says "Setup finished" when it is done. Do not reboot or log out before then. If the import fails, a critical notification appears; check the log with journalctl --user -u hyde-firstrun.
And, we are in!
FIN!!!
What's in the HyDE Hyprland Nix Files
We downloaded two files from GitHub which I uploaded on my GitHub page. Each file serves its specific purpose.
HyDE's flake.nix
flake.nix defines the pinned HyDE sources, the system configuration, and the username that HyDE deploys into. It is the only file you edit, and the install step does it for you with sed.
{
description = "HyDE Hyprland dotfiles on NixOS, deployed by HyDE's own deez-dots manifests";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
# Pinned upstream sources. flake.lock records their hashes automatically.
hyde = { url = "github:HyDE-Project/HyDE/fa2fd57afc7203b1b5653d3271f3a57ea3873f97"; flake = false; };
deez = { url = "github:HyDE-Project/deez-dots/f797e860bdccd7fbe188deac7e4dbabd9035786e"; flake = false; };
hyprquery = { url = "github:HyDE-Project/hyprquery/002af783eeb8c487a4bf90d75e5a804340557967"; flake = false; };
};
outputs = { nixpkgs, ... }@inputs:
let
hydeUser = "CHANGEME";
in
{
nixosConfigurations.nixos = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs hydeUser; };
modules = [ ./configuration.nix ./hyde.nix ];
};
};
}Purpose of Each Configuration:
- description: Describes the configuration as a NixOS setup that runs HyDE's Hyprland dotfiles through HyDE's own deployer, deez-dots.
- inputs: Declares the external flakes and repositories this configuration pulls in.
- nixpkgs: Provides the packages and NixOS modules used to build the system. The nixos-unstable branch ships newer Hyprland and Qt versions that HyDE expects.
- hyde: Pins the HyDE repository to a specific commit. This commit is what gets deployed into your home folder, so your install is reproducible.
- deez: Pins deez-dots, HyDE's own dotfile deployer. It reads HyDE's dot manifests and copies the files into your home folder.
- hyprquery: Pins hyq, the Hyprland query tool HyDE's theme switcher uses to read the current theme.
- flake = false: Tells Nix to treat the fetched repository as a plain source tree rather than a flake. This avoids evaluating HyDE's own flake file, which is not needed here.
- outputs: Defines the NixOS system configuration built from the declared inputs.
- hydeUser = "CHANGEME": The username HyDE deploys into. The sudo sed -i "s/CHANGEME/$(whoami)/" flake.nix command replaces it with your actual username during Step 1, so a username mismatch never reaches the rebuild.
- nixosConfigurations.nixos: Defines a NixOS configuration named nixos that this flake builds.
- nixpkgs.lib.nixosSystem: Creates the NixOS system using the modules and settings below.
- specialArgs = { inherit inputs hydeUser; }: Passes the flake inputs and the username into the NixOS modules so hyde.nix can pin the same HyDE sources and target the correct user.
- modules: Lists the NixOS modules loaded as part of this system configuration.
- ./configuration.nix: Loads your existing system configuration, which holds the usual NixOS settings such as bootloader, networking, and the user account.
- ./hyde.nix: Loads the HyDE-specific configuration that sets up Hyprland, SDDM, the HyDE runtimes, and the two user services that deploy the dotfiles.
hyde.nix
hyde.nix is where all the NixOS work happens. It builds HyDE's Python and Lua runtimes from nixpkgs, enables the Hyprland session and the themed SDDM, creates the FHS paths HyDE hardcodes, and adds the two user services that deploy HyDE into your home folder.
{ config, pkgs, lib, inputs, hydeUser, ... }:
let
# Keep only the attribute names that exist in this nixpkgs (avoids eval errors on renames).
pick = set: names: map (n: set.${n}) (builtins.filter (n: set ? ${n}) names);
# 1. HyDE source at the pinned commit, with the one NixOS fix.
hydeSrc = pkgs.runCommand "hyde-src" { } ''
cp -r ${inputs.hyde} $out
chmod -R u+w $out
substituteInPlace $out/Configs/.local/lib/hyde/theme.switch.sh \
--replace-fail "[ -d /run/current-system/sw/share/themes ]" "[ -d /run/hyde-nixos-disabled ]"
'';
# 2. deez-dots, HyDE's deployer (standard library only).
deez = pkgs.python3Packages.buildPythonPackage {
pname = "deez-dots";
version = "0.2.0";
pyproject = true;
src = inputs.deez;
build-system = with pkgs.python3Packages; [ setuptools wheel ];
pythonImportsCheck = [ "deez_dots" ];
};
# 3. hyprquery (hyq), used by theme switching.
hyprquery = pkgs.stdenv.mkDerivation {
pname = "hyprquery";
version = "0-unstable-2026-06-13";
src = inputs.hyprquery;
nativeBuildInputs = with pkgs; [ cmake pkg-config ];
buildInputs = with pkgs; [ hyprlang hyprutils libxkbcommon cli11 nlohmann_json ];
cmakeFlags = [ "-DHYPRQUERY_DISTRO_BUILD=ON" ];
postInstall = ''ln -s hyq $out/bin/hyprquery'';
};
# 4. Python for HyDE's scripts, replacing the uv venv HyDE builds on Arch.
hydePython = pkgs.python3.withPackages (ps: [ deez ] ++ pick ps [
"loguru" "pulsectl" "requests" "inotify-simple" "websockets" "xdg-base-dirs"
"pywayland" "pygobject3" "pyqt6" "pysensors"
]);
hydeVenv = pkgs.runCommand "hyde-python-env" { } ''
mkdir -p $out/bin
for f in ${hydePython}/bin/*; do ln -s "$f" "$out/bin/$(basename "$f")"; done
cat > $out/bin/activate <<'EOF'
VIRTUAL_ENV=/etc/hyde/python_env
export VIRTUAL_ENV
case ":$PATH:" in *":$VIRTUAL_ENV/bin:"*) ;; *) PATH="$VIRTUAL_ENV/bin:$PATH" ;; esac
export PATH
deactivate () { :; }
EOF
'';
# 5. Lua for HyDE's Lua scripts (config watcher, battery notify).
luaBase = pkgs.lua5_5 or pkgs.lua5_4;
hydeLua = luaBase.withPackages (ps: pick ps [
"luasec" "luasocket" "argparse" "dkjson" "luafilesystem" "lgi"
]);
hydeLuarocks = luaBase.pkgs.luarocks or pkgs.luarocks;
# Oh My Zsh with the three plugins HyDE's zsh config asks for.
zsh256color = pkgs.writeTextDir "zsh-256color/zsh-256color.plugin.zsh" ''
case "$TERM" in xterm|screen|tmux) export TERM="$TERM-256color" ;; esac
'';
hydeOmz = pkgs.runCommand "hyde-oh-my-zsh" { } ''
mkdir -p $out
cp -rs ${pkgs.oh-my-zsh}/share/oh-my-zsh/. $out/
chmod -R u+w $out
p=$out/custom/plugins
mkdir -p $p/zsh-autosuggestions $p/zsh-syntax-highlighting
cp -r ${zsh256color}/zsh-256color $p/
echo "source ${pkgs.zsh-autosuggestions}/share/zsh-autosuggestions/zsh-autosuggestions.zsh" \
> $p/zsh-autosuggestions/zsh-autosuggestions.plugin.zsh
echo "source ${pkgs.zsh-syntax-highlighting}/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" \
> $p/zsh-syntax-highlighting/zsh-syntax-highlighting.plugin.zsh
'';
# 6. killall that also matches Nix wrapper names.
killallShim = pkgs.writeShellScriptBin "killall" ''
${pkgs.psmisc}/bin/killall "$@" 2>/dev/null && exit 0
name="''${!#}"
set -- "''${@:1:$#-1}"
exec ${pkgs.psmisc}/bin/killall "$@" -r "^\.?''${name}(-wrapped)?$"
'';
# 7. Seeding, step 1 (before Hyprland starts): deploy HyDE when the pin changed.
hydeDeploy = pkgs.writeShellScriptBin "hyde-deploy" ''
set -u
export PATH="/run/wrappers/bin:/run/current-system/sw/bin:$HOME/.local/bin:$PATH"
state="''${XDG_STATE_HOME:-$HOME/.local/state}/hyde"
stage="''${XDG_CACHE_HOME:-$HOME/.cache}/hyde-nixos/src"
mkdir -p "$state"
for env in python_env lua_env; do
if [ -e "$state/$env" ] && [ ! -L "$state/$env" ]; then
mv "$state/$env" "$state/$env.before-nixos.$(date +%s)"
fi
ln -sfn "/etc/hyde/$env" "$state/$env"
done
if [ "$(cat "$state/nixos-deployed" 2>/dev/null)" = "${hydeSrc}" ]; then
echo "HyDE already deployed for this pin, nothing to do"
exit 0
fi
rm -rf "$stage"
mkdir -p "$(dirname "$stage")"
cp -r "${hydeSrc}" "$stage"
chmod -R u+w "$stage"
deploy() {
group="$1"; shift
${hydePython}/bin/deez --source "$stage" --config "$stage/Scripts/dots-groups/$group.toml" \
dots --skip-git --no-deps-checks --deploy "$@" </dev/null
}
deploy core hyde grimblast xdg-terminal-exec app2unit hyprland wallbash-gtk \
waybar rofi dunst wlogout icon-wallbash \
|| { echo "core deploy failed, will retry next login" >&2; exit 1; }
deploy extra electron-flags baloofilerc dolphin kitty hyprlock hypridle hyprsunset \
fastfetch swaync_config || echo "warning: some extra dots failed" >&2
deploy shell zsh || echo "warning: zsh dots failed" >&2
echo "${hydeSrc}" > "$state/nixos-deployed"
touch "$state/nixos-pending"
'';
# 8. Seeding, step 2 (inside Hyprland): import themes, then apply the current theme.
hydeFirstrun = pkgs.writeShellScriptBin "hyde-firstrun" ''
export PATH="$HOME/.local/lib/hyde:$HOME/.local/bin:/run/wrappers/bin:/run/current-system/sw/bin:$PATH"
export LIB_DIR="$HOME/.local/lib" SHARE_DIR="$HOME/.local/share" HYDE_SHELL_INIT=1
state="''${XDG_STATE_HOME:-$HOME/.local/state}/hyde"
stage="''${XDG_CACHE_HOME:-$HOME/.cache}/hyde-nixos/src"
for _ in $(seq 60); do
sig="$(ls -t "$XDG_RUNTIME_DIR/hypr" 2>/dev/null | head -n1)"
[ -n "$sig" ] && break
sleep 1
done
export HYPRLAND_INSTANCE_SIGNATURE="''${HYPRLAND_INSTANCE_SIGNATURE:-$sig}"
if [ -z "$(ls -A "$HOME/.config/hyde/themes" 2>/dev/null)" ]; then
notify-send -a HyDE "HyDE" "First login: importing themes from GitHub, this takes a few minutes"
"$stage/Scripts/restore_thm.sh" \
|| notify-send -u critical -a HyDE "HyDE" "Theme import failed: journalctl --user -u hyde-firstrun"
fi
source "$LIB_DIR/hyde/globalcontrol.sh"
"$LIB_DIR/hyde/wallpaper/cache.sh" commence -t ""
"$LIB_DIR/hyde/theme.switch.sh" -q
"$LIB_DIR/hyde/waybar.py" --update
rm -f "$state/nixos-pending"
notify-send -a HyDE "HyDE" "Setup finished"
'';
in
{
nix.settings.experimental-features = [ "nix-command" "flakes" ];
# ---- Session: Hyprland under UWSM ----
programs.hyprland = { enable = true; withUWSM = true; xwayland.enable = true; };
programs.hyprlock.enable = true;
services.displayManager.sddm = {
enable = true;
wayland.enable = true;
theme = "catppuccin-sddm-corners";
extraPackages = with pkgs.kdePackages; [ qt5compat qtsvg ];
};
services.displayManager.defaultSession = "hyprland-uwsm";
# ---- User and shell ----
programs.zsh = {
enable = true;
enableGlobalCompInit = false;
shellInit = ''export ZSH_CACHE_DIR="$HOME/.cache/oh-my-zsh"'';
};
users.users.${hydeUser} = {
shell = pkgs.zsh;
extraGroups = [ "networkmanager" "video" "input" ];
};
# ---- Services HyDE enables on Arch ----
networking.networkmanager.enable = true;
hardware.bluetooth = { enable = true; powerOnBoot = true; };
services.blueman.enable = true;
services.pipewire = { enable = true; alsa.enable = true; pulse.enable = true; jack.enable = true; wireplumber.enable = true; };
security.rtkit.enable = true;
security.polkit.enable = true;
services.udisks2.enable = true;
services.gvfs.enable = true;
services.upower.enable = true;
programs.nix-ld.enable = true;
# ---- Fonts and cursor HyDE downloads on Arch ----
fonts.packages = with pkgs; [
nerd-fonts.caskaydia-cove nerd-fonts.jetbrains-mono nerd-fonts.mononoki
maple-mono.truetype-autohint cantarell-fonts noto-fonts-cjk-sans
noto-fonts-color-emoji material-design-icons
];
# ---- Packages ----
environment.systemPackages = with pkgs; [
# system
pavucontrol pamixer networkmanagerapplet bluez brightnessctl playerctl udiskie
# window manager
dunst rofi waybar wlogout grim slurp satty hyprpicker cliphist
wl-clipboard wl-clip-persist hyprsunset hypridle hyprpolkitagent
(if pkgs ? awww then awww else swww)
# dependencies
parallel jq imagemagick libnotify xdg-user-dirs xdg-utils unzip fzf git curl psmisc
kdePackages.ffmpegthumbs kdePackages.kde-cli-tools kdePackages.kimageformats
qt5.qtimageformats kdePackages.qtimageformats gobject-introspection
# theming
nwg-look libsForQt5.qt5ct qt6Packages.qt6ct
libsForQt5.qtstyleplugin-kvantum kdePackages.qtstyleplugin-kvantum
qt5.qtwayland kdePackages.qtwayland bibata-cursors
(tela-circle-icon-theme.override { colorVariants = [ "dracula" ]; })
catppuccin-sddm-corners
# applications
firefox kitty kdePackages.dolphin kdePackages.ark vim nwg-displays fastfetch starship
# HyDE runtimes and custom builds
hydePython hydeLua hydeLuarocks hyprquery hydeDeploy hydeFirstrun
(lib.hiPrio killallShim)
];
environment.etc."hyde/python_env".source = hydeVenv;
environment.etc."hyde/lua_env".source = hydeLua;
environment.pathsToLink = [ "/lib/girepository-1.0" ];
environment.sessionVariables.GI_TYPELIB_PATH = "/run/current-system/sw/lib/girepository-1.0";
# ---- The FHS paths HyDE hardcodes, as links instead of patches ----
systemd.tmpfiles.rules = [
"L+ /bin/bash - - - - ${pkgs.bash}/bin/bash"
"L+ /bin/env - - - - ${pkgs.coreutils}/bin/env"
"L+ /usr/bin/python3 - - - - ${hydePython}/bin/python3"
"L+ /usr/bin/rofi - - - - ${pkgs.rofi}/bin/rofi"
"L+ /usr/bin/xdg-open - - - - ${pkgs.xdg-utils}/bin/xdg-open"
"L+ /usr/bin/kitten - - - - ${pkgs.kitty}/bin/kitten"
"d /usr/libexec 0755 root root -"
"L+ /usr/libexec/hyprpolkitagent - - - - ${pkgs.hyprpolkitagent}/libexec/hyprpolkitagent"
"d /usr/share 0755 root root -"
"L+ /usr/share/wlogout - - - - ${pkgs.wlogout}/share/wlogout"
"L+ /usr/share/oh-my-zsh - - - - ${hydeOmz}"
"L+ /usr/share/zsh-theme-powerlevel10k - - - - ${pkgs.zsh-powerlevel10k}/share/zsh-powerlevel10k"
];
# ---- The two user units that put HyDE in $HOME ----
systemd.user.services.hyde-deploy = {
description = "HyDE: deploy dotfiles into $HOME when the pinned commit changes";
wantedBy = [ "default.target" "graphical-session-pre.target" ];
before = [ "graphical-session-pre.target" ];
unitConfig.ConditionUser = hydeUser;
serviceConfig = {
Type = "oneshot";
RemainAfterExit = true;
ExecStart = "${hydeDeploy}/bin/hyde-deploy";
TimeoutStartSec = "10min";
};
};
systemd.user.services.hyde-firstrun = {
description = "HyDE: import themes and apply the current theme after a deploy";
wantedBy = [ "graphical-session.target" ];
after = [ "graphical-session.target" "hyde-deploy.service" ];
partOf = [ "graphical-session.target" ];
unitConfig = {
ConditionUser = hydeUser;
ConditionPathExists = "%h/.local/state/hyde/nixos-pending";
};
serviceConfig = {
Type = "oneshot";
ExecStart = "${hydeFirstrun}/bin/hyde-firstrun";
TimeoutStartSec = "30min";
};
};
}Purpose of Each Configuration:
- pick: A helper that keeps only the attribute names that exist in the current nixpkgs. This keeps the build from failing when a Python or Lua package gets renamed upstream.
- hydeSrc: Copies the pinned HyDE source into the Nix store and rewrites one line in theme.switch.sh so HyDE looks for themes in your home folder instead of the read-only system profile. The --replace-fail flag stops the build if upstream ever changes that line, so you know the fix needs updating.
- deez: Builds HyDE's own dotfile deployer from the pinned commit. It uses only the Python standard library, so the build is small.
- hyprquery: Builds hyq, the Hyprland query tool that HyDE's theme switcher calls. It is compiled from source with the Hyprland libraries from nixpkgs.
- hydePython: A Python environment that replaces the uv virtual environment HyDE builds on Arch. It includes deez plus the Python modules HyDE's scripts import, such as loguru, pulsectl, pywayland, and pygobject3.
- hydeVenv: Wraps hydePython so it also provides a working activate script. HyDE's scripts source this file before running Python, and a real venv would break inside the read-only Nix store.
- luaBase: Picks a Lua interpreter from nixpkgs, so the same config works whether nixpkgs names it lua5_5 or lua5_4.
- hydeLua: A Lua environment with the modules HyDE's Lua scripts need, such as luasec, luasocket, dkjson, and lgi. It replaces luarocks, which HyDE would normally use to install them.
- hydeLuarocks: Installs a real luarocks binary because HyDE's activate script refuses to start without one on PATH. It is only a presence check; the rocks themselves come from hydeLua.
- zsh256color: A small stand-in plugin that upgrades plain terminals (xterm, screen, tmux) to their 256-color names. HyDE's zsh config asks for the zsh-256color plugin, but it is not packaged in nixpkgs.
- hydeOmz: A merged copy of Oh My Zsh with the three plugins HyDE's zsh config loads: zsh-autosuggestions, zsh-syntax-highlighting, and zsh-256color. Nixpkgs' Oh My Zsh is read-only, so this copy makes the plugin folder writable during the build.
- killallShim: A killall wrapper that also matches Nix's wrapper process names like .waybar-wrapped or .dunst-wrapped. HyDE restarts Waybar, Dunst, and Kitty with plain killall NAME, which fails on NixOS without this shim.
- hydeDeploy: The first-run script that deploys HyDE into your home folder. It runs before Hyprland starts, checks the pinned HyDE commit against the last one it saw, and copies the dotfiles only when the pin changes. That means your theme and your own edits survive reboots and rebuilds.
- HyDE env symlinks: Points ~/.local/state/hyde/python_env and lua_env at /etc/hyde/python_env and /etc/hyde/lua_env. HyDE looks for its environments there, so this step gives it the Nix-built ones instead of a uv venv.
- deploy function: A small wrapper around deez that reads HyDE's dot manifests from Scripts/dots-groups/*.toml and deploys one group at a time, such as core, extra, and shell.
- deploy core: Deploys the core HyDE dotfiles, such as HyDE itself, Grimblast, Waybar, Rofi, Dunst, and the wallbash GTK setup. If this step fails, the script exits and retries on the next login.
- deploy extra: Deploys optional dotfiles, such as Dolphin, Kitty, Hyprlock, Hypridle, Fastfetch, and SwayNC configs. A failure here only prints a warning so the core install still succeeds.
- deploy shell: Deploys HyDE's zsh configuration. A failure here is also a warning.
- nixos-deployed and nixos-pending: Two state files. nixos-deployed records the HyDE commit that was last deployed, and nixos-pending tells hyde-firstrun that there is new work to do after Hyprland starts.
- hydeFirstrun: The second stage of the deploy. It runs inside Hyprland, waits for Hyprland's socket, imports HyDE's theme pack from GitHub on the first run, and then re-applies your current theme, wallpaper cache, and Waybar.
- restore_thm.sh: HyDE's own theme import script. It fetches the theme pack from GitHub, so the first login takes a few minutes and the script shows a notification while it runs.
- theme.switch.sh and waybar.py: HyDE's theme switcher and Waybar helper. They reapply the last theme you picked, so the desktop looks the same after a deploy as it did before.
- nix.settings.experimental-features: Enables flakes and the new nix CLI, which the flake-based rebuild requires.
- programs.hyprland: Enables the Hyprland compositor, starts it under UWSM (which HyDE expects), and turns on XWayland so X11 apps still run.
- programs.hyprlock: Enables Hyprlock, HyDE's lock screen.
- services.displayManager.sddm: Enables SDDM on Wayland with the catppuccin-sddm-corners theme. The qt5compat and qtsvg extra packages are needed because the theme imports Qt5Compat.GraphicalEffects.
- services.displayManager.defaultSession: Sets the default session to hyprland-uwsm, so SDDM logs you straight into the HyDE session.
- programs.zsh: Enables zsh and points its cache directory at your home folder, because Oh My Zsh lives in the read-only store.
- users.users.${hydeUser}: Sets zsh as the shell for your user and adds the networkmanager, video, and input groups HyDE needs.
- networking, bluetooth, pipewire, rtkit, polkit, udisks2, gvfs, upower: The same services HyDE enables on Arch, so its bar, Bluetooth widget, audio controls, automount, and battery widget all work.
- programs.nix-ld: Lets HyDE's prebuilt hydectl and hyde-ipc binaries run, since they are compiled against a standard Linux loader.
- fonts.packages: Installs the Nerd Fonts, Maple Mono, Cantarell, Noto, and Material Design Icons that HyDE downloads on Arch, so the bar and terminal render correctly.
- environment.systemPackages: Installs the base utilities, window manager tools, theming packages, applications, and HyDE's custom builds. Note that HyDE starts Waybar, Dunst, Hypridle, and the others itself, so no NixOS services are enabled for them.
- killallShim with lib.hiPrio: Makes the shim win over the real psmisc killall, so HyDE's restart commands always go through the wrapper.
- environment.etc."hyde/python_env" and "lua_env": Exposes the Python and Lua environments at stable paths under /etc/hyde. /etc survives garbage collection, so HyDE's scripts always find them.
- environment.pathsToLink and GI_TYPELIB_PATH: Links the GObject introspection files into the system profile and sets GI_TYPELIB_PATH, so HyDE's GTK and GObject Python scripts can load their typelibs.
- systemd.tmpfiles.rules: Creates the FHS paths HyDE hardcodes, such as /bin/bash, /usr/bin/python3, /usr/bin/rofi, /usr/share/wlogout, and /usr/share/oh-my-zsh, as symlinks. This means HyDE's scripts run without patching every path.
- systemd.user.services.hyde-deploy: A user service that runs hyde-deploy before the graphical session starts. It runs once per login and skips the deploy if the pinned HyDE commit has not changed.
- systemd.user.services.hyde-firstrun: A user service that runs hyde-firstrun after Hyprland starts, but only when nixos-pending exists. That means it runs after a fresh deploy, not on every login.
❓ Frequently Asked Questions: Installing HyDE Hyprland Dotfiles on NixOS
What are the requirements for HyDE Hyprland dotfiles on NixOS?
You need a base NixOS system installed without any desktop environment, because the HyDE installation overrides the login manager and display server with its own configuration. Your root partition should have at least 30 GB of free space, since the total space after installing HyDE is around 20 GB. You also need an x86-64 processor, at least 8 GB of RAM, a 2015 or newer GPU, and a stable internet connection.
Is HyDE officially supported on NixOS?
There is no official installer for NixOS. HyDE's installer is built for Arch Linux and its derivatives, and its README points NixOS users to a separate project called Hydenix, a home-manager rewrite of HyDE. My approach is different. Instead of rewriting HyDE as Nix modules, hyde.nix runs HyDE's own deez-dots deployer against a pinned HyDE commit, and adds the NixOS fixes HyDE needs (FHS symlinks, Python and Lua environments, a killall shim). The files are on my GitHub at musabase/hyde-hyprland-nixos.
Why do I need to replace the placeholder username in flake.nix?
The flake.nix file sets a placeholder, CHANGEME, in the hydeUser variable. HyDE's deploy services and the user settings in hyde.nix use this name to decide whose home folder to deploy into. If it does not match your real username, the dotfiles go to the wrong user, or never deploy for the account you log in with. The sudo sed -i "s/CHANGEME/$(whoami)/" flake.nix command replaces the placeholder with your actual username automatically.
What does the HyDE setup change on my NixOS system?
It enables the HyDE-themed SDDM login manager, configures Hyprland with HyDE's Waybar, Rofi, and theming components, and pulls the official HyDE repository into your NixOS configuration. The rebuild also installs the packages listed in hyde.nix, including the shell components, fonts, and utilities that HyDE depends on. NixOS keeps every generation, so you can roll back with nixos-rebuild switch --rollback if needed.
Why does the installation take around 20 minutes?
The rebuild downloads the official HyDE repository and its dependencies, evaluates the NixOS configuration, and builds the packages that are not available as prebuilt binaries. On my PC, the whole process took roughly 20 minutes. On a slower connection or less powerful machine, expect it to take longer.
What should I do if the rebuild fails?
First, check the error line in the terminal output. A common issue is a wrong username in flake.nix. Check that hydeUser matches the output of whoami, which the sed command in Step 1 fixes. If the error mentions a missing package or a flake evaluation problem, include the exact error line in a comment below and I will point you to the fix. You can also try re-running the rebuild command, because NixOS caches completed build steps.
Can I edit HyDE's configuration without rebuilding NixOS?
It depends on what you want to change. System-level settings in hyde.nix and flake.nix require a rebuild. Once HyDE is running, its runtime theming and appearance settings can be changed through HyDE's own tools and keybinds. To apply system-level changes, edit the .nix files and run the same rebuild command again.
How do I uninstall HyDE from NixOS?
Uninstalling takes two parts, because HyDE changes both the system and your home folder.
1. Revert the system. Run sudo nixos-rebuild switch --rollback or pick the previous generation from the boot menu. This undoes everything in hyde.nix, including Hyprland, SDDM, the services, and the packages. If you want it gone for good, delete flake.nix and hyde.nix from /etc/nixos and rebuild.
2. Remove the dotfiles from $HOME. A rollback does not touch these, because hyde-deploy copied them into your home folder. Back them up first, then delete:
mkdir -p ~/hyde-backup
mv ~/.config/hypr ~/.config/hyde ~/.config/waybar ~/.config/rofi \
~/.config/dunst ~/.config/wlogout ~/.config/kitty ~/hyde-backup/
mv ~/.local/share/hyde ~/.local/state/hyde ~/.local/lib/hyde ~/hyde-backup/
rm -rf ~/.cache/hyde-nixosHyDE also writes a ~/.zshrc and other app configs (Dolphin, Fastfetch, Hyprlock, and so on). Check ~/.config for anything HyDE added that you want removed. Moving folders to a backup first is safer than rm -rf.
What are the essential HyDE keybinds I should learn first?
The ones you will use most are Super + Q to close a window, Super + T for the terminal, Super + Shift + T to open the theme selector, and Super + / for the keybind cheatsheet. The theme switcher is HyDE's signature feature, and it changes the wallpaper, colors, and bar style together. The SDDM login screen stays on catppuccin-sddm-corners in this setup, because hyde.nix sets it declaratively.
HyDE Hyprland Dotfiles on NixOS: Up and Running
HyDE's theme-rich Hyprland desktop is now running on your NixOS system, with its themed SDDM, Waybar, and 70+ built-in themes sitting on top of a declarative configuration. The whole setup lives in two .nix files and a flake, so updating or reverting it is a single rebuild away. That is the NixOS advantage: you get HyDE's visual variety without losing the ability to roll back, version control, and rebuild your entire desktop from code.
If HyDE brought a fresh look to your NixOS desktop, stay tuned. MusaBase has more Linux, BSD, and virtualization guides in the pipeline.
1o1 out, I'll see you in the next one!