Warning
This program is experimental and its interface is subject to change.
Name
nix registry
- manage the flake registry
Synopsis
nix registry
[option...] subcommand
where subcommand is one of the following:
nix registry add
- add/replace flake in user flake registrynix registry list
- list available Nix flakesnix registry pin
- pin a flake to its current version or to the current version of a flake URLnix registry remove
- 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 thantarball-ttl
seconds. The default global registry is kept in a GitHub repository. -
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 optionnix.registry
. -
The user registry
~/.config/nix/registry.json
. This registry can be modified by commands such asnix registry 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 withnixpkgs
. -
nixpkgs
matches withnixpkgs/nixos-20.09
. -
nixpkgs/nixos-20.09
does not match withnixpkgs
. -
nixpkgs
does not match withgit://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 withnixpkgs
producesgithub:NixOS/nixpkgs
. -
github:NixOS/nixpkgs
unified withnixpkgs/nixos-20.09
producesgithub:NixOS/nixpkgs/nixos-20.09
. -
github:NixOS/nixpkgs/master
unified withnixpkgs/nixos-20.09
producesgithub:NixOS/nixpkgs/nixos-20.09
.
Options
Logging-related options
-
Set the logging verbosity level to 'debug'.
-
--log-format
formatSet the format of log output; one of
raw
,internal-json
,bar
orbar-with-logs
. -
--print-build-logs
/-L
Print full build logs on standard error.
-
Decrease the logging verbosity level.
-
--verbose
/-v
Increase the logging verbosity level.
Miscellaneous global options
-
Show usage information.
-
Disable substituters and consider all previously downloaded files up-to-date.
-
--option
name valueSet the Nix configuration setting name to value (overriding
nix.conf
). -
Consider all previously downloaded files out-of-date.
-
Show version information.
Note
See
man nix.conf
for overriding configuration settings with command line flags.