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 add|list|pin|remove [options] [args]

add
    Map REGISTRY name to FLAKE-REF (URL or registry name)

list
    Show all registry mappings

pin
    Pin REGISTRY to exact FLAKE-REF (immutable)

remove
    Delete REGISTRY mapping

--flake
    Resolve FLAKE-REF as registry name, not URL (add/pin)

--json
    Output as JSON instead of human-readable (list)

--profile FILE
    Operate on specified profile path

-h, --help
    Display help and exit

-V, --version
    Print version info

nix3-registry manages the Nix registry, a per-profile database mapping short names (e.g., nixpkgs) to flake references or URLs. This enables concise references in flake.nix files and commands like nix build nixpkgs#hello, promoting reproducibility without hardcoding long URLs.

Key subcommands allow adding new mappings, listing current entries, pinning specific revisions for stability, and removing entries. Entries can resolve to GitHub repos, tarballs, or other flakes. The --flake flag treats arguments as registry names for recursive resolution.

By default, it operates on the user's profile (<$NIX_PROFILE>). Use --profile for custom profiles like <~/.nix-profile-per-project>. JSON output via --json aids scripting. Registries integrate with Nix flakes, requiring experimental features enabled via nix.conf or --extra-experimental-features flakes.

This tool is essential for multi-project setups, teams sharing named inputs, or CI environments needing locked dependencies.

Requires flakes enabled; affects only specified profile; pinned entries override regular ones; no wildcard support.

nix3-registry add --flake nixpkgs github:NixOS/nixpkgs/nixos-unstable
nix3-registry list --json
nix3-registry pin mypkgs path:/path/to/local/flake
nix3-registry remove nixpkgs

Registries are profile-specific: nix3-registry --profile result add foo bar targets ./result Nix profile.

Introduced in Nix 2.4 (2021) with flakes; refactored to standalone nix3-registry binary in Nix 3.0 (2024) for modular CLI tooling.

nix3-store(1), nix3-build(1), nix(1), nix flake(1)