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. 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 kvm 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 kvm 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 kvm 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 kvm 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: empty

• 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 kvm 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

• 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: empty

• 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 kvm 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

S3 Binary Cache Store

Store URL format: s3://bucket-name

This store allows reading and writing a binary cache stored in an AWS S3 bucket.

Settings:

• buffer-size

  Size (in bytes) of each part in multi-part uploads.

  Default: 5242880

• 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

• endpoint

  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

• 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

• log-compression

  Compression method for log/* files. It is recommended to use a compression method supported by most web browsers (e.g. brotli).

  Default: empty

• ls-compression

  Compression method for .ls files.

  Default: empty

• multipart-upload

  Whether to use multi-part uploads.

  Default: false

• narinfo-compression

  Compression method for .narinfo files.

  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

• profile

  The name of the AWS configuration profile to use. By default Nix will use the default profile.

  Default: empty

• region

  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

• scheme

  The scheme used for S3 requests, https (default) or http. 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

• 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 kvm 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

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 kvm 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