Dawn contributing to Nix Modules documentation

I’m going to begin figuring out what it is I can do to contribute to the documentation of what is apparently termed Nix Modules.

I will treat this post like a diary on the matter. But public. The verbosity might make it unappealing to anyone but me.

If you happen to be reading this for some reason and feel like contributing a little tip here and there — I would appreciate it.

Otherwise, don’t let me waste your time.

My next task seems to be: read the Documentation Team meeting notes from the past 1–2 months. Onward.

Unfinished business:

1 Like

Never heard of those… Do you mind elaborating on what this seemingly coined term refers to?

I understood that they are the module system that we may be familiar with from NixOS. I suppose that’s the imports attribute.


  1. 2023-04-27 Documentation team meeting notes #44
  2. 2023-05-04 Documentation team meeting notes #45
  3. 2023-05-08 Documentation team meeting notes #46
  4. 2023-05-11 Documentation team meeting notes #47
  5. 2023-05-15 Documentation team meeting notes #48
  6. 2023-05-18 Documentation team meeting notes #49
  7. 2023-05-25 Documentation team meeting notes #50
  8. 2023-06-01 Documentation team meeting notes #51
  9. 2023-06-05 Documentation team meeting notes #52
  10. 2023-06-08 Documentation team meeting notes #53
  11. 2023-06-12 Documentation team meeting notes #54
  12. 2023-06-15 Documentation team meeting notes #55
  13. 2023-06-19 Documentation team meeting notes #56
  14. 2023-06-22 Documentation team meeting notes #57
  15. 2023-06-26 Documentation team meeting notes #58

Indeed all references to that I am aware of talk about it at the “nixOS module system”, rather than “nix module system”.

This is where my confusion stems from.

I agree that coining a new term that finds its way into official glossaries and doesn’t imply dependency to NixOS would be a good thing.

Though “nix modules” might be sound to much as if there was some native support for them in nix itself, while “nixpkgs modules” again would feel weird, as nixpkgs itself doesn’t use them at all (but in fact provides them as part of its “stdlib”).

1 Like

Would it make more sense that what was suggested that I contribute to is not whatever is behind the imports attribute and instead it is whatever abstracts NixOS modules? Or perhaps are these two parts of the same mechanism?

Generally it’s called the “module system”. It’s not tied to any packages from Nixpkgs nor tied to NixOS

Currently @roberth and me are maintaining it

1 Like

Brilliant. Thank you for chiming in. I don’t know what to ask you yet.

First mention of module system in documentation team meetings says regarding NixOS Manual:

Very minimal module system docs are in here, probably shouldn’t even be in the NixOS manual, since it’s not specific to NixOS

And mentions this PR: Module system documentation refactor by spacekookie · Pull Request #526 · NixOS/nix.dev · GitHub

And that’s it. I used text search for module in all of those notes and found only those items.

So, let’s take a look at that PR…

Before that, current thoughts:

  1. The Nix module system (or whatever it is called) should be documented somewhere canonical. Canonically.
  2. There should be mention of it and how NixOS uses it in the NixOS manual.

So, I’d be interested in seeing:

  1. What documentation currently exists for the Nix module system, whether it is in the NixOS manual or in a canonical location of its own or elsewhere.
  2. What documentation exists for how NixOS uses this module system in its manual.

A desired vs. existent check, I suppose.

I’ve recently got involved with the docs team, and I think the module system is an area where I could be particularly helpful.

Indeed the goal would be to have good documentation for it as a standalone project independent of NixOS. (Although an occasional reference would be ok, these must not be required for understanding)

What documentation currently exists for the Nix module system

It’s split between

  • Nixpkgs manual (only since recently, very incomplete, just evalModules reference documentation)
  • NixOS (fairly NixOS focused, but some parts can be moved over without much editing)
  • Code and code comments. The manuals are arguably incomplete, and the code contains some user facing info.

The latter should of be mostly replaced by URLs and references to .md files.
What should remain of the docs in the NixOS manual is probably not a lot, because we want to move non-reference (and non-explanation?) docs out of the manual, into nix.dev.

I don’t think it’s an easy task to pick up, but if you have the time we can come up with a plan. I think it’d be crucial to work out the concepts and types first, so that the reference documentation will be consistent, and we’ll have a good foundation for further docs.


Thank you for summarizing. I have a few hours per day during this and the next two weeks. Then, Summer of Nix begins, which may decrease this to one hour a day for that duration. Possibly adding some more during weekends.

Does that sound alright? I’d love your help figuring out a plan, as much as you’d be willing to.


Alright. Discovering the Nix module system existing documentation. So, where is the repository?

One part of it seems like the options system, which seems to live here.

This seems to be currently documented in the source code. So I suppose that that’s the source of truth. So, ideally, we’d consume that truth and produce documentation. Auto-generated Nix documentation is not a new idea. I wonder what it would take to implement. And I wonder what progress has been made towards it.

The other part of the Nix module system seems to live here.

The same applies. Reference documentation could be generated from source. It should be, I suppose.

Since I’m not going to solve this problem in this context, I suppose we could see the source as reference documentation, instead of copy-pasting into some documentation. I don’t like duplication of truths. It carries high risk of de-sync between source and copy.

So, if I’m not to produce reference documentation, I should take a look at the higher level documentation.

Would it make sense to begin documenting the Nix module system in nix.dev ?

Yes, as you say anything but reference should go to nix.dev. But we could also have a design document in Nixpkgs right next to the code and import it into the manual, to help readers navigate and understand the code.

Exporting doc comments sensibly probably requires a refactoring given how nixdoc currently works.

1 Like

If I was to move, with appropriate modification (which I don’t know yet) Writing NixOS Modules from the NixOS manual to nix.dev, would the NixOS manual be worse off in any significant way? Would it lack something important about modules?

We should not just move around large chunks of documentation, but rather go very carefully and try to understand what’s wrong with a given piece and improve it incrementally in place. I recommend starting with obvious changes such as completing and structuring parameter listings. The scalable approach to that is documenting library functions in the code and collaborating with @pennae and @sternenseemann on figuring out how to sensibly develop nixdoc to make best use of in-code documentation.

What also works but takes more time to produce results is improving the conceptual introductions to get them right. While the module system is a generic mechanism, that chapter is highly specific to NixOS. We should instead start documenting the mechanism separately, for example on the Nixpkgs manual. Exposing the library there in more detail would be a good way to do that. I remember @roberth had a pull request in that direction.


The Nix Community’s module system is a type system with docstrings and a lattice value priority resolver *.

Form first principles, I found one paragraph of lattice theory e.g. from wikipedia extremely helpful.

I noticed that this is at the core of the module system when studying the cue-lang documentation. :smile:

* sort of every configuration management system is in better or worse ways. Nix Community’s solution is one of the better ones, which has been the trampoline in which nickel happened.

And what would this discussion contribution be without a shameless, but imo helpful, contextual plug:ninja:


With regard to making the best use of in-code documentation, does anyone here feel that https://github.com/NixOS/rfcs/pull/145 is going towards being a solution for that?