Why is there a "default" overlay in flakes?

Some flake attributes support a “default” entry. For example self.packages.${system}.default get’s build with a simple nix build without arguments.

In Rename `defaultX` flake outputs to `X.default` · Issue #5532 · NixOS/nix · GitHub these where moved from their top level name to the default entry in the respective attrset (e.g. defaultPackage.${system}packages.${system}.default or overlayoverlays.default)

I am wondering what the default overlay is for? Or how can I consume that in any other way than just referencing some-flake.overlays.default. All the other outputs of a flake that support the default entry use it as the default target of some nix sub-command if no arguments are given. But I could not find any such usage (or any other special usage) for overlays.default.

Flakes - NixOS Wiki also lists overlays.default without telling us what it is for.


The same goes for nixosModules.default.

1 Like

I would switch perspective and say: “some flake attributes …” → “some clients …”.

Now we have the answer: the nix cli client treats default specially.

But so could any other client, which — in the case of an overlay(/module) — would be an overlay(/module)-consumating function somewhere. I’m not aware that such is actually currently standardized somewhere in a library, but it could.

This switch in perspective also helps us understand that these .default are much less special than one might initially think them being.

They are a UX concession made bleeding itself into an output convention. Whether that’s actually good, idk.

Looks like a layer violation, to me, on a second more thorough look: an alternative implementation could provide flakes with a proper name attribute and by default accessor attributes of that name in outputs. In such a variant a UX concern wouldn’t bleed into output semantics, at least.

1 Like

There are two concerns the flake output schema address, and not all parts of it impact both:

  • Establishing a convention for flake outputs so that nix code can be more regular in how it accesses them. This is a human issue, not a technical one.
  • Establishing what flake outputs will be treated how by the tools. Since no tools interact with overlays beyond simply listing them in nix flake show, this concern isn’t really relevant for overlays.