nix-registry

Pin the nixpkgs revision to the current version of the upstream repository

$ nix registry pin [nixpkgs]

$ nix registry pin [entry] [github:owner/repo/branch_or_revision]

$ nix registry add [entry] [github:owner/repo]

$ nix registry remove [entry]

$ nix registry --help

nix registry SUBCOMMAND [OPTIONS] [ARGUMENTS]

Available subcommands and their basic usage:
nix registry add NAME PATH [--flake] [--from ORIGIN] [--dir PATH] [--priority NUMBER]
nix registry delete NAME [--dir PATH]
nix registry list [--dir PATH] [--json] [--sort-by PROPERTY]
nix registry pin NAME [--dir PATH]
nix registry update [--dir PATH]

--dir
    Specifies the directory where the registry should be managed (e.g., for project-specific registries). By default, it operates on the global user registry.

--flake
    Used with the add subcommand to explicitly treat the provided PATH as a Nix flake, even if its structure is ambiguous. Nix often infers this automatically.

--from
    Used with the add subcommand to specify the origin of the registry entry, such as flake:nixpkgs or channel:nixpkgs. This helps Nix resolve the source properly.

--priority
    Used with the add subcommand to assign a lookup priority to the registry entry. Higher numbers mean higher priority. Defaults to 0.

--json
    Used with the list subcommand to output the registry entries in machine-readable JSON format, suitable for scripting.

--sort-by
    Used with the list subcommand to sort the output by a specific property, such as name, priority, or path.

The nix-registry command is a crucial utility within the Nix package manager for managing the Nix registry. The registry serves as a system for mapping short, human-readable names to Nix expressions, typically Nix flakes or traditional Nix channels. This abstraction simplifies referencing complex Nix inputs, allowing users to refer to, for example, nixpkgs instead of a full Git URL or a local path.

The command provides several subcommands to interact with this registry: add to create new entries, delete to remove them, list to view existing mappings, pin to fix an entry to a specific version (particularly useful for flakes to ensure reproducible builds by updating their lock file), and update to refresh the default nixpkgs entry.

Registry entries can be global (stored in /nix/var/nix/profiles/per-user/$USER/nix-registry) or project-specific (stored in .direnv/nix-registry or a custom path using the --dir option), enabling flexible management of dependencies across different development contexts. It streamlines the use of flakes by providing a standardized way to manage their inputs, making Nix usage more intuitive and efficient.

The nix-registry command manages entries that can be either global (for the current user) or local to a specific project. Project-specific entries are often stored in a .direnv/nix-registry directory if direnv is used, or in a path specified by the --dir option. Be mindful of which registry you are modifying or querying.

The remove subcommand is a deprecated alias for delete and should be avoided in favor of delete for clarity and future compatibility.

When using pin on a flake registry entry, it effectively updates the corresponding input's locked version within the flake's flake.lock file, ensuring reproducibility. This behavior is similar to nix flake update for a specific input.

The global user registry is typically located at /nix/var/nix/profiles/per-user/$USER/nix-registry. Project-specific or custom registries can be created and managed using the --dir option, allowing isolated and reproducible development environments.

While nix-registry allows you to define aliases for flake inputs, direct flake inputs in a flake.nix file take precedence when resolving dependencies within that specific flake. The registry is more for global or shared aliases that can be used interactively or by flakes that reference them indirectly.

The nix-registry command was introduced as part of the Nix 2.4/2.5 series, coinciding with the stabilization and wider adoption of Nix flakes. Before its introduction, channel management was primarily handled by nix-channel, and there wasn't a standardized, built-in way to manage short aliases for arbitrary Nix expressions or flake inputs. nix-registry provides a more generic and structured mechanism for defining and managing these mappings, especially vital for the flake ecosystem to abstract away complex flake input paths.

nix(1), nix-flake(1), nix-channel(1)