nix.conf(5)

📦

version 2.35.3 · 14 versions

💖 `nix.conf` — Nix configuration file

okay bestie, sit down, hydrate, because you just opened nix.conf(5) from the File Formats Manual and this is THE page. It's the configuration file for Nix, and honestly it ate. 🫶 We're gonna go through every single setting together, no skimming, no skipping, because nothing is boring when you're the main character of your own build. ✨

💅 Name

nix.conf — the Nix configuration file. That's the name, that's the whole thing, iconic. 👑

🌸 Description

Nix supports a variety of configuration settings, and they get read from configuration files or just straight taken as command line flags. Both. It's flexible like that. 💁‍♀️

🎀 Configuration file

By default, Nix reads settings from each of the following places. Settings are applied on top of one another, so later settings overwrite earlier entries. Stack 'em like lashes. 🦋

The system-wide configuration file nix.conf in the configuration directory.

The configuration directory defaults to ${sysconfdir}/nix (which is /etc/nix on most Unix systems) — or %PROGRAMDATA%\nix\conf on Windows — and you can override it with NIX_CONF_DIR.

Values loaded in this file are not forwarded to the Nix daemon. The client just assumes that the daemon has already loaded them. Assume-and-pray energy, but make it confident. 🙈

If NIX_USER_CONF_FILES is set, then each path in the list will be loaded in reverse order. The list separator is : on Unix and ; on Windows.

Otherwise it will look for nix.conf in:

The user configuration directory
On Unix additionally, nix/nix.conf under each directory in XDG_CONFIG_DIRS

If NIX_CONFIG is set, its contents are treated as the contents of a configuration file. In particular, settings are separated by newlines, just as in the configuration file.

📝 File format

Configuration files consist of name = value pairs, one per line. Comments start with a # character.

Example:

keep-outputs = true       # Nice for developers
keep-derivations = true   # Idem

Other files can be included with a line like include <path>, where <path> is interpreted relative to the current configuration file. A missing file is an error — unless you use !include instead. 💀

A configuration setting usually overrides any previous value. However, for settings that take a list of items, you can prefix the name of the setting by extra- to append to the previous value instead. It's giving "and also…" instead of "actually no".

For instance,

substituters = a b
extra-substituters = c d

defines the substituters setting to be a b c d.

Unknown option names are not an error — they're simply ignored, with a warning. Nix is chill like that. 🧚

🚩 Command line flags

Configuration options can be set on the command line, overriding the values set in the configuration file:

Every configuration setting has corresponding command line flag (e.g. --max-jobs 16). Boolean settings do not need an argument, and can be explicitly disabled with the no- prefix (e.g. --keep-failed and --no-keep-failed).

Unknown option names are invalid flags (unless there is already a flag with that name), and are rejected with an error. So don't just make stuff up, bestie. 😭

The flag --option <name> <value> is interpreted exactly like a <name> = <value> in a setting file.

Unknown option names are ignored with a warning.

The extra- prefix is supported for settings that take a list of items (e.g. --extra-trusted users alice or --option extra-trusted-users alice).

🔢 Integer settings

Settings that have an integer type support the suffixes K, M, G and T. These cause the specified value to be multiplied by 2^10, 2^20, 2^30 and 2^40, respectively. For instance, --min-free 1M is equivalent to --min-free 1048576. Math but make it cute. 🍓

⭐ Available settings

`abort-on-warn`

If set to true, builtins.warn throws an error when logging a warning.

This will give you a stack trace that leads to the location of the warning. 🕵️‍♀️

This is useful for finding information about warnings in third-party Nix code when you can not start the interactive debugger, such as when Nix is called from a non-interactive script. See debugger-on-warn.

Currently, a stack trace can only be produced when the debugger is enabled, or when evaluation is aborted.

This option can be enabled by setting NIX_ABORT_ON_WARN=1 in the environment.

Default: false

`accept-flake-config`

⚠️ heads up — this setting is part of an experimental feature. To change it, make sure the flakes experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = flakes
accept-flake-config = ...

Whether to accept Nix configuration settings from a flake without prompting. Yes, that means a flake can just tell you what to do. Consent is key. 💅

Default: false

`access-tokens`

Access tokens used to access protected GitHub, GitLab, or other locations requiring token-based authentication.

Access tokens are specified as a string made up of space-separated host=token values. The specific token used is selected by matching the host portion against the "host" specification of the input. The host portion may contain a path element which matches against the prefix URL for the input. (eg: github.com/org=token). The actual use of the token value is determined by the type of resource being accessed:

Github: the token value is the OAUTH-TOKEN string obtained as the Personal Access Token from the Github server (see https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps).
Gitlab: the token value is either the OAuth2 token or the Personal Access Token (these are different types tokens for gitlab, see https://docs.gitlab.com/12.10/ee/api/README.html#authentication). The token value should be type:tokenstring where type is either OAuth2 or PAT to indicate which type of token is being specified.

Example ~/.config/nix/nix.conf:

access-tokens = github.com=23ac...b289 gitlab.mycompany.com=PAT:A123Bp_Cd..EfG gitlab.com=OAuth2:1jklw3jk

Example ~/code/flake.nix:

input.foo = {
type = "gitlab";
host = "gitlab.mycompany.com";
owner = "mycompany";
repo = "pro";
};

This example specifies three tokens, one each for accessing github.com, gitlab.mycompany.com, and gitlab.com.

The input.foo uses the "gitlab" fetcher, which might requires specifying the token type along with the token value. (Yes, "might requires". We don't edit the source, we just vibe with it. 🎀)

Default: empty

`allow-dirty`

Whether to allow dirty Git/Mercurial trees. Uncommitted changes, we still love you. 🫶

Default: true

`allow-dirty-locks`

⚠️ heads up — this setting is part of an experimental feature. To change it, make sure the flakes experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = flakes
allow-dirty-locks = ...

Whether to allow dirty inputs (such as dirty Git workdirs) to be locked via their NAR hash. This is generally bad practice, since Nix has no way to obtain such inputs if they are subsequently modified. Therefore lock files with dirty locks should generally only be used for local testing, and should not be pushed to other users. Do not send your mess to your friends. 🙈

Default: false

`allow-import-from-derivation`

By default, Nix allows Import from Derivation.

With this option set to false, Nix throws an error when evaluating an expression that uses this feature, even when the required store object is readily available. This ensures that evaluation doesn't require any builds to take place, regardless of the state of the store.

Default: true

`allow-new-privileges`

(Linux-specific.) By default, builders on Linux cannot acquire new privileges by calling setuid/setgid programs or programs that have file capabilities. For example, programs such as sudo or ping should fail. (Note that in sandbox builds, no such programs are available unless you bind-mount them into the sandbox via the sandbox-paths option.) You can allow the use of such programs by enabling this option. This is impure and usually undesirable, but may be useful in certain scenarios (e.g. to spin up containers or set up userspace network interfaces in tests).

Default: false

`allow-symlinked-store`

If set to true, Nix stops complaining if the store directory (typically /nix/store) contains symlink components.

This risks making some builds "impure" because builders sometimes "canonicalise" paths by resolving all symlink components. Problems occur if those builds are then deployed to machines where /nix/store resolves to a different location from that of the build machine. You can enable this setting if you are sure you're not going to do that. The way this is a trust exercise. 😭

Default: false

`allow-unsafe-native-code-during-evaluation`

Enable built-in functions that allow executing native code. Wild behaviour. 🔥

In particular, this adds:

builtins.importNative path symbol

Opens dynamic shared object (DSO) at path, loads the function with the symbol name symbol from it and runs it. The loaded function must have the following signature:

extern "C" typedef void (*ValueInitialiser) (EvalState & state, Value & v);

The Nix C++ API documentation has more details on evaluator internals.

builtins.exec arguments

Execute a program, where arguments are specified as a list of strings, and parse its output as a Nix expression.

Default: false

`allowed-impure-host-deps`

Which prefixes to allow derivations to ask for access to (primarily for Darwin). 🍎

Default: empty

`allowed-uris`

A list of URI prefixes to which access is allowed in restricted evaluation mode. For example, when set to https://github.com/NixOS, builtin functions such as fetchGit are allowed to access https://github.com/NixOS/patchelf.git.

Access is granted when

the URI is equal to the prefix,
or the URI is a subpath of the prefix,
or the prefix is a URI scheme ended by a colon : and the URI has the same scheme.

Default: empty

`allowed-users`

A list of user names, separated by whitespace. These users are allowed to connect to the Nix daemon.

You can specify groups by prefixing names with @. For instance, @wheel means all users in the wheel group. Also, you can allow all users by specifying *.

📌 note — Trusted users (set in trusted-users) can always connect to the Nix daemon. VIP list behaviour, honestly. 👑

Default: *

`always-allow-substitutes`

If set to true, Nix ignores the allowSubstitutes attribute in derivations and always attempt to use available substituters.

Default: false

`auto-allocate-uids`

⚠️ heads up — this setting is part of an experimental feature. To change this setting, make sure the auto-allocate-uids experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = auto-allocate-uids
auto-allocate-uids = ...

auto-allocate-uids — okay so do you want Nix to just pick UIDs for builds all by itself instead of using the users in build-users-group? That's what this does 💅 The UIDs get handed out starting at 872415232 (0x34000000) on Linux, and starting at 56930 on macOS.

Default: false

auto-optimise-store — set this to true and Nix goes ✨detective mode✨, spotting files in the store with the exact same contents and replacing them with hard links to one single copy. Disk space? Saved. If you leave it at false (which is the default), you can still run nix-store --optimise later to yeet the duplicates by hand.

Default: false

bash-prompt — the bash prompt, aka PS1, inside nix develop shells.

Default: empty

bash-prompt-prefix — a lil prefix that gets prepended to the PS1 environment variable in nix develop shells.

Default: empty

bash-prompt-suffix — a lil suffix that gets appended to the PS1 environment variable in nix develop shells.

Default: empty

build-dir — overrides the build-dir store setting for every store that has this setting. Lowkey also check the per-store build-dir setting while you're at it 👀

Default: ``

build-hook — the path to the helper program that runs remote builds. Nix talks to the build hook over stdio using a custom protocol, asking it for builds that the Nix daemon can't do itself. The default value is the internal Nix binary that implements remote building.

⚠️ Important — only touch this setting if you really know what you're doing. fr fr.

Default: nix __build-remote

build-poll-interval — how often (in seconds) to poll for locks.

Default: 5

build-users-group — this option names the Unix group that holds the Nix build user accounts. Bestie, listen: in multi-user Nix installations, builds should not be run by the Nix account, because that would let users arbitrarily mess with the Nix store and database by handing over specially crafted builders 😭. And they can't be run by the calling user either, because that would let them influence the build result. Nope.

So basically: if this option is non-empty and points at a valid group, builds get performed under the user accounts that are members of the group you named here (as listed in /etc/group). Those user accounts should not be used for anything else, periodt!

Nix never runs two builds under the same user account at the same time. Why? To close an obvious security hole: a malicious user writing a Nix expression that modifies the build result of a legitimate Nix expression being built by someone else 💀. So it's good to have as many Nix build user accounts as you can spare. (Remember bestie: uids are cheap.)

The build users should have permission to create files in the Nix store, but not to delete them. So /nix/store should be owned by the Nix account, its group should be the group you specify here, and its mode should be 1775.

If the build users group is empty, builds run under the uid of the Nix process (so: the uid of the caller if NIX_REMOTE is empty, and the uid the Nix daemon runs under if NIX_REMOTE is daemon). Obviously, don't do this with a nix daemon that untrusted clients can reach 🙈.

Defaults to nixbld when running as root, empty otherwise.

Default: machine-specific

builders — a semicolon- or newline-separated list of build machines 🖥️✨

On top of the usual ways of setting config options, you can read the value from a file by prefixing its absolute path with @.

Example — this is the default setting:

builders = @/etc/nix/machines

Each machine specification is made up of the following elements, separated by spaces. Only the first element is required. To leave a field at its default, set it to -.

The URI of the remote store, in the format ssh://[username@]hostname[:port].

Example

ssh://nix@mac

For backward compatibility, ssh:// may be omitted. The hostname may be an alias defined in ~/.ssh/config.

A comma-separated list of Nix system types. If omitted, this defaults to the local platform type.

Example

aarch64-darwin

It is possible for a machine to support multiple platform types.

Example

i686-linux,x86_64-linux

The SSH identity file used to log in to the remote machine. If omitted, SSH uses its regular identities.

Example

/home/user/.ssh/id_mac

The maximum number of builds that Nix executes in parallel on the machine. Typically this should equal the number of CPU cores.
The "speed factor", indicating the relative speed of the machine as a positive integer or decimal number. If there are multiple machines of the right type, Nix prefers the fastest one, taking load into account.
A comma-separated list of supported system features.

A machine is only used to build a derivation if all the features in the derivation's requiredSystemFeatures attribute are supported by that machine.

A comma-separated list of required system features.

A machine is only used to build a derivation if all of the machine's required features appear in the derivation's requiredSystemFeatures attribute.

The (base64-encoded) public host key of the remote machine. If omitted, SSH uses its regular known_hosts file.

The value for this field can be obtained via base64 -w0.

Example — multiple builders specified on the command line:

--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'

Example — this specifies several machines that can perform i686-linux builds:

nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy 8 1 kvm
nix@itchy.labs.cs.uu.nl    i686-linux /home/nix/.ssh/id_scratchy 8 2
nix@poochie.labs.cs.uu.nl  i686-linux /home/nix/.ssh/id_scratchy 1 2 kvm benchmark

However, poochie only builds derivations that have the attribute

requiredSystemFeatures = [ "benchmark" ];

requiredSystemFeatures = [ "benchmark" "kvm" ];

itchy cannot do builds that require kvm, but scratchy does support such builds. For regular builds, itchy is preferred over scratchy because it has a higher speed factor. Slay 💅

For Nix to use substituters, the calling user must be in the trusted-users list.

Note — a build machine must be accessible via SSH and have Nix installed. nix must be available in $PATH for the user connecting over SSH.

⚠️ Warning — if you're building via the Nix daemon (the default), the Nix daemon user account on the local machine (that is, root) requires access to a user account on the remote machine (not necessarily root). If you can't or don't want to configure root to access the remote machine, set store to any local store, e.g. by passing --store /tmp to the command on the local machine.

To build only on remote machines and disable local builds, set max-jobs to 0.

If you want the remote machines to use substituters, set builders-use-substitutes to true.

Default: machine-specific

builders-use-substitutes — set to true and Nix tells remote build machines to use their own substituters if they have them. Which means: remote build hosts fetch as many dependencies as possible from their own substituters (like, say, from cache.nixos.org) instead of waiting around for the local machine to upload literally everything 🦋. If the network between the local machine and the remote build host is slow, this can drastically cut build times. Iconic.

Default: false

commit-lock-file-summary —

⚠️ Warning — this setting is part of an experimental feature. To change this setting, make sure the flakes experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = flakes
commit-lock-file-summary = ...

The commit summary to use when committing changed flake lock files. If empty, the summary is generated based on the action performed.

Default: empty

Deprecated alias: commit-lockfile-summary

compress-build-log — if set to true (the default), build logs written to /nix/var/log/nix/drvs get compressed on the fly using bzip2. Otherwise? Not compressed.

Default: true

Deprecated alias: build-compress-log

connect-timeout — the timeout (in seconds) for establishing connections in the binary cache substituter. It matches curl's --connect-timeout option. A value of 0 means no limit.

Default: 15

cores — sets the value of the NIX_BUILD_CORES environment variable when the builder executable of a derivation gets invoked. The builder executable can read this variable to control its own maximum amount of parallelism ✨

For instance, in Nixpkgs, if the attribute enableParallelBuilding for the mkDerivation build helper is set to true, it passes the -j${NIX_BUILD_CORES} flag to GNU Make.

If set to 0, nix will detect the number of CPU cores and pass that number via NIX_BUILD_CORES.

Note — the number of parallel local Nix build jobs is controlled independently with the max-jobs setting.

Default: 0

Deprecated alias: build-cores

debugger-on-trace — if set to true and the --debugger flag is given, these functions drop you into the debugger just like builtins.break:
- builtins.trace
- builtins.traceVerbose — if trace-verbose is set to true.
- builtins.warn

Super useful for debugging warnings in third-party Nix code 🫶

Default: false

debugger-on-warn — if set to true and the --debugger flag is given, builtins.warn will drop you into the debugger just like builtins.break.

Also super useful for debugging warnings in third-party Nix code.

Use debugger-on-trace if you also want to enter the debugger on legacy warnings that are logged with builtins.trace.

Default: false

diff-hook — …to be continued bestie 💅✨

absolute path to an executable that can diff build results. It only fires when run-diff-hook is true and we already know the build output isn't the same as before. It does not get run to figure out whether two results match — it's purely for showing you the diff. 💅

Quick deets, bestie:

The diff hook runs as the same user and group that ran the build.
But (!!) it does not have write access to the store path that was just built.
The stderr and stdout from the diff hook? Not shown to you. Nope. It goes to the nix-daemon's log instead. 🙈
When you're using the Nix daemon, diff-hook must be set in the nix.conf configuration file — you can't pass it on the command line.

The diff hook program receives three parameters:

A path to the previous build's results
A path to the current build's results
The path to the build's derivation
The path to the build's scratch directory. This directory exists only if the build was run with --keep-failed.

Default: ``

download-buffer-size — how big Nix's internal download buffer is, in bytes, during curl transfers. Real talk: if data isn't processed fast enough to get past the size of this buffer, downloads can stall. 😭 Default is 1048576 (that's 1 MiB, for the record).

Default: 1048576

download-speed — the max transfer rate, in kilobytes per second, that you want Nix to use for downloads.

Default: 0

eval-attrset-update-layer-rhs-threshold — tunes the biggest size an attribute set can be where, if it's used as the right-hand operand in an attribute set update expression, it uses a more space-efficient linked-list representation of attribute sets. Setting it higher generally means fewer memory allocations, but heads up, it can make evaluation performance worse. A value of 0 disables this optimization completely. 🚫

This is an advanced performance tuning thing and typically should not be changed. The default is picked to balance performance and memory usage. On 32 bit systems where memory is scarce, the default is a large value so there's fewer allocations.

Default: 16

eval-cache — whether to use the flake evaluation cache. Some commands won't have to evaluate when you invoke them a second time with a particular version of a flake. Note: intermediate results are not cached.

Default: true

eval-profile-file — the file where the evaluation profile gets saved. 🎀

Default: nix.profile

eval-profiler — turns on evaluation profiling. These modes are supported:
- flamegraph stack sampling profiler. Outputs folded format, one line per stack (suitable for flamegraph.pl and compatible tools).

Use eval-profile-file to say where the profile is saved. See Using the eval-profiler.

Default: disabled

eval-profiler-frequency — the sampling rate in hertz for sampling evaluation profilers. Use 0 to sample the stack after each function call. See eval-profiler.

Default: 99

eval-system — this defines builtins.currentSystem in the Nix language if it's set as a non-empty string. Otherwise, if it's set to the empty string (which is the default), the value of the system configuration setting is used instead. 👑

Unlike system, this setting does not change what kind of derivations can be built locally. It's useful for evaluating Nix code on one system so you can produce derivations to be built on another type of system.

Default: empty

experimental-features — the experimental features that are enabled.

Example:

experimental-features = nix-command flakes

The following experimental features are available:

auto-allocate-uids
blake3-hashes
ca-derivations
cgroups
configurable-impure-env
daemon-trust-override
dynamic-derivations
external-builders
fetch-closure
fetch-tree
flakes
git-hashing
impure-derivations
local-overlay-store
mounted-ssh-store
nix-command
parse-toml-timestamps
pipe-operators
read-only-local-store
recursive-nix
verified-fetches

Experimental features are further documented in the manual. 📖

Default: empty

external-builders — helper programs for building derivations, given in JSON format, like this:

[ {"systems": ["aarch64-linux"], "program": "/path/to/helper", "args": ["bla"]} ]

Whenever Nix needs to build a derivation for a system that's contained in systems, it will invoke program with the command line arguments args, plus an additional argument containing the path of a JSON document that describes the build environment. That JSON document looks like this:

{
"args": [
"-e",
"/nix/store/vj1c3wf9…-source-stdenv.sh",
"/nix/store/shkw4qm9…-default-builder.sh"
],
"builder": "/nix/store/s1qkj0ph…-bash-5.2p37/bin/bash",
"env": {
"HOME": "/homeless-shelter",
"builder": "/nix/store/s1qkj0ph…-bash-5.2p37/bin/bash",
"nativeBuildInputs": "/nix/store/l31j72f1…-version-check-hook",
"out": "/nix/store/2yx2prgx…-hello-2.12.2"
…
},
"inputPaths": [
"/nix/store/14dciax3…-glibc-2.32-54-dev",
"/nix/store/1azs5s8z…-gettext-0.21",
…
],
"outputs": {
"out": "/nix/store/2yx2prgx…-hello-2.12.2"
},
"realStoreDir": "/nix/store",
"storeDir": "/nix/store",
"system": "aarch64-linux",
"tmpDir": "/private/tmp/nix-build-hello-2.12.2.drv-0/build",
"tmpDirInSandbox": "/build",
"topTmpDir": "/private/tmp/nix-build-hello-2.12.2.drv-0",
"version": 1
}

Default: empty

extra-platforms — the system types of executables that can be run on this machine. ✨

Nix only builds a given store derivation locally when its system attribute equals any of the values specified here or in the system option.

Setting this is handy for building derivations locally on compatible machines:

i686-linux executables can be run on x86_64-linux machines (set by default)
x86_64-darwin executables can be run on macOS aarch64-darwin with Rosetta 2 (set by default where applicable)
armv6 and armv5tel executables can be run on armv7
some aarch64 machines can also natively run 32-bit ARM code
qemu-user may be used to support non-native platforms (though this may be slow and buggy)

Build systems usually detect the target platform to be the current physical system, and therefore produce machine code that's incompatible with what may be intended in the derivation. You should design your derivation's builder accordingly and cross-check the results when using this option against natively-built versions of your derivation. ⚠️

Default: machine-specific

fallback — if it's set to true, Nix falls back to building from source when a binary substitute fails. This is equivalent to the --fallback flag. Default is false.

Default: false

Deprecated alias: build-fallback

filetransfer-retry-attempts — how many times Nix attempts a file transfer (download or upload) before giving up. Retries apply to transient failures: connection-level errors, HTTP 408, 429, and most 5xx responses. Authentication failures (401/403/407), 404/410, and other 4xx responses are not retried. 🙅

Default: 5

Deprecated alias: download-attempts

filetransfer-retry-delay — initial delay in milliseconds before retrying a failed file transfer (download or upload). The delay doubles with each subsequent attempt (exponential backoff) and is subject to random jitter (see filetransfer-retry-jitter).

Default: 100

filetransfer-retry-delay-rate-limited — initial delay in milliseconds before retrying a file transfer that failed with a rate-limit response (HTTP 429 or 503). The delay doubles with each subsequent attempt.

Servers may send a Retry-After header specifying a longer delay; when present, Nix respects the larger of the two values. 🫶

Default: 5000

filetransfer-retry-jitter — whether to apply random jitter to retry delays. When enabled, each retry waits for a random duration between 0 and the computed delay ("full jitter"), which spreads out retry storms from many clients. Disable it for deterministic retry timing (primarily useful for tests).

Default: true

filetransfer-retry-max-delay — ceiling on the exponential backoff delay in milliseconds. Heads up: this does not cap server-provided Retry-After values, which are honored as-is.

Default: 60000

filter-syscalls — whether to prevent certain dangerous system calls, such as creation of setuid/setgid files or adding ACLs or extended attributes. Only disable this if you're aware of the security implications. 👀

Default: true

flake-registry

Warning This setting is part of an experimental feature. To change this setting, make sure the flakes experimental feature is enabled. For example, include the following in nix.conf:

extra-experimental-features = flakes
flake-registry = ...

Path or URI of the global flake registry. When empty, it disables the global flake registry. 🌈

Default: https://channels.nixos.org/flake-registry.json

fsync-metadata — if it's set to true, changes to the Nix store metadata (in /nix/var/nix/db) are synchronously flushed to disk. This improves robustness in case of system crashes, but reduces performance. The default is true.

Default: true

fsync-store-paths — whether to call fsync() on store paths before registering them, to flush them to disk. This improves robustness in case of system crashes, but reduces performance. The default is false.

Default: false

gc-reserved-space — amount of reserved disk space for the garbage collector. 🗑️

Default: 8388608

hashed-mirrors

A list of web servers that builtins.fetchurl hits up to grab files by hash. Give it a hash algorithm ha and a base-16 hash h, and Nix goes and downloads the file from hashed-mirror/ha/h. Which means: even if a file has fully ghosted its original URI, you can still get it. Obsessed, honestly. ✨

Like, say your mirror is http://tarballs.nixos.org/ and you're building this derivation:

builtins.fetchurl {
url = "https://example.org/foo-1.2.3.tar.xz";
sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
}

Nix will first try to download it from http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae. If it's not there, then it falls back to the original URI. 🦋

Default: empty

http-connections — the max number of parallel TCP connections used to fetch files from binary caches and by other downloads. Defaults to 25. 0 means no limit, bestie. 🌈

Default: 25

Deprecated alias: binary-caches-parallel-connections

http2 — whether to enable HTTP/2 support or not.

Default: true

http3 — whether to try enabling HTTP/3 (QUIC). When it's on, Nix requests HTTP/3 and transparently falls back to HTTP/2 or HTTP/1.1 for servers that don't support it. Heads up tho: this option does nothing unless the nix binary is linked against a libcurl built with HTTP/3 (QUIC) support. 💅

Default: false

id-count — the number of UIDs/GIDs to use for dynamic ID allocation.

Default: 8388608

ignore-try — if set to true, ignore exceptions inside tryEval calls when evaluating Nix expressions in debug mode (using the --debugger flag). By default the debugger pauses on all exceptions, no cap.

Default: false

ignored-acls — a list of ACLs that should be ignored. Normally Nix tries to remove all ACLs from files and directories in the Nix store, but some ACLs like security.selinux or system.nfs4_acl can't be removed even by root. So like, bestie, it's best to just ignore them. 🙈

Default: security.csm security.selinux system.nfs4_acl

impersonate-linux-26 — whether to impersonate a Linux 2.6 machine on newer kernels. Main character energy fr.

Default: false

Deprecated alias: build-impersonate-linux-26

impure-env — ⚠️ warning ⚠️ this setting is part of an experimental feature. To change it, make sure the configurable-impure-env experimental feature is enabled. For example, drop this in nix.conf:

extra-experimental-features = configurable-impure-env
impure-env = ...

A list of items, each in this format:

name=value: set environment variable name to value.

If the user is trusted (see the trusted-users option), then when building a fixed-output derivation, environment variables set in this option get passed to the builder if they're listed in impureEnvVars.

This option is useful for, e.g., setting https_proxy for fixed-output derivations and in a multi-user Nix installation, or setting private access tokens when fetching a private repository. 🔑

Default: empty

json-log-path — a file or unix socket to which JSON records of Nix's log output are written, in the same format as --log-format internal-json (but without the @nix prefixes on each line). Concurrency tea ☕: concurrent writes to the same file by multiple Nix processes are not supported and may result in interleaved or corrupted log records. Watch out.

Default: (empty)

keep-build-log — if set to true (the default), Nix writes the build log of a derivation (i.e. the standard output and error of its builder) to the directory /nix/var/log/nix/drvs. You can retrieve the build log with the command nix-store -l path. 🎀

Default: true

Deprecated alias: build-keep-log

keep-derivations — if true (default), the garbage collector keeps the derivations from which non-garbage store paths were built. If false, they get deleted unless explicitly registered as a root (or reachable from other roots).

Keeping derivations around is useful for querying and traceability (e.g., it lets you ask with what dependencies or options a store path was built), so by default this option is on. Turn it off to save a bit of disk space (or a lot if keep-outputs is also turned on). 🍓

This option only applies to garbage collection of the whole store and does not affect deleting explicit paths.

Default: true

Deprecated alias: gc-keep-derivations

keep-env-derivations — if false (default), derivations are not stored in Nix user environments. Which is to say, the derivations of any build-time-only dependencies may be garbage-collected. 🗑️

If true, when you add a Nix derivation to a user environment, the path of the derivation is stored in the user environment. So the derivation isn't garbage-collected until the user environment generation is deleted (nix-env --delete-generations). To prevent build-time-only dependencies from being collected, you should also turn on keep-outputs.

The difference between this option and keep-derivations is that this one is "sticky": it applies to any user environment created while this option was enabled, while keep-derivations only applies at the moment the garbage collector is run.

Default: false

Deprecated alias: env-keep-derivations

keep-failed — whether to keep temporary directories of failed builds. 💀

Default: false

keep-going — whether to keep building derivations when another build fails. The grind does not stop.

Default: false

keep-outputs — if true, the garbage collector keeps the outputs of non-garbage derivations. If false (default), outputs are deleted unless they are GC roots themselves (or reachable from other roots).

In general, outputs must be registered as roots separately. However, even if the output of a derivation is registered as a root, the collector still deletes store paths that are used only at build time (e.g., the C compiler, or source tarballs downloaded from the network). To prevent it from doing so, set this option to true. 🙅

This option only applies to garbage collection of the whole store and does not affect deleting explicit paths.

Default: false

Deprecated alias: gc-keep-outputs

lint-absolute-path-literals — controls handling of absolute path literals (paths starting with /) and home path literals (paths starting with ~/).
- ignore: ignore without warning (default)
- warn: emit a warning about non-portability
- fatal: treat as a parse error

So like, it is true that some files are more difficult to reference with relative paths, because they'd require lots of ../../.. upward traversing to reach them. But first off, it's probably not a good idea to reference these files — such paths often make Nix expressions less portable and reproducible, as they depend on the file system layout of the machine evaluating the expression. 👀

Secondly, with pure evaluation mode, most such files are prohibited to access anyway, whether by absolute or relative paths. In that case, enabling this lint in fatal mode is less disruptive, because the paths pure eval allows are usually not the ones that would be ergonomically expressed with absolute paths anyway. Iykyk.

Default: ignore

lint-short-path-literals — controls handling of relative path literals that don't start with ./ or ../.
- ignore: ignore without warning (default)
- warn: emit a warning suggesting to use ./ prefix
- fatal: treat as a parse error

For example, with this setting set to warn or fatal, foo/bar would suggest using ./foo/bar instead.

This is useful for improving code readability and making path literals more explicit. ✨

Default: ignore

lint-url-literals — controls handling of unquoted URLs as part of the Nix language syntax. The Nix language allows for URL literals, like so:

$ nix repl
nix-repl> http://foo
"http://foo"

Setting this to warn or fatal will cause the Nix parser to warn or throw an error when encountering a URL literal:

$ nix repl --lint-url-literals fatal
nix-repl> http://foo
error: URL literal 'http://foo' is deprecated
     at «string»:1:1:

          1| http://foo
           | ^

Unquoted URLs are being deprecated and their usage is discouraged. 🚫

The reason is that, as opposed to path literals, URLs have no special properties that distinguish them from regular strings, URLs containing query parameters have to be quoted anyway, and unquoted URLs may confuse external tooling.

Default: ignore

log-lines — the number of lines of the tail of the log to show if a build fails. Just the ✨highlights✨.

Default: 25

max-build-log-size — this option defines the maximum number of bytes that a builder can write to its stdout/stderr. If the builder exceeds this limit, it's killed. A value of 0 (the default) means that there is no limit.

Default: 0

Deprecated alias: build-max-log-size

max-call-depth — the maximum function call depth to allow before erroring. Don't go deeper, bestie. 🌊

Default: 10000

max-free — when a garbage collection is triggered by the min-free option, it stops as soon as max-free bytes are available. The default is infinity (i.e. delete all garbage). 🗑️✨

Default: 9223372036854775807

max-jobs — maximum number of jobs that Nix tries to build locally in parallel.

The special value auto causes Nix to use the number of CPUs in your system. Use 0 to disable local builds and directly use the remote machines specified in builders. This doesn't affect derivations that have preferLocalBuild = true, which are always built locally.

Note 📝 the number of CPU cores to use for each build job is independently determined by the cores setting.

The setting can be overridden using the --max-jobs (-j) command line switch.

Default: 1

Deprecated alias: build-max-jobs

max-silent-time
max-silent-time — okay so this one sets the max number of seconds a builder can go without producing any data on standard output or standard error, and honestly the watchdog energy is immaculate 💅. It's super useful (say, in an automated build system) for catching builds that have gotten themselves stuck in an infinite loop, or for catching remote builds that are just hanging there because of network problems. You can override it with the --max-silent-time command line switch.

A value of 0 means there is no timeout at all. And 0 is also the default, bestie.

Default: 0

Deprecated alias: build-max-silent-time

max-substitution-jobs — this defines the max number of substitution jobs Nix tries to run in parallel. Default is 16. The minimum value you can choose is 1, and any value lower than that gets interpreted as 1.

Default: 16

Deprecated alias: substitution-max-jobs

min-free — when the free disk space in /nix/store drops below min-free during a build, Nix runs a garbage-collection until max-free bytes are available or there's literally no more garbage left to collect. A value of 0 (which is the default) turns this whole feature off. 🗑️✨

Default: 0

min-free-check-interval — the number of seconds between checks of the free disk space. tick tock ⏰

Default: 5

nar-buffer-size — the maximum size of NARs before Nix spills them out to disk.

Default: 33554432

narinfo-cache-meta-ttl — the TTL in seconds for caching binary cache metadata (i.e. /nix-cache-info). It decides how long the info about a binary cache — stuff like its store directory, priority, and whether it wants mass queries — counts as valid before it gets refreshed.

Default: 604800

narinfo-cache-negative-ttl — the TTL in seconds for negative lookups. If a store path gets queried from a substituter but wasn't found, a negative lookup gets cached in the local disk cache database for the duration you specify.

Set it to 0 to force updating the lookup cache.

Wanna wipe the lookup cache completely? Say less, bestie:

$ rm $HOME/.cache/nix/binary-cache-v*.sqlite*
# rm /root/.cache/nix/binary-cache-v*.sqlite*

Default: 3600

narinfo-cache-positive-ttl — the TTL in seconds for positive lookups. If a store path gets queried from a substituter, the result of that query is cached in the local disk cache database, including some of the NAR metadata. The default TTL is a whole month. Setting a shorter TTL for positive lookups can be useful for binary caches that have frequent garbage collection — in that case a more frequent cache invalidation would stop you from trying to pull the path again and failing with a hash mismatch if the build isn't reproducible. 😭

Default: 2592000

netrc-file — set this to an absolute path to a netrc file, and Nix will use the HTTP authentication credentials in that file whenever it tries to download from a remote host through HTTP or HTTPS. Defaults to $NIX_CONF_DIR/netrc.

The netrc file is just a list of accounts, formatted like this:

machine my-machine login my-username password my-password

For the exact syntax, go check the curl documentation.

Note — this must be an absolute path, and ~ is not resolved. Like, for example, ~/.netrc won't resolve to your home directory's .netrc. periodt. 🙈

Default: /dummy/netrc

nix-path — the list of search paths used for lookup path resolution. This setting determines the value of builtins.nixPath and can be used with builtins.findFile.
- The configuration setting is overridden by the NIX_PATH environment variable.
- NIX_PATH is overridden by specifying the setting as the command line flag --nix-path.
- Any current value is extended by the -I option or --extra-nix-path.

If those paths are actually accessible, the default values are:

$HOME/.nix-defexpr/channels — the user channel link, pointing at the current state of channels for the current user.
nixpkgs=$NIX_STATE_DIR/profiles/per-user/root/channels/nixpkgs — the current state of the nixpkgs channel for the root user.
$NIX_STATE_DIR/profiles/per-user/root/channels — the current state of all channels for the root user.

These files are set up by the Nix installer. See NIX_STATE_DIR for the details on that environment variable. 🫶

Note — if restricted evaluation is enabled, the default value is empty. And if pure evaluation is enabled, builtins.nixPath always evaluates to the empty list [ ].

Default: machine-specific

nix-shell-always-looks-for-shell-nix — before Nix 2.24, nix-shell would only look at shell.nix if it was in the working directory, when no file was specified. Since Nix 2.24, nix-shell always looks for a shell.nix, whether that's in the working directory or in a directory that was passed as an argument. You may set this to false to temporarily go back to the behavior of Nix 2.23 and older.

Using this setting is not recommended. It will be deprecated and removed. 💀

Default: true

nix-shell-shebang-arguments-relative-to-script — before Nix 2.24, relative file path expressions in arguments in a nix-shell shebang were resolved relative to the working directory. Since Nix 2.24, nix-shell resolves these paths in a manner that is relative to the base directory, which is defined as the script's directory. You may set this to false to temporarily revert to the behavior of Nix 2.23 and older.

Using this setting is not recommended. It will be deprecated and removed. 💀

Default: true

plugin-files — a list of plugin files for Nix to load. Each of these files gets dlopened by Nix. If they contain the symbol nix_plugin_entry(), that symbol gets called. Alternatively, they can affect execution through static initialization. In particular, these plugins may construct static instances of RegisterPrimOp to add new primops or constants to the expression language, RegisterStoreImplementation to add new store implementations, RegisterCommand to add new subcommands to the nix command, and RegisterSetting to add new nix config settings. See the constructors for those types for more details.

Warning! These APIs are inherently unstable and may change from release to release. ⚠️

Since these files get loaded into the same address space as Nix itself, they must be DSOs compatible with the instance of Nix that's running at the time (i.e. compiled against the same headers, not linked to any incompatible libraries). They should not be linked to any Nix libraries directly, as those are already available at load time.

If an entry in the list is a directory, all files in that directory get loaded as plugins (non-recursively).

Default: empty

post-build-hook — optional. The path to a program to execute after each build. 🌈

This option is only settable in the global nix.conf, or on the command line by trusted users.

When you're using the nix-daemon, the daemon executes the hook as root. If the nix-daemon isn't involved, the hook runs as the user executing the nix-build.

The hook executes after an evaluation-time build.
The hook does not execute on substituted paths.
The hook's output always goes to the user's terminal.
If the hook fails, the build succeeds but no further builds execute.
The hook executes synchronously, and blocks other builds from progressing while it runs.

The program executes with no arguments. The program's environment contains the following environment variables:

DRV_PATH — the derivation for the built paths.

Example: /nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv

OUT_PATHS — output paths of the built derivation, separated by a space character.

Example: /nix/store/l88brggg9hpy96ijds34dlq4n8fan63g-bash-4.4-p23-dev /nix/store/vch71bhyi5akr5zs40k8h2wqxx69j80l-bash-4.4-p23-doc /nix/store/c5cxjywi66iwn9dcx5yvwjkvl559ay6p-bash-4.4-p23-info /nix/store/scz72lskj03ihkcn42ias5mlp4i4gr1k-bash-4.4-p23-man /nix/store/a724znygmd1cac856j3gfsyvih3lw07j-bash-4.4-p23.

Default: empty

pre-build-hook — if set, the path to a program that can set extra derivation-specific settings for this system. This gets used for settings that can't be captured by the derivation model itself and are too variable between different versions of the same system to be hard-coded into nix.

The hook gets passed the derivation path and, if sandboxes are enabled, the sandbox directory. It can then modify the sandbox and send a series of commands to stdout to modify various settings. The commands currently recognized are:

extra-sandbox-paths — pass a list of files and directories to be included in the sandbox for this build. One entry per line, terminated by an empty line. Entries have the same format as sandbox-paths.

Default: empty

preallocate-contents — whether to preallocate files when writing objects with a known size.

Default: false

print-missing — whether to print what paths need to be built or downloaded.

Default: true

pure-eval — pure evaluation mode makes sure the result of Nix expressions is fully determined by explicitly declared inputs, and not influenced by external state:
- Restrict file system and network access to files specified by cryptographic hash
- Disable impure constants:
  - builtins.currentSystem
  - builtins.currentTime
  - builtins.nixPath
  - builtins.storePath

Default: false

require-drop-supplementary-groups — following the principle of least privilege, Nix attempts to drop supplementary groups when building with sandboxing.

However, this can fail under some circumstances. For example, if the user lacks the CAP_SETGID capability. Search setgroups(2) for EPERM to find more detailed information on this.

If you encounter such a failure, setting this option to false lets you ignore it and keep on going. But before you do that, you should consider the security implications very carefully. Not dropping supplementary groups means the build sandbox is less restricted than intended. 🚩

This option defaults to true when the user is root (since root usually has permissions to call setgroups) and false otherwise.

Default: false

require-sigs — sis hold that thought, the deets on this one are rolling in next 🎀
(still on the previous one bestie, we're not done 💖) — If it's set to true (the default, and yes it matters), then any non-content-addressed path that gets added or copied into the Nix store — like when you're substituting from a binary cache — must have a signature from a trusted key. And what's a trusted key, you ask? It's either one that's listed in trusted-public-keys, or the public key counterpart to a private key stored in a file that's listed in secret-key-files. That's the whole vibe check 🔑✨

Set it to false and you've fully turned off signature checking, trusting all non-content-addressed paths unconditionally. No bouncer, no velvet rope, just vibes.

(Content-addressed paths are inherently trustworthy, so this configuration option doesn't touch them at all — they're built different, no cap 💅)

Default: true

restrict-eval — flip this to true and the Nix evaluator gets the strictest curfew ever: it cannot access any files outside of builtins.nixPath, and it can't touch URIs outside of allowed-uris. Everything else is uninvited 🚫🙈

Default: false

run-diff-hook — if true, this enables the execution of the diff-hook program. Important though: when you're using the Nix daemon, run-diff-hook must be set in the nix.conf configuration file — it can't be passed at the command line. It's giving config-file-only, no exceptions 😤

Default: false

sandbox — ok this one is a whole personality, buckle up 🌈 If set to true, builds get performed in a sandboxed environment. Meaning: they're isolated from the normal file system hierarchy and can only see their dependencies in the Nix store, the temporary build directory, private versions of /proc, /dev, /dev/shm and /dev/pts (on Linux), and the paths configured with the sandbox-paths option. Why do we care? Because it stops builds from sneakily depending on undeclared files in directories like /usr/bin. Chef's kiss prevention 🎀

Extra on Linux: builds also run in private PID, mount, network, IPC and UTS namespaces, so they're isolated from other processes in the system. The one exception — fixed-output derivations don't run in a private network namespace, since they need to be able to access the network.

Currently, sandboxing only works on Linux and macOS. And using a sandbox requires that Nix is run as root — so bestie, please use the "build users" feature so the actual builds happen under different users instead of root. Do it for me 🫶

Set this option to relaxed and it chills out a bit: fixed-output derivations, and derivations that have the __noChroot attribute set to true, do not run in sandboxes.

The default is true on Linux and false on all other platforms.

Default: true

Deprecated alias: build-use-chroot, build-use-sandbox

sandbox-build-dir — Linux only 💛 This is the build directory inside the sandbox. That directory is backed by build-dir on the host.

Default: /build

sandbox-dev-shm-size — Linux only 💛 This option determines the maximum size of the tmpfs filesystem mounted on /dev/shm in Linux sandboxes. For the format, go look at the description of the size option of tmpfs in mount(8). The default is 50%.

Default: 50%

sandbox-fallback — whether to disable sandboxing when the kernel just won't allow it 🫠

Default: true

sandbox-paths — a list of paths that get bind-mounted into Nix sandbox environments. You can use the target=source syntax to mount a path in a different location inside the sandbox; for instance, /bin=/nix-bin mounts the path /nix-bin as /bin inside the sandbox. Slay 💅

If source is followed by a ?, then it's not an error if source doesn't exist; for example, /dev/nvidiactl? specifies that /dev/nvidiactl only be mounted in the sandbox if it exists in the host filesystem. Very demure, very mindful ✨

If the source is in the Nix store, then its closure gets added to the sandbox as well.

Depending on how Nix was built, the default value for this option may be empty, or it may provide /bin/sh as a bind-mount of bash.

Default: empty

Deprecated alias: build-chroot-dirs, build-sandbox-paths

secret-key-files — a whitespace-separated list of files containing secret (private) keys 🔐 These get used to sign locally-built paths. You can generate them with nix-store --generate-binary-cache-key. The corresponding public key can then be distributed to other users, who can add it to trusted-public-keys in their own nix.conf.

Default: empty

show-trace — should Nix print out a stack trace when Nix expression evaluation errors happen? 🫣

Default: false

ssl-cert-file — the path of a file containing CA certificates used to authenticate https:// downloads. By default Nix uses the first of these files that exists:
1. /etc/ssl/certs/ca-certificates.crt
2. /nix/var/nix/profiles/default/etc/ssl/certs/ca-bundle.crt

The path can be overridden by these environment variables, in order of precedence:

NIX_SSL_CERT_FILE
SSL_CERT_FILE

Default: machine-specific

stalled-download-timeout — the timeout (in seconds) for receiving data from servers during a download. Nix cancels idle downloads once this timeout's duration has passed. Bye bye, dead downloads 💀

Default: 300

start-id — the first UID and GID to use for dynamic ID allocation.

Default: 872415232

store — the URL of the Nix store to use for most operations. Wanna know all the supported store types and settings? That's the Store Types section of the manual, go peek 📖

This can be overridden by the NIX_REMOTE environment variable.

The default value is auto.

Default: auto

substitute — if set to true (default), Nix uses binary substitutes whenever they're available. Disable it and you're forcing everything to build from source, which is a choice 😭

Default: true

Deprecated alias: build-use-substitutes

substituters — a list of URLs of Nix stores to be used as substituters, separated by whitespace. A substituter is an additional store that Nix can grab store objects from instead of building them itself 🛍️

Substituters get tried based on their priority value, and each substituter can set that independently. Lower value means higher priority. The default is https://cache.nixos.org, which has a priority of 40.

For Nix to use a substituter, at least one of these conditions has to be met:

The substituter is in the trusted-substituters list
The user calling Nix is in the trusted-users list

On top of that, each store path should be trusted as described in trusted-public-keys 🔑

Default: https://cache.nixos.org/

Deprecated alias: binary-caches

sync-before-registering — are we calling sync() before registering a path as valid, or not 🤔

Default: false

system — the system type of the current Nix installation. Nix only builds a given store derivation locally when its system attribute equals any of the values specified here, or in extra-platforms.

The default value is set when Nix itself is compiled for the system it'll run on. These system types are widely used, since Nix is actively supported on these platforms:

x86_64-linux
x86_64-darwin
i686-linux
aarch64-linux
aarch64-darwin
armv6l-linux
armv7l-linux

In general, you do not have to modify this setting, bestie. Sure, you can force Nix to run a Darwin-specific builder executable on a Linux machine — but the result would obviously be wrong 💀

This value is available in the Nix language as builtins.currentSystem if the eval-system configuration option is set as the empty string.

Default: x86_64-linux

system-features — a set of system "features" supported by this machine. It complements the system and extra-platforms configuration options and the corresponding system attribute on derivations.

A derivation can require system features in the requiredSystemFeatures attribute, and whichever machine builds that derivation must have them ✅

System features are user-defined, but Nix sets these defaults:

apple-virt — included on Darwin if virtualization is available.
kvm — included on Linux if /dev/kvm is accessible.
nixos-test, benchmark, big-parallel — these historical pseudo-features are always enabled for backwards compatibility, because they're used in Nixpkgs to route Hydra builds to specific machines.
ca-derivations — included by default if the ca-derivations experimental feature is enabled. This system feature is implicitly required by derivations with the __contentAddressed attribute.
recursive-nix — included by default if the recursive-nix experimental feature is enabled.
uid-range — on Linux, Nix can run builds in a user namespace where they run as root (UID 0) and have 65,536 UIDs available. This is primarily useful for running containers such as systemd-nspawn inside a Nix build. For an example, see tests/systemd-nspawn/nix. Included by default on Linux if the auto-allocate-uids setting is enabled.

The reference link from the manual:

[nspawn]: https://github.com/NixOS/nix/blob/67bcb99700a0da1395fa063d7c6586740b304598/tests/systemd-nspawn.nix

Default: machine-specific

tarball-ttl — how many seconds a downloaded tarball is considered fresh ⏳ If the cached tarball goes stale, Nix checks whether it's still up to date using the ETag header. Nix downloads a new version if the ETag header is unsupported, or if the cached ETag doesn't match.

Set the TTL to 0 and you force Nix to always check whether the tarball is up to date.

Nix caches tarballs in $XDG_CACHE_HOME/nix/tarballs.

Files fetched via NIX_PATH, fetchGit, fetchMercurial, fetchTarball, and fetchurl all respect this TTL.

Default: 3600

timeout — the maximum number of seconds a builder is allowed to run. This is genuinely useful (say, in an automated build system) to catch builds that are stuck in an infinite loop but keep writing to their standard output or standard error 👀 It can be overridden using the --timeout command line switch.

The value 0 means there is no timeout. That's also the default.

Default: 0

Deprecated alias: build-timeout

trace-function-calls — if set to true, the Nix evaluator traces every single function call. Nix prints a log message at the "vomit" level 💀 for every function entrance and function exit.

function-trace entered undefined position at 1565795816999559622
function-trace exited undefined position at 1565795816999581277
function-trace entered /nix/store/…/example.nix:226:41 at 1565795253249935150
function-trace exited /nix/store/…/example.nix:226:41 at 1565795253249941684

The undefined position means the function call is a builtin ✨

Use the contrib/stack-collapse.py script distributed with the Nix source code to convert the trace logs in to a format suitable for flamegraph.pl.

Default: false

trace-import-from-derivation — okay bestie, by default Nix allows Import from Derivation. When this setting is true, Nix logs a warning indicating that it performed such an import. This option has no effect if allow-import-from-derivation is disabled.

Default: false

trace-verbose — Whether builtins.traceVerbose should trace its first argument when evaluated. iykyk 🔍

Default: false

trust-tarballs-from-git-forges — If enabled (the default), Nix considers tarballs from GitHub and similar Git forges to be locked if a Git revision is specified, e.g. github:NixOS/patchelf/7c2f768bf9601268a4e71c2ebe91e2011918a70f. This requires Nix to trust that the provider returns the correct contents for the specified Git revision. trust fall, but make it cryptographic 💖

If disabled, such tarballs are only considered locked if a narHash attribute is specified, e.g. github:NixOS/patchelf/7c2f768bf9601268a4e71c2ebe91e2011918a70f?narHash=sha256-PPXqKY2hJng4DBVE0I4xshv/vGLUskL7jl53roB8UdU%3D. no narHash, no trust, periodt ✨

Default: true

trusted-public-keys — A whitespace-separated list of public keys. the VIP list, basically 🎀

At least one of the following condition must be met for Nix to accept copying a store object from another Nix store (such as a substituter):

the store object has been signed using a key in the trusted keys list
the require-sigs option has been set to false
the store URL is configured with trusted=true
the store object is content-addressed

Default: cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

Deprecated alias: binary-cache-public-keys

trusted-substituters — A list of Nix store URLs, separated by whitespace. These are not used by default, but users of the Nix daemon can enable them by specifying substituters. lowkey a secret menu 👑

Unprivileged users (those set in only allowed-users but not trusted-users) can pass as substituters only those URLs listed in trusted-substituters.

Default: empty

Deprecated alias: trusted-binary-caches

trusted-users — A list of user names, separated by whitespace. These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional substituters, or to import unsigned realisations or unsigned input-addressed store objects. main character energy, but for daemon privileges 💅

You can also specify groups by prefixing names with @. For instance, @wheel means all users in the wheel group.

Warning — Adding a user to trusted-users is essentially equivalent to giving that user root access to the system. For example, the user can access or replace store path contents that are critical for system security. not a drill, bestie 😭

Default: root

upgrade-nix-store-path-url — Used by nix upgrade-nix, the URL of the file that contains the store paths of the latest Nix release. the glow-up source 🦋

Default:

https://github.com/NixOS/nixpkgs/raw/master/nixos/modules/installer/tools/nix-
fallback-paths.nix

use-case-hack — Whether to enable a macOS-specific hack for dealing with file name case collisions. tiny hack, big vibe 🍓

Default: false

use-cgroups — Whether to execute builds inside cgroups. This is only supported on Linux. Linux girlies only 🐧

Cgroups are required and enabled automatically for derivations that require the uid-range system feature.

Default: false

use-registries —

Warning — This setting is part of an experimental feature. To change this setting, make sure the flakes experimental feature is enabled. For example, include the following in nix.conf: extra-experimental-features = flakes use-registries = ...

Whether to use flake registries to resolve flake references. flakes girlies, this is your moment ❄️

Default: true

use-sqlite-wal — Whether SQLite should use WAL mode. WAL mode is that girl 💚

Default: true

use-xdg-base-directories — If set to true, Nix conforms to the XDG Base Directory Specification for files in $HOME. The environment variables used to implement this are documented in the Environment Variables section. XDG said organize, and Nix listened ✨

Warning — This changes the location of some well-known symlinks that Nix creates, which might break tools that rely on the old, non-XDG-conformant locations. read this twice, bestie 😭

In particular, the following locations change:

~/.nix-profile → $XDG_STATE_HOME/nix/profile
~/.nix-defexpr → $XDG_STATE_HOME/nix/defexpr
~/.nix-channels → $XDG_STATE_HOME/nix/channels

If you already have Nix installed and are using profiles or channels, you should migrate manually when you enable this option. If $XDG_STATE_HOME is not set, use $HOME/.local/state/nix instead of $XDG_STATE_HOME/nix. This can be achieved with the following shell commands:

nix_state_home=${XDG_STATE_HOME-$HOME/.local/state}/nix
mkdir -p $nix_state_home
mv $HOME/.nix-profile $nix_state_home/profile
mv $HOME/.nix-defexpr $nix_state_home/defexpr
mv $HOME/.nix-channels $nix_state_home/channels

Default: false

user-agent-suffix — String appended to the user agent in HTTP requests. identity, but for HTTP 🌈

Default: empty

warn-dirty — Whether to warn about dirty Git/Mercurial trees. git status said what it said 💀

Default: true

warn-large-path-threshold — Warn when copying a path larger than this number of bytes to the Nix store (as determined by its NAR serialisation). Default is 0, which disables the warning. Set it to 1 to warn on all paths. big path? warn. all paths? also warn. 🍓

Default: 0

warn-short-path-literals — Deprecated. Use lint-short-path-literals = warn instead. she's retired, but not forgotten 🕊️

Default: false

And that's the whole nix.conf(5) page, bestie — source/version and date are chillin' in the footer of your local man page build, so go check that exact timestamp there. Stay slaying with your configs. 💅✨

📦 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-03: a language model's rewrite of the original, under its terms

nix.conf(5)

💖 nix.conf — Nix configuration file

💅 Name

🌸 Description

🎀 Configuration file

📝 File format

🚩 Command line flags

🔢 Integer settings

⭐ Available settings

abort-on-warn

accept-flake-config

access-tokens

allow-dirty

allow-dirty-locks

allow-import-from-derivation

allow-new-privileges

allow-symlinked-store

allow-unsafe-native-code-during-evaluation

allowed-impure-host-deps

allowed-uris

allowed-users

always-allow-substitutes

auto-allocate-uids

💖 `nix.conf` — Nix configuration file

`abort-on-warn`

`accept-flake-config`

`access-tokens`

`allow-dirty`

`allow-dirty-locks`

`allow-import-from-derivation`

`allow-new-privileges`

`allow-symlinked-store`

`allow-unsafe-native-code-during-evaluation`

`allowed-impure-host-deps`

`allowed-uris`

`allowed-users`

`always-allow-substitutes`

`auto-allocate-uids`