When is a Nix builtin function (`builtins`) considered ready to be used inside Nixpkgs

Most of the time, the Nix interpreter version is independent to the evaluation result. People would base their daily-driver on NixOS/nixpkgs/nixos-<stable version> and get bleeding-edge versions of packages from NixOS/nixpkgs/nixos-unstable directly without hesitation. This does not hold when a new builtin function is used in the newer version of Nixpkgs (or other Nix projects) but is not available to the version of Nix used to evaluate it.

As new builtin functions are added to newer versions of Nix, when is it considered okay to be used inside Nixpkgs? We don’t seem to have a guide about it.

To be specific, builtins.convertHash recently got accepted and merged into Nix. It would greatly simplify the implementation of legacy hash arguments (e.g. sha256 and sha512) compatibility of fetchers. I would like to know when to submit such PRs.

1 Like

The lib/minver.nix file specifies the minimum Nix version required, which is currently still 2.3. As far as I know there’s no standardised process or guidelines for updating it though.

Furthermore, CI doesn’t even use that version of Nix most of the time, so changes making Nixpkgs dependent on newer features might not even be caught, which caused problems before when placeholder was introduced.

It’s very common to poly-fill builtins for older versions though, e.g. if builtins.groupBy doesn’t exist, a pure Nix implementation is used: https://github.com/NixOS/nixpkgs/blob/b12d067c1bae020748f5e7073e642e67659c0381/lib/lists.nix#L462.

Furthermore I’d encourage people to not use builtins directly, but rather put their functionality into lib first and then use it from there. Builtin functionality being available through lib makes it much easier to evolve them over time, since we’re not bound to the indefinite stability guarantee of Nix builtins.


Can we copy that into a FAQ section?


Oh yeah good point! Frequently Asked Questions — nix.dev documentation Should be good, PR appreciated!

1 Like