Setting up your dotfiles with home-manager as a flake

Home Manager is a great project to make managing your dotfiles via Nix super nice and easy. However, there is not a ton of documentation out there explaining how to use home-manager in a standalone way with flakes. I assume most people using flakes and home-manager simply use NixOS; although using home-manager standalone there is a good idea because you do not need to rebuild your whole system to change your Vim or shell config.

I found it a little difficult to figure out so here are some notes/snippets that hopefully helps others. I hope to come back to this post over time and make it a little easier to read, but hopefully official docs and etc simply get better to make it not needed.

To start, I followed the instructions here: Declarative management of dotfiles with Nix and Home Manager

But, they seem to be out of date or something because it didn’t work for me.

  1. The command to get things built and running is different and you need to pass --flake . in the flake directory
  2. You need to remember/know to restart your shell
  3. The way to specify where ./home.nix and how to write home.nix has changed.

Errors you may see:

  • “NIX_PATH unset” : This is because you’re using the wrong command and do not have channels setup. Using the right command will fix this without using channels
  • “home.nix no configuration found” : This is likely related to using the wrong command and not telling it to use your flake

Creating basic home-manager flake configuration

  1. Setup your ~/.config/nix/nix.conf to allow flakes
# ~/.config/nix/nix.conf
experimental-features = nix-command flakes 
  1. git init and nix flake init in your dotfiles repo
  2. Setup your basic flake.nix like this:
    description = "My Home Manager Flake";

    inputs = {
        nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
        home-manager = {
            url = "github:nix-community/home-manager";
            inputs.nixpkgs.follows = "nixpkgs";

    outputs = {nixpkgs, home-manager, ...}: {
        defaultPackage.x86_64-linux = home-manager.defaultPackage.x86_64-linux;
        defaultPackage.x86_64-darwin = home-manager.defaultPackage.x86_64-darwin;

        homeConfigurations = {
            "your.username" = home-manager.lib.homeManagerConfiguration {
                # Note: I am sure this could be done better with flake-utils or something
                pkgs = nixpkgs.legacyPackages.x86_64-darwin;

                modules = [ ./home.nix ];

Some notes:

  • Other posts tell you to put more in your home configuration of the flake.nix but that is the old way of doing things
  • On Apple M1/M2 systems you’ll probably want to have the x86_64 version installed and use that. If not you need to add support for that by specifying it.
    • An aside: You can use flake-utils to manage which systems are supported and etc.

Your home.nix should look like this

{pkgs, ...}: {
    home.username = "your.username";
    home.homeDirectory = "/home/your.username";
    home.stateVersion = "22.11"; # To figure this out you can comment out the line and see what version it expected.
    programs.home-manager.enable = true;
  1. Run nix run . switch -- --flake . to build and setup home-manager. **Restart your shell or run exec $SHELL -l.
  2. Modify home.packages in home.nix to add new packages to your environment.
{pkgs, ...}: {
    home.username = "your.username";
    home.homeDirectory = "/home/your.username";
    home.packages = [
    home.stateVersion = "22.11"; # To figure this out (in-case it changes) you can comment out the line and see what version it expected.
    programs.home-manager.enable = true;

Now you can refer to the home-manager docs for other configuration options (of which there are many).

In the future I may write a post about my dotfiles and suggestions for others once I’ve had a chance to work on it a bit.