Home Manager files and symbolic links

What is home.file?#

Sometimes you encounter less-common software for which Home Manager’s programs provides no dedicated options. In that case, you can use the home.file attribute to declare a file link at a specific location in your home directory.

1. Basic usage

{
  home.file.".config/my-app/config.txt".text = ''
    setting1=true
    setting2=false
  '';
}

• Result: Home Manager creates a symbolic link under ~/.config/my-app/ pointing to a read-only file in /nix/store.

2. Referencing local files in the project

If you already have a collection of .conf files and do not want to rewrite them in Nix:

{
  home.file.".bashrc".source = ./dotfiles/bashrc;
}

XDG Base Directory (the modern approach)#

For modern Linux applications, use xdg.configFile rather than working directly at the root of the home directory.

{
  xdg.configFile."kitty/kitty.conf".text = "font_size 12.0";
}

This automatically places the file at ~/.config/kitty/kitty.conf.

The executable and recursive options#

• executable = true;: when linking a script, this option ensures it has execute permission.
• recursive = true;: links the files in a directory individually; the default, false, links the target directory as a whole to the source directory. Both approaches can manage directories.

Why did my configuration file become “read-only”?#

This is Home Manager’s default behavior.

• Reason: the Store file the link points to generally cannot be edited directly. If you replace the link with a regular file, the next activation may refuse to overwrite it because of a file conflict. Make changes in the declarative source.
• Lesson: always edit your .nix configuration rather than the file exposed through a /nix/store symlink.

A practical tip: a transitional approach#

If you are not ready to convert hundreds of lines of Nvim configuration to Nix:

1. Place your .config/nvim folder inside your Nix configuration directory.
2. Link the entire directory with home.file.".config/nvim".source = ./nvim;.
3. When you have time later, gradually split it into separate Nix modules.