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)