NixOS Dotfiles: Symlinks, GNU Stow, Home Manager, and Where Flakes Fit

ByPriya Nair

If you’re running NixOS with flakes, you don’t need to put flake.nix in /etc/nixos/ or create a symlink there. The nixos-rebuild command accepts a --flake flag that points to any directory on your machine:

sudo nixos-rebuild switch --flake ~/.dotfiles#your-hostname

That single flag means your entire config — flake.nix, flake.lock, hardware-configuration.nix, home.nix, the lot — can live in ~/.dotfiles as a normal Git repo. The book’s suggestion of /etc/nixos/ reflects where NixOS looks by default when you don’t pass the flag. With flakes, that default no longer applies.

Stow vs ln: what actually makes sense here

GNU Stow mirrors a package subdirectory into a target directory using symlinks. If you have ~/.dotfiles/starship/.config/starship.toml, running stow starship from inside ~/.dotfiles creates the link automatically. Elegant when all your targets share one root — typically $HOME.

The friction in the setup from the original thread is that it targets two different roots: /etc/nixos/ and ~/.config/. Stow handles one target directory per invocation, so mixed-target layouts get awkward. Plain ln -sf calls in a small shell script are often less noise to maintain in that situation.

That said, if you adopt the --flake approach described above, most of the /etc/nixos/ symlinks disappear entirely. You’d only be managing home-directory files — which is precisely where Stow earns its keep.

Home Manager makes most of this moot

You already have home.nix. Home Manager’s home.file option declares symlinks directly in Nix, no separate tool needed:

home.file.".config/starship.toml".source = ./starship.toml;

After home-manager switch, the link exists. Home Manager tracks it, and if you remove the declaration later it cleans up the link too. This is the lowest-friction path if you’re already invested in the Home Manager ecosystem — it’s one fewer tool to remember.

The /etc/nixos/ targets are the exception. Those need root, and Home Manager won’t touch them. But with nixos-rebuild --flake ~/.dotfiles, those files don’t need to live in /etc/nixos/ at all. Your NixOS modules reference them by relative path inside the dotfiles directory.

Combining everything above, a structure that needs almost no manual symlink management looks like this:

~/.dotfiles/
├── flake.nix
├── flake.lock
├── nixos/
│   ├── configuration.nix
│   ├── hardware-configuration.nix
│   ├── gnome.nix
│   ├── hdd.nix
│   ├── pcloud.nix
│   └── vm.nix
├── home-manager/
│   └── home.nix
└── starship.toml

In flake.nix, your nixosConfigurations output references ./nixos/configuration.nix by relative path. In home.nix, home.file places starship.toml where it belongs. The /etc/nixos/ directory stays empty — or holds a single symlink to the dotfiles root if you’re used to editing from there.

If you’re not ready to commit to all of this and just want to keep the current symlink setup working, a short shell script with ln -sf calls is easier to audit than a full Stow installation for a mixed-target case. Stow’s real advantage shows up when your targets converge on $HOME and you have enough packages to make the automation worthwhile.

Similar Posts