New users are using NixOS wrong (and it's our fault)

but I also discourage people to install NixOS without having first learned at least some of the Nix language by practicing Nix in another Linux distribution.

I’m really hesitant to recommend people to start with Nix on non-NixOS because it is clearly a second-class citizen, which is not good for a first-time exposure.
Off the top of my head:

  • openGL application simply segfault.
  • you have to use nix-env instead of declarative configuration.nix
  • on single user installs, the store is mutable so it can easily be corrupted (and this happens often: every time you run python, it compiles bytecode in the store)
  • on distros without user namespaces (eg debian without special tuning) you end up disabling the sandbox, and some package don’t compile without it because they depend on /bin/sh being bash or because they still pick up FHS libs.
  • on darwin there is (used to be) a bug were if you try to install an unsupported package (eg firefox) nix-env fails without an error message

We only do CI on sandboxed NixOS linux (at least, I don’t know about darwin) so everything else ends up worse user experience. I don’t want to recommend that to potential users.

Also (but this is more personnal) I found helpful to be stuck on NixOS and thus forced to install things the right way. If you are still on $distro, it is easy to give up on $yet-another-evaluation-error and decide to use the mutable, usual way.

1 Like

Can’t we just look in people’s github repos and call it a day? :grin:

1 Like

Nixos is not a linux distro… it’s about a far from unix as you can get. It has a ‘degree’ of unix backward compatibility… but it’s about a close to unix as a apple is to an orange.

we need to patch all the standard utils like ‘adduser’ to display

’ Hi, are you sure you want to be using this…this ain’t ubuntu kiddo’.

that should be enough. :wink:

1 Like

Then of course someone in the community will call it unfriendly gatekeeping. Then turn around and support kicking someone as a troll even though the kicked user actually complained about a true negative experience with NixOS of a person (themselves) woefully underqualified from all sides and underestimating what qualified would mean.


I count myself as a bit of a noob. I think the documentation is pretty good. One thing I find hard to wrap my head around is more the language itself. Where do I put brackets, or braces, what values do I put into arguments?

I find it a lot to remember because I’m not a dev and don’t know any programming languages, and I’m not great at scripting. Like I said, I think the docs are pretty good, but maybe finding a way to make the nix language easier to remember and fully understand, and not by wrote.

I always thought nix-env was for installing user packages as non root, and not being “baked into” the system.

I would like to see nix-env integration with Discover and other gui software managers.

1 Like

Most systems installed by new users are single-user machines, though, and in that case it seems simplest to have all packages “baked into” the system?

I agree with this. I’ve been using NixOS for almost 2 years now but only really felt comfortable writing derivations from scratch this year. Despite knowing functional languages (Scheme, Haskell) the JSON-like syntax of Nix confused me. It seemed that the language revolved around attribute sets in a strange way.

I managed to get by for a while by editing configuration.nix and moving imperatively installed packages into it, but when it came to building software that was not in Nixpkgs (tilem2, now upstreamed), I was extremely confused. See the IRC logs from that day where clever was nice enough to package it for me.

I thought about this onboarding process recently when I was telling friends about Nix and realizing the documentation on how to get started building packages with Nix was somewhat lacking. Perhaps it would be of benefit to have some “problem driven” guide for those kinds of users? See my nix-challenges repo for such an idea.

1 Like

May I ask why? I’m very much beginner and I don’t know much of nix language. For me 2 main benefits of nixos are:

  • My system no longer boots. How do I restore it (NixOS answer - choose older generation)
  • How do my settings different from default (its configuration.nix split across several files).

(I second @siraben in nix language being confusing. It’s probably because pills get way too much into details of derivations before going to ‘useful’ parts. It would be like starting Haskell tutorial with description of thunks or git tutorial with what are BLOBs and references. Yes - both may be needed for understanding what is going on but not really when you just have a problem to solve now.

EDIT: To expand a bit - I think sometimes adding an immediate something working during process of the tutorial is more important than understanding all the details. Probably packaging hello world would be a good first lesson of tutorial rather than lesson 8. Compare it with ebuild tutorials in various places)


May I ask why? I’m very much beginner and I don’t know much of nix language.

In a similar setting, I encourage people to use Nix, because it is a pure addition: you know how you like to manage your system, and that’s great, and let’s use Nix for things I maintain and we need to be identical everywhere regardless of the base system.

Talking people into switching NixOS means talking them into taking an actual risk. This is not always desirable.


I do like the idea of seperating the core system, as defined in the nix config, from a users basic apps. In it’s own way, similar to Fedora Silverblue, or even Apple’s IOS (but you have control instead of Apple). Get the OS how you like it and leave it alone. Then install your apps as a user.

It also avoids the reboot after rebuilding the system.

1 Like

Mainly because I don’t want to take chances at getting people disappointed if they realize that Nix is quite complex only after they are “stuck” with it. I will of course describe all the benefits that using NixOS brings but encourage people to get a bit of experience with Nix first. That was my own experience and it was successful, but of course your mileage may vary.

Besides, I also advocate Nix to people that can benefit of it for specific use cases, but I think that’s actually a separate topic.

1 Like

I’m a convert to NixOS as of this year. I have been called a glutton for punishment for even attempting to use it as a daily driver, and while I admit that proficient configuration comes with an intimidating learning curve (especially for those new to Nix, functional programming, CAS, and/or system administration in general), I also wish to echo that this OS stands alone in what it offers, and as such, it goes without saying that “you have to learn what it is before you can try using it”.

For me, both the learning process and general use have been incredibly rewarding—and I have no intention of ever returning to a conventional FHS-based distro—but my onboarding was also purpose-based. For marketing the OS to the more casual prospective user, I agree that the uniqueness of its organizational paradigm perhaps should be clearer on the tin. It’s tragic to see a passerby automatically label NixOS as “a KDE distro” and so on.

I agree that scripted installations can be convenient even for the adept, provided adequate customizability.

Incidentally, I created a topic just today regarding @danieldk’s aforementioned LUKS dance: YubiKey 2FA FDE with multiple drives. Tedious indeed.

I installed NixOS in a VM to give it a shot, installed all packages and when trying to build a project called CMaNGOS which requires cmake, openssl, boost, bz2, mysql++ (and i wanted to build with clang) i completely lost it.

I did everything with configuration.nix up until that point where i wanted to do just build something in my homedir and NixOS blew up on me. And how would i go about debugging with with vs-code if i first need to make a nix package out of it?

So yeah, i agree too.

@Salsa9 Do you know how to build this project now?

No, I put it off for now as it was so arcane to me what i had to write to accomplish what i wanted. Coming from using Debian derivates and Manjaro where everything lives in a global “packagespace” is really quite the mindbender.

My long term goal is:
Replace Manjaro with NixOS on desktop (Everything up until building my own packages was no problem, the VM runs KDE with X, OpenSSH etc…)
Throw out my Macbook, find a good replacement to run NixOS on.
Find a cheapo host somewhere to run NixOS with containers for persistent services such as WeeChat, Syncthing, TypeScript labs (Since NixOS is heavier than others It’ll be some dedi)
Promote NixOS for the few Linux servers we have at work (We’re big into Microsoft and VMware at work)

Idk why i wrote my ambitions with Nix here, but it might be insightful for someone to know what people want to do and what’s blocking them from getting started.

Languages i have experience with already is only C# and C++ (Python, PowerShell, JS, PHP, bash scripts in small amounts too) as I’ve been involved in projects using these languages. I should probably start by reading the Nixlang manual before asking for help, so far i must say the documentation is quite good (except for building your own packages in my exp).

1 Like

No, I put it off for now as it was so arcane to me what i had to write to accomplish what i wanted. Coming from using Debian derivates and Manjaro where everything lives in a global “packagespace” is really quite the mindbender.

@Salsa9 he global namespace for packages is exactly what Nix tries to avoid, but I agree, once you’ve learned a “design pattern” wrt. package management, switching mental models can be initially costly.

It is quite simple to package things in Nix and specify dependencies, once you’ve seen an example (PM me if you want help with packaging your application). This is a good anecdote to the thread, since I myself felt the same.

Cheatsheet - NixOS Wiki is quite nice for beginners coming classical distros, but is lacking in even a basic “from scratch” example of how to package things.

I installed NixOS a year ago on my one server. I have to deal with 82 linux x86 servers and 112 ARM servers. Sometimes, when I have time, I install a new distribution on one server. Nix OS is simple. But in my opinion it is too simple because it is not intuitive at all. I don’t have time to read the entire documentation. There is a lack of simple “how to” guides on the Internet. If I don’t know something in Ubuntu or Debian, I write a phrase in google and pop up thousands of links on how to do it. Nix is so unpopular that the user relies on Documentation that they don’t have time to read.

I’m not aware of any good documentation for this, but you would want to do:

# shell.nix
with import '<nixpkgs>' { };

clangStdenv.mkDerivation {
  name = "CManGOS-git";
  src = null;

  nativeBuildInputs = [ cmake pkg-config ];
  buildInputs = [ openssl boost bz2 mysql ];

and to build it locally, you would just do:

# follow normal build instructions

there might be some “additional pain” if they have fixed paths in their code. e.g. /usr/bin/...

We have vscode with cpp extensions in the repo. Visual Studio Code - NixOS Wiki , I’m also working on creating a fhs-wrapped variation which will allow for extensions to “just work” vscode.fhs: add buildFHSUserEnv wrapped version by jonringer · Pull Request #99968 · NixOS/nixpkgs · GitHub

Purity does have a cost. The real pain is that it’s not apparent what you should do. And the learning curve is steeper than it needs to be.


We have searches for packages and options.

the nixpkgs framework (it’s libraries and conventions don’t have a reference guides with any examples).

It seems that it was written in adhoc manner, although it’s devilishly brilliant, I know for a fact it’s devilishly brilliant, because devilishly brilliant programmers don’t write devilishly brilliant documentation.

Many things have a level of API documentation… nix has none, and grepping the source right into the weeds, is probably going to put people off on first use.

is a brave attempt , nix/OS doesn’t have shortage of documentation, it has a shortage of Library functions->real world example . I guess that’s somewhere between API documentation and a Cookbook.

take this an example.

  sshkeys = pkgs.fetchFromGitHub {
    owner = "abc";
    repo = "def";
    rev = "123";
    sha512 = "456";
  getpubkeys = user: builtins.readFile "${sshkeys}/${user}.pub";
  mkuser = user: { name = user; isNormalUser = true; extraGroups = [ "wheel" ]; initialPassword = "hdsklf"; openssh.authorizedKeys.keys = [ (getpubkeys user) ]; };
  users.users = (lib.genAttrs [ "alice" "bob" "charlie" ] mkuser) // {
    dana = { name = "dana"; isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [
      "ssh-rsa AAAA..."
    ]; };

that’s pretty amazing as it goes… but uses lib.genAttrs

which is completely undocumented. (or is it).

apart from…

it’s here… with examples…

so i think all this stuff is actually documented, it’s just tucked away in .nix files… it needs to be extracted and placed in a searchable system like nix options (which is brilliant).

It’s a massive task. By the time i first this post , another 10 functions will be added to nixpkgs standard library…

Most projects ‘win’ not because they are technologically superior, they just have superior documentation over other pieces of technology.


The documentation for the nixpkgs library functions is extracted from the comments and is printed right in the document you linked: Nixpkgs 23.11 manual | Nix & NixOS