Warning
This program is experimental and its interface is subject to change.
Name
nix help-stores
- show help about store types and their settings
Synopsis
nix help-stores
[option...]
Nix supports different types of stores:
- Dummy Store
- Experimental SSH Store
- Experimental SSH Store with filesytem mounted
- HTTP Binary Cache Store
- Local Binary Cache Store
- Local Daemon Store
- Local Store
- S3 Binary Cache Store
- SSH Store
Store URL format
Stores are specified using a URL-like syntax. For example, the command
# nix path-info --store https://cache.nixos.org/ --json \
/nix/store/a7gvj343m05j2s32xcnwr35v31ynlypr-coreutils-9.1
fetches information about a store path in the HTTP binary cache located at https://cache.nixos.org/, which is a type of store.
Store URLs can specify store settings using URL query strings,
i.e. by appending ?name1=value1&name2=value2&...
to the URL. For
instance,
--store ssh://machine.example.org?ssh-key=/path/to/my/key
tells Nix to access the store on a remote machine via the SSH
protocol, using /path/to/my/key
as the SSH private key. The
supported settings for each store type are documented below.
The special store URL auto
causes Nix to automatically select a
store as follows:
-
Use the local store
/nix/store
if/nix/var/nix
is writable by the current user. -
Otherwise, if
/nix/var/nix/daemon-socket/socket
exists, connect to the Nix daemon listening on that socket. -
Otherwise, on Linux only, use the local chroot store
~/.local/share/nix/root
, which will be created automatically if it does not exist. -
Otherwise, use the local store
/nix/store
.
Dummy Store
Store URL format: dummy://
This store type represents a store that contains no store paths and cannot be written to. It's useful when you want to use the Nix evaluator when no actual Nix store exists, e.g.
# nix eval --store dummy:// --expr '1 + 2'
Settings
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
Experimental SSH Store with filesytem mounted
Warning
This store is part of an experimental feature.
To use this store, make sure the
mounted-ssh-store
experimental feature is enabled. For example, include the following innix.conf
:extra-experimental-features = mounted-ssh-store
Store URL format: mounted-ssh-ng://[username@]hostname
Experimental store type that allows full access to a Nix store on a remote machine, and additionally requires that store be mounted in the local file system.
The mounting of that store is not managed by Nix, and must by managed manually. It could be accomplished with SSHFS or NFS, for example.
The local file system is used to optimize certain operations. For example, rather than serializing Nix archives and sending over the Nix channel, we can directly access the file system data via the mount-point.
The local file system is also used to make certain operations possible that wouldn't otherwise be. For example, persistent GC roots can be created if they reside on the same file system as the remote store: the remote side will create the symlinks necessary to avoid race conditions.
Settings
-
The public host key of the remote machine.
Default: empty
-
Whether to enable SSH compression.
Default:
false
-
directory where Nix will store log files.
Default:
/nix/var/log/nix
-
Maximum age of a connection before it is closed.
Default:
4294967295
-
Maximum number of concurrent connections to the Nix daemon.
Default:
1
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Physical path of the Nix store.
Default:
/nix/store
-
Path to the
nix-daemon
executable on the remote machine.Default:
nix-daemon
-
Store URL to be used on the remote machine. The default is
auto
(i.e. use the Nix daemon or/nix/store
directly).Default: empty
-
Directory prefixed to all other paths.
Default: ``
-
Path to the SSH private key used to authenticate to the remote machine.
Default: empty
-
Directory where Nix will store state.
Default:
/dummy
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
Experimental SSH Store
Store URL format: ssh-ng://[username@]hostname
Experimental store type that allows full access to a Nix store on a remote machine.
Settings
-
The public host key of the remote machine.
Default: empty
-
Whether to enable SSH compression.
Default:
false
-
Maximum age of a connection before it is closed.
Default:
4294967295
-
Maximum number of concurrent connections to the Nix daemon.
Default:
1
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Path to the
nix-daemon
executable on the remote machine.Default:
nix-daemon
-
Store URL to be used on the remote machine. The default is
auto
(i.e. use the Nix daemon or/nix/store
directly).Default: empty
-
Path to the SSH private key used to authenticate to the remote machine.
Default: empty
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
HTTP Binary Cache Store
Store URL format: http://...
, https://...
This store allows a binary cache to be accessed via the HTTP protocol.
Settings
-
NAR compression method (
xz
,bzip2
,gzip
,zstd
, ornone
).Default:
xz
-
The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected.
-1
specifies that the default compression level should be used.Default:
-1
-
Whether to index DWARF debug info files by build ID. This allows
dwarffs
to fetch debug info on demandDefault:
false
-
Path to a local cache of NARs fetched from this binary cache, used by commands such as
nix store cat
.Default: empty
-
Enable multi-threaded compression of NARs. This is currently only available for
xz
andzstd
.Default:
false
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Path to the secret key used to sign the binary cache.
Default: empty
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
-
Whether to write a JSON file that lists the files in each NAR.
Default:
false
Local Binary Cache Store
Store URL format: file://
path
This store allows reading and writing a binary cache stored in path in the local filesystem. If path does not exist, it will be created.
For example, the following builds or downloads nixpkgs#hello
into
the local store and then copies it to the binary cache in
/tmp/binary-cache
:
# nix copy --to file:///tmp/binary-cache nixpkgs#hello
Settings
-
NAR compression method (
xz
,bzip2
,gzip
,zstd
, ornone
).Default:
xz
-
The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected.
-1
specifies that the default compression level should be used.Default:
-1
-
Whether to index DWARF debug info files by build ID. This allows
dwarffs
to fetch debug info on demandDefault:
false
-
Path to a local cache of NARs fetched from this binary cache, used by commands such as
nix store cat
.Default: empty
-
Enable multi-threaded compression of NARs. This is currently only available for
xz
andzstd
.Default:
false
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Path to the secret key used to sign the binary cache.
Default: empty
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
-
Whether to write a JSON file that lists the files in each NAR.
Default:
false
Local Daemon Store
Store URL format: daemon
, unix://
path
This store type accesses a Nix store by talking to a Nix daemon
listening on the Unix domain socket path. The store pseudo-URL
daemon
is equivalent to unix:///nix/var/nix/daemon-socket/socket
.
Settings
-
directory where Nix will store log files.
Default:
/nix/var/log/nix
-
Maximum age of a connection before it is closed.
Default:
4294967295
-
Maximum number of concurrent connections to the Nix daemon.
Default:
1
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Physical path of the Nix store.
Default:
/nix/store
-
Directory prefixed to all other paths.
Default: ``
-
Directory where Nix will store state.
Default:
/dummy
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
Local Store
Store URL format: local
, root
This store type accesses a Nix store in the local filesystem directly
(i.e. not via the Nix daemon). root is an absolute path that is
prefixed to other directories such as the Nix store directory. The
store pseudo-URL local
denotes a store that uses /
as its root
directory.
A store that uses a root other than /
is called a chroot
store. With such stores, the store directory is "logically" still
/nix/store
, so programs stored in them can only be built and
executed by chroot
-ing into root. Chroot stores only support
building and running on Linux when mount namespaces
and user namespaces
are
enabled.
For example, the following uses /tmp/root
as the chroot environment
to build or download nixpkgs#hello
and then execute it:
# nix run --store /tmp/root nixpkgs#hello
Hello, world!
Here, the "physical" store location is /tmp/root/nix/store
, and
Nix's store metadata is in /tmp/root/nix/var/nix/db
.
It is also possible, but not recommended, to change the "logical"
location of the Nix store from its default of /nix/store
. This makes
it impossible to use default substituters such as
https://cache.nixos.org/
, and thus you may have to build everything
locally. Here is an example:
# nix build --store 'local?store=/tmp/my-nix/store&state=/tmp/my-nix/state&log=/tmp/my-nix/log' nixpkgs#hello
Settings
-
directory where Nix will store log files.
Default:
/nix/var/log/nix
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Allow this store to be opened when its database is on a read-only filesystem.
Normally Nix will attempt to open the store database in read-write mode, even for querying (when write access is not needed), causing it to fail if the database is on a read-only filesystem.
Enable read-only mode to disable locking and open the SQLite database with the
immutable
parameter set.Warning Do not use this unless the filesystem is read-only.
Using it when the filesystem is writable can cause incorrect query results or corruption errors if the database is changed by another process. While the filesystem the database resides on might appear to be read-only, consider whether another user or system might have write access to it.
Default:
false
-
Physical path of the Nix store.
Default:
/nix/store
-
Whether store paths copied into this store should have a trusted signature.
Default:
true
-
Directory prefixed to all other paths.
Default: ``
-
Directory where Nix will store state.
Default:
/dummy
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
S3 Binary Cache Store
Store URL format: s3://
bucket-name
This store allows reading and writing a binary cache stored in an AWS S3 (or S3-compatible service) bucket. This store shares many idioms with the HTTP Binary Cache Store.
For AWS S3, the binary cache URL for a bucket named example-nix-cache
will be exactly s3://example-nix-cache.
For S3 compatible binary caches, consult that cache's documentation.
Anonymous reads to your S3-compatible binary cache
If your binary cache is publicly accessible and does not require authentication, it is simplest to use the [HTTP Binary Cache Store] rather than S3 Binary Cache Store with https://example-nix-cache.s3.amazonaws.com instead of s3://example-nix-cache.
Your bucket will need a bucket policy like the following to be accessible:
{
"Id": "DirectReads",
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowDirectReads",
"Action": [
"s3:GetObject",
"s3:GetBucketLocation"
],
"Effect": "Allow",
"Resource": [
"arn:aws:s3:::example-nix-cache",
"arn:aws:s3:::example-nix-cache/*"
],
"Principal": "*"
}
]
}
Authentication
Nix will use the default credential provider chain for authenticating requests to Amazon S3.
Note that this means Nix will read environment variables and files with different idioms than with Nix's own settings, as implemented by the AWS SDK. Consult the documentation linked above for further details.
Authenticated reads to your S3 binary cache
Your bucket will need a bucket policy allowing the desired users to perform the s3:GetObject
and s3:GetBucketLocation
action on all objects in the bucket.
The anonymous policy given above can be updated to have a restricted Principal
to support this.
Authenticated writes to your S3-compatible binary cache
Your account will need an IAM policy to support uploading to the bucket:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "UploadToCache",
"Effect": "Allow",
"Action": [
"s3:AbortMultipartUpload",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::example-nix-cache",
"arn:aws:s3:::example-nix-cache/*"
]
}
]
}
Examples
With bucket policies and authentication set up as described above, uploading works via nix copy
(experimental).
-
To upload with a specific credential profile for Amazon S3:
$ nix copy nixpkgs.hello \ --to 's3://example-nix-cache?profile=cache-upload®ion=eu-west-2'
-
To upload to an S3-compatible binary cache:
$ nix copy nixpkgs.hello --to \ 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
Settings
-
Size (in bytes) of each part in multi-part uploads.
Default:
5242880
-
NAR compression method (
xz
,bzip2
,gzip
,zstd
, ornone
).Default:
xz
-
The preset level to be used when compressing NARs. The meaning and accepted values depend on the compression method selected.
-1
specifies that the default compression level should be used.Default:
-1
-
The URL of the endpoint of an S3-compatible service such as MinIO. Do not specify this setting if you're using Amazon S3.
Note
This endpoint must support HTTPS and will use path-based addressing instead of virtual host based addressing.
Default: empty
-
Whether to index DWARF debug info files by build ID. This allows
dwarffs
to fetch debug info on demandDefault:
false
-
Path to a local cache of NARs fetched from this binary cache, used by commands such as
nix store cat
.Default: empty
-
Compression method for
log/*
files. It is recommended to use a compression method supported by most web browsers (e.g.brotli
).Default: empty
-
Compression method for
.ls
files.Default: empty
-
Whether to use multi-part uploads.
Default:
false
-
Compression method for
.narinfo
files.Default: empty
-
Enable multi-threaded compression of NARs. This is currently only available for
xz
andzstd
.Default:
false
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
The name of the AWS configuration profile to use. By default Nix will use the
default
profile.Default: empty
-
The region of the S3 bucket. If your bucket is not in
us–east-1
, you should always explicitly specify the region parameter.Default:
us-east-1
-
The scheme used for S3 requests,
https
(default) orhttp
. This option allows you to disable HTTPS for binary caches which don't support it.Note
HTTPS should be used if the cache might contain sensitive information.
Default: empty
-
Path to the secret key used to sign the binary cache.
Default: empty
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
-
Whether to write a JSON file that lists the files in each NAR.
Default:
false
SSH Store
Store URL format: ssh://[username@]hostname
This store type allows limited access to a remote store on another machine via SSH.
Settings
-
The public host key of the remote machine.
Default: empty
-
Whether to enable SSH compression.
Default:
false
-
Maximum number of concurrent SSH connections.
Default:
1
-
Size of the in-memory store path metadata cache.
Default:
65536
-
Priority of this store when used as a substituter. A lower value means a higher priority.
Default:
0
-
Path to the
nix-store
executable on the remote machine.Default:
nix-store
-
Store URL to be used on the remote machine. The default is
auto
(i.e. use the Nix daemon or/nix/store
directly).Default: empty
-
Path to the SSH private key used to authenticate to the remote machine.
Default: empty
-
Logical location of the Nix store, usually
/nix/store
. Note that you can only copy store paths between stores if they have the samestore
setting.Default:
/nix/store
-
Optional system features available on the system this store uses to build derivations.
Example:
"kvm"
Default: machine-specific
-
Whether paths from this store can be used as substitutes even if they are not signed by a key listed in the
trusted-public-keys
setting.Default:
false
-
Whether this store can be queried efficiently for path validity when used as a substituter.
Default:
false
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.