nixos/flake-registry

Global registry of Nix flakes

Nix Flake Registry

Welcome to the Nix Flake Registry repository! This repository contains the default flake-registry.json file utilized by the Nix CLI. The flake registry serves as a convenient method for the Nix CLI to associate short names with flake URIs, such as linking nixpkgs to github:NixOS/nixpkgs/nixpkgs-unstable.

Usage

Mapped names from this registry are employed in two distinct contexts:

CLI

The registry allows for more concise invocations of nix run and other Nix commands.

For instance, when executing nix run nixpkgs#hello, the nixpkgs portion is resolved to the corresponding GitHub repository via the registry mapping.

Flake Inputs

When a flake output function refers to an input that has not been explicitly specified, the input is resolved using the registry.

Consider the following minimal flake.nix file:

{
  outputs = { self, nixpkgs }: { };
}

Here, self refers to the flake itself, while nixpkgs is resolved automatically through the registry.

NOTE: Although this feature offers convenience, we recommend explicitly listing all inputs, as the flake registry content may change over time.

Registry File Format

The file format is briefly documented here: https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-registry.html#registry-format.

Inclusion Policy

Inclusion criteria are evaluated based on the following considerations:

1. The namespace has a limited size.
2. Common names should be avoided to prevent confusion if a user mistypes an input in their flake.nix and it resolves to another input via the registry.
3. The shortcut must offer clear utility to the NixOS ecosystem; it is not intended to showcase random projects.
4. Project popularity is taken into account.

When submitting a PR, please acknowledge and refer to these policy points for argumentation.

If your goal is to get your project listed somewhere, consider submitting it to https://github.com/nix-community/awesome-nix/ instead.

NOTE: Some existing entries may not adhere to this policy due to historical reasons.

Publication Pipeline

By default, the Nix CLI is configured to fetch the registry at https://channels.nixos.org/flake-registry.json. This URL is proxied to this repository using Fastly: https://github.com/NixOS/nixos-org-configurations/blob/72adc59c5ba946c3d4844a920e9beefae12bbd49/terraform/channels.tf#L106-L116.

flake-registry's Issues

nixos-stable

points to current stable nixos release. I am unsure if registry allows ref.
I also proposed for branch which would make this easier NixOS/nixpkgs#266149

Can we add flake-utils?

What are the rules for all this? Which flakes can be added here anyways?

I'd love to see flake-utils added here because basically everyone uses it https://github.com/search?q=flake-utils+extension%3Anix&type=code

@numtide thoughts?

Policy for inclusion in the flake registry

What policy should we adopt for inclusion in the flake registry?

Should we allow any references that are getting submitted? Or do we have some criteria for inclusion?

Some facts:

• The registry is a global namespace and will hit naming collisions at some point
• The registry is not strictly necessary. It's mainly a shorthand notation.

This issue was triggered by #24. It seems to be just a normal tool, not specific to Nix.

Once we agree I will create a README and add the policy to it

Add CI to validate the schema

Make sure that the schema is valid by running it through some program. Does the Nix CLI provide a way to validate the schema?

`nixpkgs` entry should default to `nixpkgs-unstable` ref

The nixpkgs entry right now is github:NixOS/nixpkgs. This means that a reference to the nixpkgs flake will default to the master branch, meaning anyone who uses this may get packages that haven't yet been built by hydra. This is surprising and something of a footgun.

The registry should instead set it to github:NixOS/nixpkgs/nixpkgs-unstable. This mirrors the default <nixpkgs> channel set up by the Nix installer. Anyone who wants the master branch can reference it as nixpkgs/master. And similarly, other branches like nixpkgs/nixos-21.11 will still work as they do today.

Add nixos versions to replace channels?

The idea of flakes is to also replace channels. In a flake, one can choose what nixpkgs url to use. When not working with a local flake, one can invoke e.g.

nix shell nixpkgs#hello

If one wants a version from 20.09, one needs to use

$ nix shell nixpkgs#hello --override-input nixpkgs github:nixos/nixpkgs/nixos-20.09

It would be convenient if there would be registry entries for all stable versions so one could write

nix shell nixos-20.09#hello

We do need to draw a line here because we can't add all branches of whatever project. Also, it's not bad having to learn to use override-input. And, it prevents users from relying specifically on nixos-20.09 in a flake.nix where maybe they should not.

I do not know whether we should add the stable versions or not, but I can imagine here the convenience outweighs the disadvantages.