nix help-stores - Lix Reference Manual

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

> 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...]

Lix 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 Lix 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 Lix 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: machine-specific

- `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[?port=42069]`

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`

- `port`

  Port that should be used instead of the default on the remote machine.

  Default: ``

- `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: machine-specific

- `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: `zstd`

- `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.

  Note: when using zstd `-1` will select level 12 to approximately match xz compression ratios at default settings rather than the zstd library default of 3.

  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: machine-specific

- `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: `zstd`

- `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.

  Note: when using zstd `-1` will select level 12 to approximately match xz compression ratios at default settings rather than the zstd library default of 3.

  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: machine-specific

- `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?protocol=any`.

Settings:

- `log`

  directory where Lix 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`

- `protocol`

  Space-or-comma-separated list of protocols to try to connect to, in preference order. Currently supported:

  - `legacy-combined` (default): legacy wire protocol using a single combined socket. The provided path will be used unmodified to locate the combined daemon socket.

  Also supports the special value `any` to try all known protocols using the provided path as the base directory for sockets. Unlike `legacy-combined` this will append a `/socket` to the given path when trying to connect with the legacy-combined protocol.

  Ignored unless a path is also present.

  Default: `legacy-combined`

- `real`

  Physical path of the Nix store.

  Default: `/nix/store`

- `root`

  Directory prefixed to all other paths.

  Default: ``

- `state`

  Directory where Lix 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: machine-specific

- `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 Lix 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 Lix 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 Lix 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: machine-specific

- `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: `zstd`

- `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.

  Note: when using zstd `-1` will select level 12 to approximately match xz compression ratios at default settings rather than the zstd library default of 3.

  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 Lix 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: machine-specific

- `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[?port=42069]`

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`

- `port`

  Port that should be used instead of the default on the remote machine.

  Default: ``

- `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: machine-specific

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