Provided by: nix-bin_2.18.1+dfsg-1ubuntu5_amd64 
Name
nix help-stores - show help about store types and their settings
Synopsis
nix help-stores [option…]
Nix supports different types of stores. These are described below.
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:
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
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:
• base64-ssh-public-host-key
The public host key of the remote machine.
Default: empty
• compress
Whether to enable SSH compression.
Default: false
• max-connection-age
Maximum age of a connection before it is closed.
Default: 4294967295
• max-connections
Maximum number of concurrent connections to the Nix daemon.
Default: 1
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• remote-program
Path to the nix-daemon executable on the remote machine.
Default: nix-daemon
• remote-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
• ssh-key
Path to the SSH private key used to authenticate to the remote machine.
Default: empty
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
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:
• compression
NAR compression method (xz, bzip2, gzip, zstd, or none).
Default: xz
• compression-level
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
• index-debug-info
Whether to index DWARF debug info files by build ID. This allows dwarffs to fetch debug
info on demand
Default: false
• local-nar-cache
Path to a local cache of NARs fetched from this binary cache, used by commands such as
nix store cat.
Default: empty
• parallel-compression
Enable multi-threaded compression of NARs. This is currently only available for xz and
zstd.
Default: false
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• secret-key
Path to the secret key used to sign the binary cache.
Default: empty
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
Default: false
• write-nar-listing
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:
• compression
NAR compression method (xz, bzip2, gzip, zstd, or none).
Default: xz
• compression-level
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
• index-debug-info
Whether to index DWARF debug info files by build ID. This allows dwarffs to fetch debug
info on demand
Default: false
• local-nar-cache
Path to a local cache of NARs fetched from this binary cache, used by commands such as
nix store cat.
Default: empty
• parallel-compression
Enable multi-threaded compression of NARs. This is currently only available for xz and
zstd.
Default: false
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• secret-key
Path to the secret key used to sign the binary cache.
Default: empty
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
Default: false
• write-nar-listing
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:
• log
directory where Nix will store log files.
Default: /nix/var/log/nix
• max-connection-age
Maximum age of a connection before it is closed.
Default: 4294967295
• max-connections
Maximum number of concurrent connections to the Nix daemon.
Default: 1
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• real
Physical path of the Nix store.
Default: /nix/store
• root
Directory prefixed to all other paths.
Default: ``
• state
Directory where Nix will store state.
Default: /dummy
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
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:
• log
directory where Nix will store log files.
Default: /nix/var/log/nix
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• read-only
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
• real
Physical path of the Nix store.
Default: /nix/store
• require-sigs
Whether store paths copied into this store should have a trusted signature.
Default: true
• root
Directory prefixed to all other paths.
Default: ``
• state
Directory where Nix will store state.
Default: /dummy
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
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:
• base64-ssh-public-host-key
The public host key of the remote machine.
Default: empty
• compress
Whether to enable SSH compression.
Default: false
• max-connections
Maximum number of concurrent SSH connections.
Default: 1
• path-info-cache-size
Size of the in-memory store path metadata cache.
Default: 65536
• priority
Priority of this store when used as a substituter. A lower value means a higher
priority.
Default: 0
• remote-program
Path to the nix-store executable on the remote machine.
Default: nix-store
• remote-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
• ssh-key
Path to the SSH private key used to authenticate to the remote machine.
Default: empty
• store
Logical location of the Nix store, usually /nix/store. Note that you can only copy
store paths between stores if they have the same store setting.
Default: /nix/store
• system-features
Optional features that the system this store builds on implements (like “kvm”).
Default: benchmark big-parallel nixos-test uid-range
• trusted
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
• want-mass-query
Whether this store (when used as a substituter) can be queried efficiently for path
validity.
Default: false
nix3-help-stores(1)