An unofficial NixOS & Flakes book for beginners


@ryan4yin absolutely wonderful, this is exactly what we need. A more detailed resource on all things new cli and flakes.

I quickly glimpsed over it, what I noticed is that there are quite a lot of spelling and grammatic mistakes, so you might want to correct that.

Other than that I love the idea, and I really like how much is already covered in that book. I hope there will be many more people who contribute to it, so it can become a bigger, up-to-date and best practice resource we did not have yet.

There was basically only zero-to-nix, but that was not comprehensive at all.


EDIT: I have just made a lot of optimizations to the book.


I began just few weeks ago with this wonderful distro, but I was puzzled by the fact that all the docs I found were about traditionnal configuration.nix and all the valuable examples I found were about Flakes.

Just, your preface help me a lot, I can’t wait to read the whole book. It’s the doc I was looking for. Many thanks.

1 Like

Can please clarify about using overlays for downgrading packages?

In your book you use specialArgs to make stable repository available to modules. But the official wiki advises to use overlays:

outputs = { self, nixpkgs, nixpkgs-unstable }:
      system = "x86_64-linux";
      overlay-unstable = final: prev: {
        unstable = nixpkgs-unstable.legacyPackages.${prev.system};
        # use this variant if unfree packages are needed:
        # unstable = import nixpkgs-unstable {
        #   inherit system;
        #   config.allowUnfree = true;
        # };

    in {
      nixosConfigurations."<hostname>" = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          # Overlays-module makes "pkgs.unstable" available in configuration.nix
          ({ config, pkgs, ... }: { nixpkgs.overlays = [ overlay-unstable ]; })

See here: Flakes - NixOS Wiki

I’m just a beginner, can you please describe the difference?

Yes, the overlays given by the nixos wiki and the specialArgs given by me both accomplish the same thing.

I chose to use specialArgs because I think it’s a bit more understandable and user-friendly. It took me a while to figure out how overlays work.

Technically I don’t see any advantage or disadvantage to either way, it’s up to you which one you prefer to use.


I just wanted to say, this is an excellent piece of work.

I had somehow missed this announcement thread, and perhaps others have too given the lack of comments. But I found the book via a fedi post a few weeks ago.

This is what a user-journey-focused introduction (through to quite advanced!) guide should look like. Truly great work and something I will recommend heartily.