Migrating from NixOS channels to Flakes

Add this to your config and do your nixos-rebuild routine:

nix.settings.experimental-features = [ "nix-command" "flakes" ];

Use GitHub, Gitlab, or whatever if you like… or just do something local-only:

mkdir ~/nixos-conf
cd ~/nixos-conf
git init

You can start completely from scratch if you like:

nix flake init

…but that's not really why you're here. Instead of staring at a mostly-empty nano window (I see you), you can start from a more fully-fledged template. I recommend Misterio77's minimal starter config.

nix flake init -t github:misterio77/nix-starter-config#minimal

The template is pretty thorough, but you'll have to fill out some details appropriate to your scenario. The template helpfully marks the couple of changes that need to be made with FIXME and TODO so crack open your favorite editor, search for FIXME and TODO and get to fixin'. A more detailed treatment of this can be found at the starter config link mentioned above.

Personally, I don't like managing home-manager separately from the broader system, so I followed Misterio77's advice to merge it into my system configs.

Common gotcha: flakes tooling sees the world through git. If a file isn't being tracked, nixos-rebuild won't reference it.

git add --all

This is roughly equivalent to updating your channel. I'll explain a bit more later.

nix flake update

nixos-rebuild build --flake .#your-hostname

Note: You can safely ignore any warnings about your build being "dirty" - this just means you have changes you haven't committed in git yet.

This test build, if successful, will produce a symlink named result in the directory you ran the command from. You can safely rm this symlink. You might consider adding result to your .gitignore (optional).

Don't want to lose a good thing, right?

git commit -a -m "first post!"
git push # assumes you've got a remote to push to

How do you run this thing? Updating/upgrading looks something like this (should look familiar):

1. Make edits to the configuration.nix in your repo (e.g. to add a new package)
2. nix flake update <- if you want to pull more recent versions of things
3. git commit -a -m "BAM!" && git push
4. sudo nixos-rebuild switch --flake .#your-hostname

If you've decided to use a public GitHub or Gitlab repo as a remote, you can reference your flake(s) directly from other machines. This means that to reinstall your machine completely from scratch, you can boot a vanilla NixOS install image, do your partitioning as normal, then magic:

sudo nixos-install --flake github:YourGithubUsername/YourFlakeRepo#your-hostname

You don't have to clone your repo or futz about pointing curl at some random URL – you just install straight from your repo.

It's easy to adapt your new setup to be useful on more than one machine. Take a look at this section in your flake.nix:

nixosConfigurations = {
  your-hostname = nixpkgs.lib.nixosSystem {
    specialArgs = {inherit inputs outputs;};
    modules = [./nixos/configuration.nix];
  };
};

If you had two identical machines that are identically partitioned, you could possibly get away with doing something like this (depending on how your hardware-configuration.nix is written):

nixosConfigurations = {
  your-hostname = nixpkgs.lib.nixosSystem {
    specialArgs = {inherit inputs outputs;};
    modules = [./nixos/configuration.nix];
  };
  your-second-hostname = nixpkgs.lib.nixosSystem {
    specialArgs = {inherit inputs outputs;};
    modules = [./nixos/configuration.nix];
  };
};

But of course, you don't have two identical machines². You probably have some set of things you want to share across machines (e.g. installing/configuring your favorite editor) and some things that are decidedly machine-specific (e.g. networking.hostId). Here's how to get to the "shared stuff is shared; machine stuff is split" promised land:

cd ~/nixos-conf # or wherever your repo root is
mkdir -p nixos/{your-hostname,your-second-hostname,common}
mv nixos/configuration.nix nixos/your-hostname/default.nix
mv nixos/hardware-configuration.nix nixos/your-hostname

Note: default.nix has a special meaning to nix – if some .nix expression references a directory without specifying a filename, default.nix will be used automatically if it exists.

Create a new file, nixos/common/default.nix, and pull common config items out of your existing system's config.

{ inputs, lib, config, pkgs, ... }: {
  services.emacs.enable = true;

  # other config you want to share goes here
}

Now you reference this common config in each system you want to share with.

nixos/your-hostname/default.nix:

{ inputs, lib, config, pkgs, ... }: {
  imports = [
    ../common
  ];

  # the rest of your system config goes here
}

Repeat this exercise for each system.

Finally, update your flake.nix:

nixosConfigurations = {
  your-hostname = nixpkgs.lib.nixosSystem {
    specialArgs = {inherit inputs outputs;};
    modules = [./nixos/your-hostname];
  };
  your-second-hostname = nixpkgs.lib.nixosSystem {
    specialArgs = {inherit inputs outputs;};
    modules = [./nixos/your-second-hostname];
  };
};

Don't forget to add your new files to git and/or commit them! As noted above, this is a pretty common gotcha that folks run into when first starting out with flakes. If you're ever seeing error messages indicating that a file doesn't exist, but you know it does, in all likelihood you've forgotten to git add it.

Why do flakes behave this way? Well, part of the point of flakes is to avoid depending on any state that can vary at build time without being detected – we want that reproducibility. The Nix language can reference environment variables and arbitrary files, and can be influenced by other outside state. By limiting the view of the world down to what's in the git repo, we can greatly improve our ability to define software that builds exactly the same across machines and in different environments.

Anyways, now that you've gotten everything in git, you can manage both machines from the same flake as you would normally (except, of course, you specify the host name when you nixos-rebuild).