Update: I’ve published my nix dotfiles for you to be inspired (as well as see what I actually do versus the simple versions of a blog post.)

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 Link to heading

  1. Setup your ~/.config/nix/nix.conf to allow flakes

    # ~/.config/nix/nix.conf
experimental-features = nix-command flakes

  2. git init and nix flake init in your dotfiles repo

  3. 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, ...}: {
        # For `nix run .` later
        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 = import nixpkgs { system = "x86_64-darwin"; };

                modules = [ ./home.nix ]; # Defined later
            };
        };
    };
}

Some notes:

  • This example assumes you’re on a macOS machine and you want to use the x86_64 architecture.
    • To use it on x86_64 linux change -darwin to -linux.
  • Other posts you may find on how to setup home-manager with flakes will tell you to put more options in homeConfigurtions."your.username", but that was the old way of doing things and these are the only options are needed.
  • On Apple M1/M2 systems many recommend using x86_64 with Rosetta, but you can install it natively using aarch64 just fine.
    • An aside: You can use flake-utils to manage which systems are supported and etc.
    • It is possible to configure an x86_64 nixpkgs to allow to access x86_64 packages to use with rosetta when/where needed.

Home manager config Link to heading

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 . -- build --flake . to build the home-manager config.

    If you see an error about “does not provide attribute” make sure to match the name of your user to the places it says your.username in the examples.

You can look in the ./result/ folder to see what it build and what config files you’ll have. It’s worth exploring this folder a bit.

  1. When building works you can try to activate the new configuration using switch: nix run . -- switch --flake . Then restart your shell or run exec $SHELL -l.

    nix run . -- switch is short for home-manager switch later. -- helps it understand which flags are for nix run vs to pass into home-manager switch.

  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 = [
        pkgs.nixpkgs-fmt
        pkgs.cowsay
    ];
    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;
}

If you have reloaded your shell you can apply these changes by saying home-manager switch --flake . in the root of your flake files.

Because we’re using flakes we must tell home manager which flake we’re referring to unlike before where it assumed where the config file would be.

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.

I’ve published my dotfiles which you can look at as an example