nix3-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

nix3 registry subcommand [options...]

--global / -g
    (Applies to add, remove) Modifies the global registry (shared across projects or users) instead of the default project-specific registry.

--flake
    Specifies the root directory of the Nix flake to operate on. Defaults to the current working directory.

--json
    (Applies to list) Outputs the result in a machine-readable JSON format.

--raw
    (Applies to list) Outputs only the raw flake references, without additional formatting.

add
    Adds a new registry entry. name is the canonical name, and flake-ref is the flake reference (e.g., a path or URL).

remove
    Removes the registry entry identified by name.

list
    Lists all currently configured registry entries, showing their names and corresponding flake references.

pin
    Pins the registry entry name to its currently resolved locked input. This action locks the exact version of the flake input for reproducibility.

update
    Updates a pinned registry entry name to its latest available version, resolving it against the most recent flake reference.

The nix3-registry command is a crucial tool for managing entries within the Nix registry. This registry serves as a mapping mechanism, associating user-friendly, canonical names (e.g., nixpkgs) with specific Nix flake references (e.g., github:NixOS/nixpkgs/nixos-23.11). It's an integral part of the experimental Nix Flakes feature, designed to enhance the reproducibility and usability of Nix-based projects.

By providing stable names for flake inputs, nix3-registry simplifies dependency management and ensures that builds are consistent across different environments. Users can add new mappings, remove old ones, list all configured entries, and crucially, pin specific versions of inputs to guarantee immutability for reproducible builds. It also supports updating these pinned entries to their latest available versions.

The Nix Flakes feature, including the nix3-registry command, is still considered experimental. Its behavior, command-line interface, and underlying mechanisms might evolve in future Nix releases.
Always be mindful of whether you are modifying the project-specific (local) registry or the global registry when using the --global option, as this significantly impacts the scope of your changes.

By default, nix3 registry operations are scoped to the current Nix flake project, modifying its local registry data (often implicitly managed). Using the --global option allows you to interact with a shared, user-specific (typically in ~/.config/nix/registry.json) or system-wide (/etc/nix/registry.json) registry. This distinction is crucial for managing common dependencies across multiple projects or for system-wide configuration.

The registry works in conjunction with the flake.lock file. When you pin a registry entry, Nix resolves the flake reference to a precise Git commit hash or content hash and records this in the flake.lock file. Subsequent builds will then use this locked version, ensuring reproducibility. The update subcommand is used to refresh this locked version to the latest available based on the original flake reference.

The concept of a Nix registry and the nix3-registry command were introduced as part of the experimental Nix Flakes initiative. Flakes began gaining prominence around Nix version 2.4, aiming to provide a more structured, reproducible, and user-friendly way to manage Nix projects and their dependencies. The registry was a key component in achieving stable and memorable names for flake inputs.

nix3-flake(1), nix3-build(1), nix3-shell(1), nix.conf(5)