Beginner's guide (non-technical)

Hello Nix community!

I’m a newcomer taking the first steps to enter the Nix universe, struggling to climb the steep learning curve.

There are multiple sources of information and plenty real configurations being shared. Frequently the information is too technical, assumes broad knowledge, applies to specific versions (unidentified), or is plainly outdated. The shared configurations are complex, representing complete setups in production, without any explanation how they evolved into their current status.

I want to learn Nix enough to understand how the system works and the best way to manage it, up to the point of being comfortable to write a beginner’s guide targeting non-technical people. It will be my humble contribution.

I will be asking questions in this forum to learn, validate my understanding, and solve problems. Oftentimes they may sound too naive to expert members, but I will do the homework before asking. The main objective is to fight the cargo cult of copy and paste without reasoning.

The target system will be macOS with nix, nix-darwin, and home-manager, adopting a flake-based configuration from the beginning.

Yes, flakes is an experimental feature. I’ve read a lot about Nix history and its evolution, including flakes. I reckon that flakes is the future of Nix and mature enough to warrant a non-technical beginner’s guide.

If you know of relevant resources addressing this level of information that I might have missed, please don’t hesitate in pointing me there.

Thank you all in advance!


A variety of people have written similar documents to the one you’re planning :slight_smile: They’re generally on github, but usually on the topic of NixOS rather than mac OS, so that should be interesting.

I think the problem is more the distributed nature of all this documentation. For the average person, if it’s not on stackoverflow, it may as well not exist, and this is doubly so if even I can’t point you at prior art.

That said, these are the reference works I consider most important to have a thorough understanding of if you want to learn nix related things:

  • NixOS 23.11 manual | Nix & NixOS
    • The configuration syntax primer. Nix is a programming language, sure, but if you stick to only configuration you can get away with only knowing these basics.
  • NixOS Search
    • This is your replacement for the arch wiki on nixos. If a pre-made option doesn’t exist, and just installing the packages into environment.systemPackages doesn’t work, consider yourself in uncharted territory. Especially if you’re following installation docs from a project upstream instead of using options or a package.
    • Your replacement for the above when using home manager.

Those are the basics. I believe them to be quite easy to follow even for not very advanced users, assuming you have some prior experience with unix systems. After all, you really can just copy paste stuff as log as you stick to options only (and slowly learn the nix syntax while you do so).

It does, however, limit you to only those things already perfectly prepared to run on NixOS, and you’ll very quickly run into that one thing you can’t do this way. Especially if you’re a developer yourself, since you won’t be able to make your own code work with this. Many people give up at this point, since “ubuntu is so much easier” (ignoring the fact that it is only so because upstream projects are designed to work with ubuntu first and foremost for obvious historical reasons, making ubuntu arguably even harder in the reverse world), and that’s where all the hate articles and claims of difficulty come from :wink:

This is where the learning curve does get a bit steep, because you actually need to learn how to package software, what building software even means, and understand the quirks and features of nix and the NixOS distro (yes, even when you’re on mac OS. I’d say especially when you’re on mac OS). If you don’t know what a systemd is you’ll get lost pretty quickly. Either way, this is when you start pulling out these things:

  • Nixpkgs 23.11 manual | Nix & NixOS
    • Especially the sectons on the “standard environment” and “builders”. This goes beyond basics, but if you were unhappy about being restricted to what’s in nixpkgs, this is what you need to learn.
    • Yes, there are three official manuals. This one covers the actual syntax in detail, because by the time you start packaging you need to understand it.
  • Nix Pills | Nix & NixOS
    • Parts of this are very technical. Parts of it explain in excruciating detail how stuff works that you should never use in this form. Only read this after you’ve written at least one or two packages using the stdenv, but once you have, this will explain everything, and suddenly nix will make sense. Read the whole thing, this is not a good document to skim. It’s like an updated, simpler version of eelco’s thesis.
    • Very good reference for a lot of the more advanced topics, and has my favorite listing of nix antipatterns.
    • If you like learning from blogs, xe is probably the best nix related blogger out there.

But yes, this gets pretty messy. You might notice that the “intermediate” documentation is a little missing. You might also notice that it’s spread out, in the form of references rather than howtos, and finding an answer to “how do I change the firefox version I’m using” is hard.

This is where the nix documentation is sadly lacking, and while lots of people write blog posts and github gists and such, it’s hard to coordinate this effort. Ultimately a lot of it ends up here on the discourse, in answers by the very people who maintain nixpkgs (and occasionally yours truly), but obviously it’s borderline impossible to index and search here.

Tweag has recently announced they will be writing a nix “book” akin to the rust one, so I’m hopeful the situation will improve :slight_smile:

My final note is that is probably worth a look either way. It’s a good place for documentation efforts that aren’t references, but it’s naturally become more “advanced” than what I think is required.


Thank you for taking the time to write such a comprehensive reply.

Indeed there are many introductions and getting started guides. Like you say, they mostly cover NixOS and are scattered around the internet. Most often they miss contextual information, providing guidelines or workarounds that are not applicable to current versions, for example. I hope to improve on that, focusing on the described target system.

The initial enthusiasm with Nix quickly faded away when sifting through the available documentation (official and non-official). It felt like tumbling down the rabbit hole, going deep into the low level details in order to solve minor issues. It’s even more overwhelming for a non-technical person, but it doesn’t have to be this way…

I will try to make the simple things easy. I want to provide some fences to new users in order to guide them through a safe path, and to allow them to learn incrementally along the way. For example, bootstrapping a fresh installation and installing and configuring a couple available packages must be clear and flawless.

Exactly! I quickly realised that a great amount of wisdom from Nix and NixOS experts needs to be put in words and curated into accessible documentation for non-experts.

The resources you’ve pointed me to certainly are a great help, especially with the explanation of what they cover and how they relate to each other.

I have a long journey ahead before being able to produce something useful. :crossed_fingers:

Darwin is always extra trouble mainly because of apples proprietary software and there need to change core mechanics in the OS way to often. Using nix on Linux is easier (to learn) and saves you from head twisting Darwin specific issues.

True! The more ingredients we add to the mix harder it gets to achieve a properly working system.

I’ve seen a number of shared configurations (most quite complex) of macOS with Nix and related tools apparently working well together. People have figured it out and managed to overcome the major roadblocks. Unfortunately, very little documentation exists to explain how to get there…

A macOS based system will have its quirks for sure. Still I think the best way to identify and fix those issues is to have a direct hands-on approach while discovering the Nix universe.

Seriously, Darwin users are second-class in the Nix community. We cannot support Darwin at the same level as Linux and if it approached that Apple would probably interfere. As someone on the Linux side I see more incentive to impeded rather than aid Darwin users.