Advanced Attributes
Derivations can declare some infrequently used optional attributes.
- 
allowedReferences
 The optional attributeallowedReferencesspecifies a list of legal references (dependencies) of the output of the builder. For example,allowedReferences = [];enforces that the output of a derivation cannot have any runtime dependencies on its inputs. To allow an output to have a runtime dependency on itself, use "out"as a list item. This is used in NixOS to check that generated files such as initial ramdisks for booting Linux don’t have accidental dependencies on other paths in the Nix store.
- 
allowedRequisites
 This attribute is similar toallowedReferences, but it specifies the legal requisites of the whole closure, so all the dependencies recursively. For example,allowedRequisites = [ foobar ];enforces that the output of a derivation cannot have any other runtime dependency than foobar, and in addition it enforces thatfoobaritself doesn't introduce any other dependency itself.
- 
disallowedReferences
 The optional attributedisallowedReferencesspecifies a list of illegal references (dependencies) of the output of the builder. For example,disallowedReferences = [ foo ];enforces that the output of a derivation cannot have a direct runtime dependencies on the derivation foo.
- 
disallowedRequisites
 This attribute is similar todisallowedReferences, but it specifies illegal requisites for the whole closure, so all the dependencies recursively. For example,disallowedRequisites = [ foobar ];enforces that the output of a derivation cannot have any runtime dependency on foobaror any other derivation depending recursively onfoobar.
- 
exportReferencesGraph
 This attribute allows builders access to the references graph of their inputs. The attribute is a list of inputs in the Nix store whose references graph the builder needs to know. The value of this attribute should be a list of pairs[ name1 path1 name2 path2 ... ]. The references graph of each pathN will be stored in a text file nameN in the temporary build directory. The text files have the format used bynix-store --register-validity(with the deriver fields left empty). For example, when the following derivation is built:derivation { ... exportReferencesGraph = [ "libfoo-graph" libfoo ]; };the references graph of libfoois placed in the filelibfoo-graphin the temporary build directory.exportReferencesGraphis useful for builders that want to do something with the closure of a store path. Examples include the builders in NixOS that generate the initial ramdisk for booting Linux (acpioarchive containing the closure of the boot script) and the ISO-9660 image for the installation CD (which is populated with a Nix store containing the closure of a bootable NixOS configuration).
- 
impureEnvVars
 This attribute allows you to specify a list of environment variables that should be passed from the environment of the calling user to the builder. Usually, the environment is cleared completely when the builder is executed, but with this attribute you can allow specific environment variables to be passed unmodified. For example,fetchurlin Nixpkgs has the lineimpureEnvVars = [ "http_proxy" "https_proxy" ... ];to make it use the proxy server configuration specified by the user in the environment variables http_proxyand friends.This attribute is only allowed in fixed-output derivations (see below), where impurities such as these are okay since (the hash of) the output is known in advance. It is ignored for all other derivations. Warning impureEnvVarsimplementation takes environment variables from the current builder process. When a daemon is building its environmental variables are used. Without the daemon, the environmental variables come from the environment of thenix-build.If the configurable-impure-envexperimental feature is enabled, these environment variables can also be controlled through theimpure-envconfiguration setting.
- 
outputHash;outputHashAlgo;outputHashMode
 These attributes declare that the derivation is a so-called fixed-output derivation (FOD), which means that a cryptographic hash of the output is already known in advance.As opposed to regular derivations, the builderexecutable of a fixed-output derivation has access to the network. Nix computes a cryptographic hash of its output and compares that to the hash declared with these attributes. If there is a mismatch, the derivation fails.The rationale for fixed-output derivations is derivations such as those produced by the fetchurlfunction. This function downloads a file from a given URL. To ensure that the downloaded file has not been modified, the caller must also specify a cryptographic hash of the file. For example,fetchurl { url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; }It sometimes happens that the URL of the file changes, e.g., because servers are reorganised or no longer available. We then must update the call to fetchurl, e.g.,fetchurl { url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; }If a fetchurlderivation was treated like a normal derivation, the output paths of the derivation and all derivations depending on it would change. For instance, if we were to change the URL of the Glibc source distribution in Nixpkgs (a package on which almost all other packages depend) massive rebuilds would be needed. This is unfortunate for a change which we know cannot have a real effect as it propagates upwards through the dependency graph.For fixed-output derivations, on the other hand, the name of the output path only depends on the outputHash*andnameattributes, while all other attributes are ignored for the purpose of computing the output path. (Thenameattribute is included because it is part of the path.)As an example, here is the (simplified) Nix expression for fetchurl:{ stdenv, curl }: # The curl program is used for downloading. { url, sha256 }: stdenv.mkDerivation { name = baseNameOf (toString url); builder = ./builder.sh; buildInputs = [ curl ]; # This is a fixed-output derivation; the output must be a regular # file with SHA256 hash sha256. outputHashMode = "flat"; outputHashAlgo = "sha256"; outputHash = sha256; inherit url; }The outputHashattribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by SRI. The "nix32" encoding is an adaptation of base-32 encoding. TheconvertHashfunction shows how to convert between different encodings, and thenix-hashcommand has information about obtaining the hash for some contents, as well as converting to and from encodings.The outputHashAlgoattribute specifies the hash algorithm used to compute the hash. It can currently be"sha1","sha256","sha512", ornull.outputHashAlgocan only benullwhenoutputHashfollows the SRI format.The outputHashModeattribute determines how the hash is computed. It must be one of the following values:- 
This is the default. 
- 
Compatibility "recursive"is the traditional way of indicating this, and is supported since 2005 (virtually the entire history of Nix)."nar"is more clear, and consistent with other parts of Nix (such as the CLI), however support for it is only added in Nix version 2.21.
- 
Warning The use of this method for derivation outputs is part of the dynamic-derivationsexperimental feature.
- 
Warning This method is part of the git-hashingexperimental feature.
 
- 
- 
Warning This attribute is part of an experimental feature. To use this attribute, you must enable the ca-derivationsexperimental feature. For example, in nix.conf you could add:extra-experimental-features = ca-derivationsIf this attribute is set to true, then the derivation outputs will be stored in a content-addressed location rather than the traditional input-addressed one.Setting this attribute also requires setting outputHashModeandoutputHashAlgolike for fixed-output derivations (see above).It also implicitly requires that the machine to build the derivation must have the ca-derivationssystem feature.
- 
passAsFile
 A list of names of attributes that should be passed via files rather than environment variables. For example, if you havepassAsFile = ["big"]; big = "a very long string";then when the builder runs, the environment variable bigPathwill contain the absolute path to a temporary file containinga very long string. That is, for any attribute x listed inpassAsFile, Nix will pass an environment variablexPathholding the path of the file containing the value of attribute x. This is useful when you need to pass large strings to a builder, since most operating systems impose a limit on the size of the environment (typically, a few hundred kilobyte).
- 
preferLocalBuild
 If this attribute is set totrueand distributed building is enabled, then, if possible, the derivation will be built locally instead of being forwarded to a remote machine. This is useful for derivations that are cheapest to build locally.
- 
allowSubstitutes
 If this attribute is set tofalse, then Nix will always build this derivation (locally or remotely); it will not try to substitute its outputs. This is useful for derivations that are cheaper to build than to substitute.This attribute can be ignored by setting always-allow-substitutestotrue.Note If set to false, thebuildershould be able to run on the system type specified in thesystemattribute, since the derivation cannot be substituted.
- 
__structuredAttrs
 If the special attribute__structuredAttrsis set totrue, the other derivation attributes are serialised into a file in JSON format. The environment variableNIX_ATTRS_JSON_FILEpoints to the exact location of that file both in a build and anix-shell. This obviates the need forpassAsFilesince JSON files have no size restrictions, unlike process environments.It also makes it possible to tweak derivation settings in a structured way; see outputChecksfor example.As a convenience to Bash builders, Nix writes a script that initialises shell variables corresponding to all attributes that are representable in Bash. The environment variable NIX_ATTRS_SH_FILEpoints to the exact location of the script, both in a build and anix-shell. This includes non-nested (associative) arrays. For example, the attributehardening.format = trueends up as the Bash associative array element${hardening[format]}.Warning If set to true, other advanced attributes such asallowedReferences,allowedReferences,allowedRequisites,disallowedReferencesanddisallowedRequisites, maxSize, and maxClosureSize. will have no effect.
- 
outputChecks
 When using structured attributes, theoutputChecksattribute allows defining checks per-output.In addition to allowedReferences,allowedRequisites,disallowedReferencesanddisallowedRequisites, the following attributes are available:- maxSizedefines the maximum size of the resulting store object.
- maxClosureSizedefines the maximum size of the output's closure.
- ignoreSelfRefscontrols whether self-references should be considered when checking for allowed references/requisites.
 Example: __structuredAttrs = true; outputChecks.out = { # The closure of 'out' must not be larger than 256 MiB. maxClosureSize = 256 * 1024 * 1024; # It must not refer to the C compiler or to the 'dev' output. disallowedRequisites = [ stdenv.cc "dev" ]; }; outputChecks.dev = { # The 'dev' output must not be larger than 128 KiB. maxSize = 128 * 1024; };
- 
When using structured attributes, the attribute unsafeDiscardReferencesis an attribute set with a boolean value for each output name. If set totrue, it disables scanning the output for runtime dependencies.Example: __structuredAttrs = true; unsafeDiscardReferences.out = true;This is useful, for example, when generating self-contained filesystem images with their own embedded Nix store: hashes found inside such an image refer to the embedded store and not to the host's Nix store. 
- 
If a derivation has the requiredSystemFeaturesattribute, then Nix will only build it on a machine that has the corresponding features set in itssystem-featuresconfiguration.For example, setting requiredSystemFeatures = [ "kvm" ];ensures that the derivation can only be built on a machine with the kvmfeature.