Name

       nix registry - manage the flake registry

Synopsis

       nix registry [option…] subcommand

       where subcommand is one of the following:

       • nix registry add (./nix3-registry-add.md) - add/replace flake in user flake registry
       • nix registry list (./nix3-registry-list.md) - list available Nix flakes
       • nix  registry  pin  (./nix3-registry-pin.md)  -  pin  a  flake to its current version or to the current
         version of a flake URL
       • nix registry remove (./nix3-registry-remove.md) - remove flake from user flake registry

Description

       nix registry provides subcommands for managing flake  registries.  Flake  registries  are  a  convenience
       feature  that  allows you to refer to flakes using symbolic identifiers such as nixpkgs, rather than full
       URLs such as git://github.com/NixOS/nixpkgs. You can use these identifiers on the command line (e.g. when
       you do nix run nixpkgs#hello) or in flake  input  specifications  in  flake.nix  files.  The  latter  are
       automatically resolved to full URLs and recorded in the flake’s flake.lock file.

       In   addition,   the   flake   registry   allows   you  to  redirect  arbitrary  flake  references  (e.g.
       github:NixOS/patchelf) to another location, such as a local fork.

       There are multiple registries. These are, in order from lowest to highest precedence:

       • The global registry, which is a file downloaded from the URL specified by the  setting  flake-registry.
         It  is  cached  locally and updated automatically when it’s older than tarball-ttl seconds. The default
         global registry is kept in a GitHub repository (https://github.com/NixOS/flake-registry).

       • The system registry, which is shared by all users. The default location is  /etc/nix/registry.json.  On
         NixOS, the system registry can be specified using the NixOS option nix.registry.

       • The  user  registry  ~/.config/nix/registry.json. This registry can be modified by commands such as nix
         flake pin.

       • Overrides specified on the command line using the option --override-flake.

Registry format

       A registry is a JSON file with the following format:

       {
         "version": 2,
         "flakes": [
           {
             "from": {
               "type": "indirect",
               "id": "nixpkgs"
             },
             "to": {
               "type": "github",
               "owner": "NixOS",
               "repo": "nixpkgs"
             }
           },
           ...
         ]
       }

       That is, it contains a list of objects with attributes from  and  to,  both  of  which  contain  a  flake
       reference  in  attribute  representation.  (For  example,  {"type":  "indirect",  "id": "nixpkgs"} is the
       attribute representation of nixpkgs, while {"type": "github", "owner": "NixOS", "repo": "nixpkgs"} is the
       attribute representation of github:NixOS/nixpkgs.)

       Given some flake reference R, a registry entry is used if its from flake reference matches R. R  is  then
       replaced by the unification of the to flake reference with R.

Matching

       The from flake reference in a registry entry matches some flake reference R if the attributes in from are
       the same as the attributes in R. For example:

       • nixpkgs matches with nixpkgs.

       • nixpkgs matches with nixpkgs/nixos-20.09.

       • nixpkgs/nixos-20.09 does not match with nixpkgs.

       • nixpkgs does not match with git://github.com/NixOS/patchelf.

Unification

       The  to  flake  reference  in  a  registry  entry is unified with some flake reference R by taking to and
       applying the rev and ref attributes from R, if specified. For example:

       • github:NixOS/nixpkgs unified with nixpkgs produces github:NixOS/nixpkgs.

       • github:NixOS/nixpkgs unified with nixpkgs/nixos-20.09 produces github:NixOS/nixpkgs/nixos-20.09.

       • github:NixOS/nixpkgs/master unified with nixpkgs/nixos-20.09 produces github:NixOS/nixpkgs/nixos-20.09.

                                                                                                nix3-registry(1)