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.


Hi there, I just wanted to say thank you for putting this together! This is what helped me to finally wrap my head around, and subsequently convert my configuration to use flakes :slight_smile:

Now I’m putting together a central repository for my systems where I’m building on my desktop and deploying to each machine.

Next step… figuring out how I’m going to encrypt secrets so I can stick my config in a repo somewhere!


It’s down now unfortunately.

I’m able to access it.

You’re right, it seems Hagezi Ultimate blocks dubious domains like I created an exception for

1 Like

Thanks for the info, @linyinfeng and me are working on this - #2194 blocks many innocent personal websites · Issue #2360 · hagezi/dns-blocklists · GitHub, and Hangezi has fixed the issue by #2360 · hagezi/dns-blocklists@424c84c · GitHub

1 Like

Hi, I am following along this tutorial, but i got stuck running rebuild after adding the flake.nix:

$ sudo nixos-rebuild switch
error: flake 'path:/etc/nixos' does not provide attribute 'packages.x86_64-linux.nixosConfigurations."nixos"', 'legacyPackages.x86_64-linux.nixosConfigurations."nixos"' or 'nixosConfigurations."nixos"'

I’ve tried googling this error but haven’t found anything helpful. I’ve reviewed your guide and I don’t think I’ve missed anything.

@quinnn: It will probably help to post your flake.nix if you want to increase the chances of anyone being able to help. My guess is that your HOSTNAME is nixos but you don’t have a line like nixosConfigurations.nixos = nixpkgs.lib.nixosSystem in your flake.nix? Note that the book uses the example = .... When running just nixos-rebuild, it will try to find a key in the nixosConfigurations attribute set matching your hostname.

Take another look at flake.nix Configuration Explained | NixOS & Flakes Book, I think it will help you.