nix3-help-stores(1)

📦

version 2.35.3 · 12 versions

, in fedora 44

🌟 nix3-help-stores(1) 🌟

okay bestie, this page is straight out of the General Commands Manual and it’s literally all about nix help-stores. 💅

⚠️ 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 Local Overlay Store
Experimental SSH Store
Experimental SSH Store with filesystem 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/1542dip9i7k4f24y6hqgd04hmvid9hr5-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. no cap, stores are just out here with URLs. 🫶

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

✨ auto special URL ✨

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 in memory. Store objects can be read and written, but only so long as the store is open. Once the store is closed, all data will be discarded. it’s giving ephemeral 💀

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
read-only — Make any sort of write fail instead of succeeding. No additional memory will be used, because no information needs to be stored.
- Default: true
store — Logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset. Note that you can only copy store paths between stores if they have the same store setting.
- Default: /nix/store
system-features — Optional system features available on the system this store uses to build derivations.
- Example: "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 can be queried efficiently for path validity when used as a substituter.
- Default: false

🔮 Experimental Local Overlay Store 🔮

⚠️ Warning This store is part of an experimental feature. 🧪 To use this store, make sure the local-overlay-store experimental feature is enabled. For example, include the following in nix.conf: extra-experimental-features = local-overlay-store

Store URL format: local-overlay

This store type is a variation of the [local store] designed to leverage Linux’s Overlay Filesystem (OverlayFS for short). Just as OverlayFS combines a lower and upper filesystem by treating the upper one as a patch against the lower, the local overlay store combines a lower store with an upper almost-[local store]. (“almost” because while the upper filesystems for OverlayFS is valid on its own, the upper almost-store is not a valid local store on its own because some references will dangle.) To use this store, you will first need to configure an OverlayFS mountpoint appropriately as Nix will not do this for you (though it will verify the mountpoint is configured correctly). ✨

🧠 Conceptual parts of a local overlay store 🧠

This is a more abstract/conceptual description of the parts of a layered store, an authoritative reference. For more “practical” instructions, see the worked-out example in the next subsection. 👑

The parts of a local overlay store are as follows:

Lower store: Specified with the lower-store setting.

This is any store implementation that includes a store directory as part of the native operating system filesystem. For example, this could be a [local store], [local daemon store], or even another local overlay store.

The local overlay store never tries to modify the lower store in any way. Something else could modify the lower store, but there are restrictions on this Nix itself requires that this store only grow, and not change in other ways. For example, new store objects can be added, but deleting or modifying store objects is not allowed in general, because that will confuse and corrupt any local overlay store using those objects. (In addition, the underlying filesystem overlay mechanism may impose additional restrictions, see below.)

The lower store must not change while it is mounted as part of an overlay store. To ensure it does not, you might want to mount the store directory read-only (which then requires the [read-only] parameter to be set to true).

Lower store directory: Specified with lower-store.real setting.

This is the directory used/exposed by the lower store.

As specified above, Nix requires the local store can only grow not change in other ways. Linux’s OverlayFS in addition imposes the further requirement that this directory cannot change at all. That means that, while any local overlay store exists that is using this store as a lower store, this directory must not change.

Lower metadata source: Not directly specified. A consequence of the lower-store setting, depending on the type of lower store chosen.

This is abstract, just some way to read the metadata of lower store store objects. For example it could be a SQLite database (for the [local store]), or a socket connection (for the [local daemon store]).

This need not be writable. As stated above a local overlay store never tries to modify its lower store. The lower store’s metadata is considered part of the lower store, just as the store’s file system objects that appear in the store directory are.

Upper almost-store: Not directly specified. Instead the constituent parts are independently specified as described below.

This is almost but not quite just a [local store]. That is because taken in isolation, not as part of a local overlay store, by itself, it would appear corrupted. But combined with everything else as part of an overlay local store, it is valid.

Upper layer directory: Specified with upper-layer setting.

This contains additional store objects (or, strictly speaking, their file system objects that the local overlay store will extend the lower store with).

Upper store directory: Specified with the real setting. This is the same as the base local store setting, and can also be indirectly specified with the root setting.

This contains all the store objects from each of the two directories.

The lower store directory and upper layer directory are combined via OverlayFS to create this directory. Nix doesn’t do this itself, because it typically wouldn’t have the permissions to do so, so it is the responsibility of the user to set this up first. Nix can, however, optionally check that the OverlayFS mount settings appear as expected, matching Nix’s own settings.

Upper SQLite database: Not directly specified. The location of the database instead depends on the state setting. It is always ${state}/db.

This contains the metadata of all of the upper layer store objects (everything beyond their file system objects), and also duplicate copies of some lower layer store object’s metadata. The duplication is so the metadata for the closure of upper layer store objects can be found entirely within the upper layer. (This allows us to use the same SQL Schema as the [local store]’s SQLite database, as foreign keys in that schema enforce closure metadata to be self-contained in this way.)

🌈 Example filesystem layout 🌈

Here is a worked out example of usage, following the concepts in the previous section. 🧚

Say we have the following paths:

/mnt/example/merged-store/nix/store
/mnt/example/store-a/nix/store
/mnt/example/store-b

Then the following store URI can be used to access a local-overlay store at /mnt/example/merged-store:

local-overlay://?root=/mnt/example/merged-store&lower-store=/mnt/example/store-a&upper-layer=/mnt/example/store-b

The lower store directory is located at /mnt/example/store-a/nix/store, while the upper layer is at /mnt/example/store-b.

Before accessing the overlay store you will need to ensure the OverlayFS mount is set up correctly:

mount -t overlay overlay \
  -o lowerdir="/mnt/example/store-a/nix/store" \
  -o upperdir="/mnt/example/store-b" \
  -o workdir="/mnt/example/workdir" \
  "/mnt/example/merged-store/nix/store"

Note that OverlayFS requires /mnt/example/workdir to be on the same volume as the upperdir.

By default, Nix will check that the mountpoint has been set up correctly and fail with an error if it has not. You can override this behaviour by passing check-mount=false if you need to. 💅

✨ Settings ✨

build-dir — The directory on the host, in which derivations’ temporary build directories are created.

If not set, Nix will use the builds subdirectory of its configured state directory.

Note that builds are often performed by the Nix daemon, so its build-dir applies. 🛠️

Nix will make this directory for you automatically, with permissions that actually work, if it's not already there.

But if it does exist? Then its permissions must let every single user traverse it — in unix-speak, it needs o+x set — otherwise non-sandboxed builds will not work correctly. Not negotiable, bestie.

This is also where --keep-failed dumps its leftover files. 💀

And if Nix is running without a sandbox, or the platform just can't do sandboxing with bind mounts (looking at you, macOS 👀), then the builder's environment gets this directory instead of the virtual location sandbox-build-dir.

Warning: build-dir must not be set to a world-writable directory. If you put temporary build directories somewhere world-writable, other users can access or modify build data that's currently in use. On its own that's just an impurity, but combined with another factor, it has let malicious derivations escape the build sandbox. Do not do it, fr fr.

Also go look at the global build-dir setting.

Default: `` (yes, empty)

check-mount — double-check that the overlay filesystem is mounted properly.

Nix doesn't manage the overlayfs mount point itself, but the whole overlay store working correctly depends on that mount point being set up right. So instead of just assuming it's fine, this checks that the lowerdir and upperdir options are what we expect them to be. It's on by default, but you can disable it if you need to.

Default: true

ignore-gc-delete-failure — whether to just... let it go when the garbage collector can't delete stuff.

Warning: this setting is part of an experimental feature. To change it, make sure the local-overlay-store experimental feature is enabled. Like, toss this in nix.conf: extra-experimental-features = local-overlay-store ignore-gc-delete-failure = ...

Normally the garbage collector errors out if the nix daemon can't delete a file. With this on, those errors just get printed as warnings. ✨

Default: false

log — the directory where Nix keeps log files.

Defaults to NIX_LOG_DIR when root is not set.

Default: /nix/var/log/nix

lower-store — the store URL for the lower store. Default is auto (so: use the Nix daemon or /nix/store directly).

It has to be a store with a store dir on the file system. And it has to be used as the OverlayFS lower layer for this store's store dir. That's the whole vibe.

Default: empty

path-info-cache-size — size of the in-memory store path metadata cache.

Default: 65536

priority — priority of this store when it's used as a substituter. Lower value means higher priority.

Default: 0

read-only — allow this store to be opened while its database sits on a read-only filesystem.

Normally Nix tries to open the store database in read-write mode, even just for querying (when write access isn't even needed), which makes it fail if the database is on a read-only filesystem. 😭

Turn on 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 actually read-only. Using it when the filesystem is writable can cause incorrect query results or corruption errors if the database gets changed by another process. And even if the filesystem the database lives on looks read-only, think reeeeally hard about whether another user or system might have write access to it.

Default: false

real — physical path of the Nix store.

Defaults to store when root is not set.

Default: /nix/store

remount-hook — a script (or other executable) to run when the overlay filesystem needs remounting.

This is occasionally needed when you delete a store path that exists in both the upper and lower layers. In that situation, the only way to do the deletion without creating a "whiteout" is to bypass OverlayFS and delete the path in the upper layer directly. But doing that knocks the OverlayFS kernel data structures out-of-sync, which can lead to stale file handle errors — remounting fixes it. 🩹

The store directory is passed as an argument to the invoked executable.

Default: `` (empty)

require-sigs — whether store paths copied into this store need to have a trusted signature.

Default: true

root — directory prefixed to all other paths. 🌳

Default: `` (empty)

state — directory where Nix stores state.

Defaults to NIX_STATE_DIR when root is not set.

Default: /dummy

store — logical location of the Nix store, usually /nix/store.

Defaults to NIX_STORE_DIR if unset.

Note that you can only copy store paths between stores if they've got the same store setting. Same setting or no deal. 🤝

Default: /nix/store

system-features — optional system features available on the system this store uses to build derivations.

Example: "kvm"

Default: machine-specific

trusted — whether paths from this store can be used as substitutes even if they're not signed by a key listed in the trusted-public-keys setting.

Default: false

upper-layer — directory containing the OverlayFS upper layer for this store's store dir.

Default: /upper-layer-must-be-set

use-roots-daemon — whether to request garbage collector roots from an external daemon.

Warning: this setting is part of an experimental feature. To change it, make sure the local-overlay-store experimental feature is enabled. Like, drop this in nix.conf: extra-experimental-features = local-overlay-store use-roots-daemon = ...

When it's enabled, the garbage collector connects to a Unix domain socket at <state-dir> /gc-roots-socket/socket to discover extra roots that should not be collected. Super handy when the Nix daemon runs without root privileges and can't scan /proc for runtime roots. 🔍

You can start that daemon with nix store roots-daemon.

Default: false

want-mass-query — whether this store can be queried efficiently for path validity when used as a substituter.

Default: false

Experimental SSH Store with filesystem mounted 🌈

Warning: this store is part of an experimental feature. To use it, make sure the mounted-ssh-store experimental feature is enabled. Like, add this to nix.conf: extra-experimental-features = mounted-ssh-store

Store URL format:

mounted-ssh-ng://[username@]hostname

An experimental store type that gives you full access to a Nix store on a remote machine — and additionally requires that store to be mounted in the local file system. 🦋

Nix does not manage that mounting at all. You handle it manually, bestie. SSHFS or NFS, for example, could get the job done.

The local file system is what makes certain operations efficient. For instance, instead of serializing Nix archives and shipping them over the Nix channel, we can just reach directly into the file system data through the mount point. So fast, so slay. ✨

The local file system is also what makes certain operations possible that otherwise wouldn't be. For example, persistent GC roots can be created if they live on the same file system as the remote store: the remote side will create the symlinks needed to avoid race conditions. 🙈

Settings

base64-ssh-public-host-key — the public host key of the remote machine.

Default: empty

compress — whether to enable SSH compression.

Default: false

log — directory where Nix stores log files.

Defaults to NIX_LOG_DIR when root is not set.

Default: /nix/var/log/nix

max-connection-age — maximum age of a connection before it gets 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.

Defaults to store when root is not set.

Default: /nix/store

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

root — directory prefixed to all other paths.

Default: `` (empty)

ssh-key — path to the SSH private key used to authenticate to the remote machine. 🔑

Default: `` (empty)

state — directory where Nix stores state.

Defaults to NIX_STATE_DIR when root is not set.

Default: /dummy

store — logical location of the Nix store, usually /nix/store.

Defaults to NIX_STORE_DIR if unset.

Note that you can only copy store paths between stores if they have the same store setting. 👑

Default: /nix/store

system-features — optional system features available on the system this store uses to build derivations.

Example: "kvm"

Default: machine-specific

trusted — whether paths from this store can be used as substitutes even if they're not signed by a key listed in the trusted-public-keys setting.

Default: false

want-mass-query — 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[:port]

okay bestie, this one is experimental — it's a store type that gives you full access to a Nix store sitting on a remote machine. like, the whole thing. remote and yours. 💅

Settings

base64-ssh-public-host-key — the public host key of the remote machine. that's it, that's the whole vibe. 🔑 Default: empty
compress — whether to enable SSH compression or not. tiny packets, big dreams. ✨ Default: false
max-connection-age — maximum age of a connection before it gets closed. rip little connection 🫡 Default: 4294967295
max-connections — maximum number of concurrent connections to the Nix daemon. lowkey a crowd limit. 🎀 Default: 1
path-info-cache-size — size of the in-memory store path metadata cache. it's giving memory budget. 🧠 Default: 65536
priority — priority of this store when it's used as a substituter. a lower value means a higher priority (yes, it's one of those backwards ones, iykyk). 🌈 Default: 0
remote-program — path to the nix-daemon executable on the remote machine. tell it where the daemon lives. 🏠 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. keep it secret, keep it safe bestie 🔐 Default: empty
store — logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset.

⚠️ note bestie: you can only copy store paths between stores if they have the same store setting. no mixing, no matching, periodt.

Default: /nix/store

system-features — optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
trusted — whether paths from this store can be used as substitutes even if they're not signed by a key listed in the trusted-public-keys setting. 🤝 Default: false
want-mass-query — whether this store can be queried efficiently for path validity when it's used as a substituter. 🌸 Default: false

HTTP Binary Cache Store 🦋

Store URL format: http://..., https://...

this store lets a binary cache be accessed over the HTTP protocol. it's the classic, the icon, the moment. 💖

Settings

compression — NAR compression method. One of: xz, bzip2, gzip, zstd, none, br, compress, grzip, lrzip, lz4, lzip, lzma or lzop. To use a particular compression method, Nix has to be built with a version of libarchive that natively supports that compression algorithm. 🗜️ 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
log-compression — compression method for log/* files. it's 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
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. If not set explicitly, defaults to true when compression is zstd and false otherwise. 🧚 Default: false
path-info-cache-size — size of the in-memory store path metadata cache. 🧠 Default: 65536
priority — priority of this store when it's used as a substituter. a lower value means a higher priority. 🌈 Default: 0
retry-attempts — override filetransfer-retry-attempts for requests to this store. 🔁 Default: 0
retry-delay — override filetransfer-retry-delay for requests to this store (milliseconds). ⏳ Default: 0
retry-delay-rate-limited — override filetransfer-retry-delay-rate-limited for requests to this store (milliseconds). 🐢 Default: 0
retry-max-delay — override filetransfer-retry-max-delay for requests to this store (milliseconds). 🐇 Default: 0
secret-key — path to the secret key used to sign the binary cache. 🤫 Default: empty
secret-keys — list of comma-separated paths to the secret keys used to sign the binary cache. 🔑🔑 Default: empty
store — logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset.

⚠️ again bestie: you can only copy store paths between stores if they have the same store setting.

Default: /nix/store

system-features — optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
tls-certificate — path to an optional TLS client certificate in PEM format. 🪪 Default: empty
tls-private-key — path to an optional TLS client certificate private key in PEM format. 🔐 Default: empty
trusted — whether paths from this store can be used as substitutes even if they're not signed by a key listed in the trusted-public-keys setting. 💖 Default: false
want-mass-query — whether this store can be queried efficiently for path validity when it's used as a substituter. ✨ 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 lets you read and write a binary cache stored in path on the local filesystem. and if path doesn't exist yet? it will be created. slay. 💅

for example, this 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. One of: xz, bzip2, gzip, zstd, none, br, compress, grzip, lrzip, lz4, lzip, lzma or lzop. To use a particular compression method, Nix has to be built with a version of libarchive that natively supports that compression algorithm. 🗜️ 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. If not set explicitly, defaults to true when compression is zstd and false otherwise. 🧚 Default: false
path-info-cache-size — size of the in-memory store path metadata cache. 🧠 Default: 65536
priority — priority of this store when it's 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
secret-keys — list of comma-separated paths to the secret keys used to sign the binary cache. 🔑🔑 Default: empty
store — logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset.

⚠️ one more time: you can only copy store paths between stores if they have the same store setting.

Default: /nix/store

system-features — optional system features available on the system this store uses to build derivations. Example: "kvm" Default: machine-specific
trusted — whether paths from this store can be used as substitutes even if they're not signed by a key listed in the trusted-public-keys setting. 💖 Default: false
want-mass-query — whether this store can be queried efficiently for path validity when it's used as a substituter. ✨ 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

Okay so bestie, this store type is the "let's go ask the daemon" girlie 💁 — it gets its hands on a Nix store by talking to a Nix daemon that's listening on the Unix domain socket path.

When path is not given (so like, the bare daemon pseudo-URL, or just a lonely unix://), the socket path gets figured out like this:

The NIX_DAEMON_SOCKET_PATH environment variable, if it's set. ✨
Otherwise, daemon-socket/socket inside the state directory.

🎀 Settings 🎀

log — Directory where Nix stores log files. Defaults to NIX_LOG_DIR when root is not set.

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. Defaults to store when root is not set.

Default: /nix/store

root — Directory prefixed to all other paths.

Default: ``

state — Directory where Nix stores state. Defaults to NIX_STATE_DIR when root is not set.

Default: /dummy

store — Logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset.

Note that you can only copy store paths between stores if they have the same store setting.

Default: /nix/store

system-features — Optional system features available on the system this store uses to build derivations.

Example: "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 can be queried efficiently for path validity when used as a substituter.

Default: false

🌈 Local Store 🌈

Store URL format: local, root

This one accesses a Nix store in the local filesystem directly — no daemon middleman, we're going straight to the source, periodt. root is an absolute path that gets prefixed to other directories, like the Nix store directory. The store pseudo-URL local means a store that uses / as its root directory.

🦋 Local chroot store 🦋

A local store that uses a root other than / is called a local chroot store. With these cuties, 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 💖

build-dir — The directory on the host, in which derivations' temporary build directories are created.

If not set, Nix will use the builds subdirectory of its configured state directory.

Note that builds are often performed by the Nix daemon, so its build-dir applies.

Nix will create this directory automatically with suitable permissions if it does not exist. Otherwise its permissions must allow all users to traverse the directory (i.e. it must have o+x set, in unix parlance) for non-sandboxed builds to work correctly.

This is also the location where --keep-failed leaves its files.

If Nix runs without sandbox, or if the platform does not support sandboxing with bind mounts (e.g. macOS), then the builder's environment will contain this directory, instead of the virtual location sandbox-build-dir.

Warning ⚠️ build-dir must not be set to a world-writable directory. Placing temporary build directories in a world-writable place allows other users to access or modify build data that is currently in use. This alone is merely an impurity, but combined with another factor this has allowed malicious derivations to escape the build sandbox. 🚨

See also the global build-dir setting.

Default: ``

ignore-gc-delete-failure — Whether to ignore failures when deleting items with the garbage collector.

Warning ⚠️ This setting is part of an experimental feature. To change this setting, make sure the local-overlay-store experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = local-overlay-store
ignore-gc-delete-failure = ...

Normally the garbage collector will fail with an error if the nix daemon cannot delete a file, with this setting such errors will only be printed as warnings.

Default: false

log — Directory where Nix stores log files. Defaults to NIX_LOG_DIR when root is not set.

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 attempts 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. Defaults to store when root is not set.

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 stores state. Defaults to NIX_STATE_DIR when root is not set.

Default: /dummy

store — Logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if unset.

Note that you can only copy store paths between stores if they have the same store setting.

Default: /nix/store

system-features — Optional system features available on the system this store uses to build derivations.

Example: "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

use-roots-daemon — Whether to request garbage collector roots from an external daemon.

Warning ⚠️ This setting is part of an experimental feature. To change this setting, make sure the local-overlay-store experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = local-overlay-store
use-roots-daemon = ...

When enabled, the garbage collector connects to a Unix domain socket at <state-dir> /gc-roots-socket/socket to discover additional roots that should not be collected. This is useful when the Nix daemon runs without root privileges and cannot scan /proc for runtime roots.

The daemon can be started with nix store roots-daemon.

Default: false

want-mass-query — 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

okay bestie, this one is literally an AWS S3 (or S3-compatible service) bucket pretending to be a store. It lets you read and write 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",
                "s3:ListBucket"
            ],
            "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, s3:GetBucketLocation, and s3:ListBucket actions 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&region=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 ⚙️✨

addressing-style — The S3 addressing style to use. auto (default) uses virtual-hosted-style for standard AWS endpoints and path-style for custom endpoints; bucket names containing dots automatically fall back to path-style to avoid TLS certificate errors. path forces path-style addressing (deprecated by AWS). virtual forces virtual-hosted-style addressing (bucket names must not contain dots).

Default: auto

compression — NAR compression method. One of: xz, bzip2, gzip, zstd, none, br, compress, grzip, lrzip, lz4, lzip, lzma or lzop. To use a particular compression method Nix has to be built with a version of libarchive that natively supports that compression algorithm.

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 S3 endpoint to use. When empty (default), uses AWS S3 with region-specific endpoints. For S3-compatible services such as MinIO, set this to your service’s endpoint.

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-chunk-size — The size (in bytes) of each part in multipart uploads. Must be at least 5 MiB (AWS S3 requirement). Larger chunk sizes reduce the number of requests but use more memory. Default is 5 MiB.

Default: 5242880

Deprecated alias: buffer-size

multipart-threshold — The minimum file size (in bytes) for using multipart uploads. Files smaller than this threshold will use regular PUT requests. Default is 100 MiB. Only takes effect when multipart-upload is enabled.

Default: 104857600

multipart-upload — Whether to use multipart uploads for large files. When enabled, files exceeding the multipart threshold will be uploaded in multiple parts, which is required for files larger than 5 GiB and can improve performance and reliability for large 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.

If not set explicitly, defaults to true when compression is zstd and false otherwise.

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 uses the default profile.

Default: default

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

retry-attempts — Override filetransfer-retry-attempts for requests to this store.

Default: 0

retry-delay — Override filetransfer-retry-delay for requests to this store (milliseconds).

Default: 0

retry-delay-rate-limited — Override filetransfer-retry-delay-rate-limited for requests to this store (milliseconds).

Default: 0

retry-max-delay — Override filetransfer-retry-max-delay for requests to this store (milliseconds).

Default: 0

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: https

secret-key — Path to the secret key used to sign the binary cache.

Default: (empty)

secret-keys — List of comma-separated paths to the secret keys used to sign the binary cache.

Default: empty

storage-class — The S3 storage class to use for uploaded objects. When not set (default), uses the bucket’s default storage class. Valid values include:
- STANDARD (default, frequently accessed data)
- REDUCED_REDUNDANCY (less frequently accessed data)
- STANDARD_IA (infrequent access)
- ONEZONE_IA (infrequent access, single AZ)
- INTELLIGENT_TIERING (automatic cost optimization)
- GLACIER (archival with retrieval times in minutes to hours)
- DEEP_ARCHIVE (long-term archival with 12-hour retrieval)
- GLACIER_IR (instant retrieval archival)

See AWS S3 documentation for detailed storage class descriptions and pricing: https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage-class-intro.html

Default: (empty)

store — Logical location of the Nix store, usually /nix/store.

Defaults to NIX_STORE_DIR if unset.

Note that you can only copy store paths between stores if they have the same store setting.

Default: /nix/store

system-features — Optional system features available on the system this store uses to build derivations.

Example: "kvm"

Default: machine-specific

tls-certificate — Path to an optional TLS client certificate in PEM format.

Default: (empty)

tls-private-key — Path to an optional TLS client certificate private key in PEM format.

Default: (empty)

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 can be queried efficiently for path validity when used as a substituter.

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]

Okay bestie, this one is giving long-distance relationship 💞 — it lets you get limited access to a store on a whole other machine, and it does it over SSH. Not full access, not unlimited access. Limited. We respect boundaries in this house 🫶

⚙️ Settings ⚙️

base64-ssh-public-host-key — the public host key of the remote machine, in base64. Default: empty
compress — do you wanna turn SSH compression on or not? Default: false
log-fd — the file descriptor that SSH's stderr gets wired up to. Default: -1
max-connections — max number of SSH connections happening at the same time. Default: 1
path-info-cache-size — how big the in-memory store path metadata cache is. Default: 65536
priority — the priority of this store when it's being used as a substituter. Heads up: a lower value means a higher priority (yes, it's backwards, don't ask, it's the vibe 😭). Default: 0
remote-program — path to the nix-store executable on the remote machine. Default: nix-store
remote-store — the store URL to use over on the remote machine. Default is auto (i.e. use the Nix daemon or /nix/store directly). Default: empty
ssh-key — path to the SSH private key you're authenticating with to reach that remote machine. Default: ``
store — the logical location of the Nix store, usually /nix/store. Defaults to NIX_STORE_DIR if it's unset.

✨ Important vibe check: you can only copy store paths between stores if they've got the same store setting. Same setting or it's not happening, periodt.

Default: /nix/store

system-features — optional system features that exist on the system this store uses to build derivations. Example: "kvm". Default: machine-specific
trusted — whether paths coming from this store can be used as substitutes even when they are not signed by a key listed in the trusted-public-keys setting. Default: false
want-mass-query — whether this store can be queried efficiently for path validity when it's being used as a substituter. Default: false

🎀 Options 🎀

--debug — crank the logging verbosity level all the way up to ‘debug’. we're nosy today 🔍
--log-format format — pick the format of the log output; one of raw, internal-json, bar or bar-with-logs.
--print-build-logs, -L — print the full build logs straight onto standard error.
--quiet — turn the logging verbosity level down. shhh 🤫
--verbose, -v — turn the logging verbosity level up. tell me everything 💅

🌈 Miscellaneous global options 🌈

--help — show usage information. your bestie when you're lost 🫶
--offline — disable substituters and treat every previously downloaded file as up-to-date.
--option name value — set the Nix configuration setting name to value, overriding nix.conf. king of the override 👑
--refresh — treat every previously downloaded file as out-of-date.
--version — show version information.

📌 Note: see man nix.conf for how to override configuration settings with command line flags. iykyk 😌

and that's the whole page, bestie!! you made it to the end, genuinely iconic behavior 🌟 this was nix3-help-stores(1), pulled straight from the Nix manual source with its version and build date chillin' in the footer — go forth and store things flawlessly 💖✨🎀🦋🌸

📦 where this page comes from

fedora 44: nix-core 2.35.3-2.fc44 · LGPL-2.1-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms

nix3-help-stores(1)

🌟 nix3-help-stores(1) 🌟

💖 Name 💖

🦋 Synopsis 🦋

🎀 Store URL format 🎀

✨ auto special URL ✨

🧸 Dummy Store 🧸

✨ Settings ✨

🔮 Experimental Local Overlay Store 🔮

🧠 Conceptual parts of a local overlay store 🧠

🌈 Example filesystem layout 🌈

✨ Settings ✨

Experimental SSH Store with filesystem mounted 🌈

Settings

Experimental SSH Store 🌸

Settings

HTTP Binary Cache Store 🦋

Settings

Local Binary Cache Store 🍓

Settings

🌸 Local Daemon Store 💅

🎀 Settings 🎀

🌈 Local Store 🌈

🦋 Local chroot store 🦋

💖 Settings 💖

S3 Binary Cache Store ☁️💅

Anonymous reads to your S3-compatible binary cache 🕵️‍♀️

Authentication 🔐

Authenticated reads to your S3 binary cache 🔍

Authenticated writes to your S3-compatible binary cache ✍️

Examples 🍓

Settings ⚙️✨

🦋 SSH Store 🦋

⚙️ Settings ⚙️

🎀 Options 🎀

📝 Logging-related options 📝

🌈 Miscellaneous global options 🌈