NixOS pain points — newbie-gone-intermediate experience report


Given that I just fleshed this out in a random reply on reddit, I thought I could copy&paste it here in case anyone’s interested. For background, those are some pain points I personally have with NixOS (partly applies to non-OS nix+nixpkgs usage too), after experimenting with it for some time on a spare computer at home.

Please note I’m fully aware of the huge Nix/NixOS advantages. I don’t list them here, because we all know them. This is in no way meant as an “attack”, “flame/flame war” or whatever; sorry if you find it harsh, you can just ignore this post. I just thought some people may understand the value of some harsh but honest experience report of a newbie-gone-intermediate NixOS user. To repeat, I totally know of NixOS advantages; those are what has drawn me to Nix/NixOS, made me experiment, and still makes me want to experiment at home. But notably, those are points which especially make it difficult for me to currently recommend NixOS at my workplace.

Without further ado, in no particular order (but numbered for easier reference):

  1. multiple stacked variants of legacy approaches to various stuff & configuration (the “lava layer antipattern”) in nixpkgs; good example of the problem is vim;
  2. some areas are poorly documented (notably with cross-compilation I felt on my own, even the people on the mailing list could not help me with some non-trivial cases); the Nix & NixOS manuals are awesome and indispensable, but I quickly found out that soon afterwards you have to just dive in the nixpkgs repo and use it as the main source of truth, referring to the manuals as a kind of “base reference cards/sheets”;
  3. “to pin or not to pin”: when staying with a NixOS release, I quickly started to miss newer packages; when following nightly, I was afraid of things breaking and the config being not really reproducible; I tried to reasearch nixpkgs pinning, but didn’t manage to find a lot about this (reportedly doable, but haven’t found good examples I would be able to reuse);
  4. problems with hookability because of encapsulation: I started with .nixpkgs/config.nix and overlays for Nix, and /etc/configuration.nix with NixOS; but after some time I realized you can only do so much with them, as packages tend to be quite encapsulated, opening only a few parameters for public modification; IIUC, for deeper hacks/customization the de facto canonical technique seems to be to fork nixpkgs and maintain your own set of patches over it. This feels like notable trouble from maintenance perspective. (I think this is exacerbated by the difficulty of contributing back upstream; I’m fully aware this is a known problem in the community, discussed a lot, and efforts are taken repeatedly and relentlessly to try and solve this.)
  5. (introducing new, niche language in the codebase; as much as I like the Nix expression language, and understand its advantages, there’s no escaping that it being niche and peculiar must be accounted for as a cost from maintenance perspective; I cannot deny Ansible has it better here by using YAML+Python.)
  6. (popularity (i.e. ease of googling for solutions); absolutely not in any way a fault of Nix, but life’s not fair and Nix just starts with a handicap here compared to Ansible.)

I put the last two in parentheses, as I don’t see them as something that can (or should) be easily fixed, but this being a real “experience report”, I wanted to note, that when evaluating NixOS for use at work, I felt I cannot skip them if I want to be honest (comparing e.g. to Ansible).

By the way, I feel that 3. and 4. may be where I just haven’t found a good solution yet, so I’m especially open to suggestions here. But at this point I stand by my opinion that I do firmly see them as pain points, given that I put quite some effort to try and research them for myself. What can be said for sure is that some official documentation on recommended practices/approach here would be useful.

Also please note I last dabbled with Nix I think some 12+ months ago. I’d be happy to hear if any of this is now outdated.



Hey, I solve 3+4 using a nixpkgs.nix and overlay.nix described here:


Re.3: Does this linked approach work to pin the whole NixOS? If yes, how? I.e. how do I use it with /etc/configuration.nix in a NixOS installation? I still didn’t see it from the linked post.

Re.4: I don’t see how the link is related. Does it somehow help maintain a nixpkgs fork? Or does it in some other way provide more functionality than overlays for modifying existing packages in nixpkgs?


Include the overlay.nix into configuration.nix to add it to your package set. Like this: ( Pinning nixpkgs is just replacing the import with a specific github rev using fetchgit.


Since 18.03 you can pin nixpkgs directly in your NixOS config using nixpkgs.pkgs although I only recommend doing so if you have some automation set up to update the pin regularly. You can import Nixpkgs more than once if you only want to pin some packages.


@tom Umm; I think I must not have been able to explain or understand something clearly enough, as those hints don’t seem to really advance my situation in any way. As to pinning, I meant the whole NixOS, as in roberth’s suggestion.

@roberth Thanks! Why the automatic updating? Because of security? Or something else?


@akavel Yes, because of security, but also because I’m a lazy functional programmer :wink: I’m not recommending it, but not recommending not to. You can always revert to the conventional way.


@akavel correct. I usually pin specific projects. The other method pins the whole OS. The suggestion to keep it updated is to help you upgrade. At some point that becomes very similar to just using a channel. I agree that these nuanced differences and the power available to you makes a steep learning curve. There are multiple ways to do one thing and many ways to do slightly related things.

All: does this mean we should create an opinionated method/framework/cli/thing? Or at least document it as the “preferred way”. Overlays are a good step in that direction.


One thing I’ve repeatedly found frustrating is that when I google for various combinations of things including NixOS, I often find myself in the obsolete repository at . For instance googling “NixOS pulseaudio” currently has this as the second result, and I have often seen things in this repository as the first result. Why not just add a commit to this repository that removes everything except the README?


Why not just add a commit to this repository that removes everything except the README?

What prevents you from making such a PR for that repo? :slight_smile:

Btw, why would you ask Google when you can just grep the tree locally? (Hint: silver-searcher aka ag greps much faster than Google.)


Because I’m hoping real documentation exists somewhere for the topic at hand (e.g. in the manual, the NixOS wiki or a blog post), other than the source code.


@akavel I also recently searched for options for pinning nixpkgs for my system configuration. I keep my system configuration in git and my goal was for a specific commit in my repo to refer to as exact a state as possible. I didn’t like the variance channels introduce. In the end I went with the approach of adding nixpkgs as a git submodule and setting it in nix.nixPath. When I want to update I update the submodule.

I use my my nixpkgs fork as the remote for the submodule, mainly for when I have some pull request I want to use before it’s merged. I try to avoid maintaining any differences in my nixpkgs fork. I also added NixOS/nixpkgs-channels as a remote as advised in in the main nixpkgs repo and use that to follow nixos-unstable.

While there may be a better approach, I’m currently satisfied.
You can find my nixos config here, and this is the commit that adds the pinning.


One problem with submodules is that Nixpkgs repository has grown SO large. It takes quite a few to download it. I tried pinning it directly via URI, but I hit some chicken or egg problem that I forgot the details to. You definitely need to set nixPath to the pinned nixpkgs, and I remember that’s where the problem struck.

Add “suggest edit” and comments/discussions features in Manuals


  1. Add “suggest edit” and “notes/comments” to manuals.
  2. Encourage significantly more in line comments from authors/contributors in the nixpkgs repo.

One think that I think could be incredibly helpful for all of us is to make it possible to contribute notes to the manual and documentation WITHOUT needing to fork nixpkgs, editing manual files, and putting in a pull request. It makes it a gigantic pain in the ass to contribute helpful notes after solving a problem on your own. I think this is one of the biggest reasons that documwntation can seem thin or outdated.

This could be as simple as adding little comment sections to pages, and maybe section specific comment areas for longer docs like the manuals.

Discourse has been a helpful spot for me to post little examples or guides after I solve something; but I don’t see any real advantage of keeping these discussions so separated from the manuals’ pages.

Secondly the lack of inline comments in nixpkgs is something which has always baffled me. They usually only appear in libs and some of the core features, being almost completely non-existent in packages/derivations. I’m not sure if this is an intentional stylistic decision (or if they are discouraged), but I cannot see how it is to anyone’s benefit.


@Growpotkin Ok, so your response reminded me that there’s actually the revived NixOS Wiki — which was a major source of useful help and HOWTOs in its previous incarnation. So I tried to search for “nixos wiki version pinning”, and lo and behold, there’s even some FAQ note about it: Though I still don’t understand how to use the linked snippet in NixOS, or Nix overlays, or home-manager…

The wiki is not exactly same as inline comments in the docs, but I remember it being really useful before it undergone the takedown and then later the revival (fortunately). That shock therapy might be a reason why it seems to not show up in web search results so highly as before (or does it already?).

As to inline comments in the sources, I do lament this heavily with you. It’s not an easy thing to introduce such culture. That said, I do keep my hopes high for the recent nixdoc effort — really keeping my fingers crossed that this will get integrated to auto-publish on the main site…!


The Wiki has always been #1 in search results when it’s relevant to me, on different search engines.


I think the “suggest edit” is a great idea. I actually did a lot of small changes to my local copy of the manual while reading through it for the first time. I never ended up submitting it though and its too bit-rotten by now. An easier way to “get it out” immediately would have been good.

I very much agree about the inline comment point. Its probably the thing I request most in code reviews.