Hold on, there's a mix-up here. I'm pretty sure that the priorities used by nix-env (the meta.priority field of derivations) have nothing at all to do with NixOS option system priorities, they are completely separate things that just happen to both be named the same.

It all always has the same name - of course.

This is why it was a play, my way of saying what is hard to show and explain. I hope somebody understood the meta of Not expected Spanish Inquisition!. But seems like nobody reacted to the seriousness of it, nobody shown he was there - except actors.

I opened a PR, so things would go cleaner from that. And here you helping me.

Ok. Yes, I thought that there is big probability that it is the case, but was too tired.

If that is true.
Manual talks only about nix-env and meta.priority.
And nixpkgs talks only about the priority.

And I so far found now explanation about the difference of the two.

I remember something that nix-env priorities had a very limited range, like 10 or 11. So everything must fin-in cascade into that gradations.

I already crawled through the Deus & relevant commits in the module but I do not know when I would go search even more.

So I looked into this myself, and one part is indeed a bit messed up.

Derivation priorities

Nix derivation priorities are apparently used for two different decisions, with different default priorities!

For deciding which files to use

One decision is made by environment builders to figure out which package a file should come from if multiple of them have one at some included path. The main environment builders are pkgs.buildEnv (declarative) and nix-env (statefully). Both of them use a default priority of 5 for this, and lower numbers mean higher priority. Source for buildEnv and for nix-env.

For deciding which derivation to install

The second decision is made by nix-env as well, to decide which package to install when running -i (without -A) and there's multiple with the same name and version. For this, it uses a default priority of 0! Source.

Example of weirdness

So as a result, this can lead to some odd behavior. E.g. let prio.nix be

with import <nixpkgs> {};
let mkDrv = name: priority: runCommandNoCC name
  (lib.optionalAttrs (priority != null) { meta.priority = priority; })
  "mkdir $out; echo 'name = ${name}\npriority = ${toString priority}' > $out/priority";
in rec {
  aaa = mkDrv "foo" 4;
  bbb = mkDrv "foo" null; # Default priority, 0 or 5
  ccc = mkDrv "bar" 2;
}

We can have the following sequence of commands:

$ nix-env -f prio.nix -i foo
installing 'foo'
$ cat ~/.nix-profile/priority
name = foo
priority =

Here nix-env considered both aaa and bbb for installation because they have the requested name "foo", but bbb with default priority was selected, because it's 0 in this case, which is of higher priority than aaa's 4.

$ nix-env -f prio.nix -i bar
installing 'bar'
$ cat ~/.nix-profile/priority
name = bar
priority = 2

Here nix-env is installing ccc alongside the already installed bbb, but the file from ccc is preferred, because the default priority of bbb which is 5 in this case, is of lower priority than ccc's 2.

NixOS option priorities

Override priorities

NixOS option override priorities are used by the NixOS module system to decide which definitions of options should be used. Only definitions with the highest priority get merged together to build the final value, all others are ignored/overridden. Option definitions by default have priority 100, a lower number means higher priority. Due to the implementation, 9999 is the lowest possible priority as of now.

Functions mkOverride, mkDefault, mkForce, etc. can be used to change the priority of assignments. A bit confusing is how mkDefault isn't using the default priority, but 1000 instead, which is because mkDefault assigns a default value of the option, whereas 100 is the default priority of assigments. This means a normal option assigment will override any default values assigned elsewhere.

Ordering priorities

Once the list of definitions to be used has been decided with override priorities, ordering priorities can be used to control the ordering of definitions. The default ordering priority is 1000, with functions mkOrder, mkBefore and mkAfter to change it.

Thank you for your contributions.
This has been automatically marked as stale because it has had no activity for 180 days.
If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.
Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the
   related code and @ mention them in a comment.
2. Ask on the NixOS Discourse. 3. Ask on the #nixos channel on
   irc.freenode.net.

I marked this as stale due to inactivity. → More info