nix help-stores
[option…]
Nix supports different types of stores. These are described
below.
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.
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
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
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
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
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
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
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