Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Advanced Attributes

Derivations can declare some infrequently used optional attributes.

Inputs

  • exportReferencesGraph
    Specifies the export references graph option. The value of this attribute should be a list of pairs [ name1 path1 name2 path2 ... ]. For example, when the following derivation is built:

    derivation {
  ...
  exportReferencesGraph = [ "libfoo-graph" libfoo ];
};

    the references graph of libfoo is placed in the file libfoo-graph in the temporary build directory.

  • passAsFile
    A list of names of attributes whose environment variables should be marked pass as file. For example, if you have

    passAsFile = ["big"];
big = "a very long string";

    then when the builder runs, the environment variable bigPath will contain the absolute path to a temporary file containing a very long string.

  • __structuredAttrs
    If the special attribute __structuredAttrs is set to true, the other derivation attributes are serialised into a file in JSON format.

    See the corresponding section in the derivation page for further details.

    Warning

    If set to true, the top-level attributes allowedReferences, allowedRequisites, disallowedReferences and disallowedRequisites will have no effect; use outputChecks instead.

Output checks

These attributes specify checks on the derivation’s outputs. The concepts behind them are documented there; this section gives the syntax for specifying them from the Nix language.

Store paths in these lists may be given as strings with context (i.e. by interpolating a derivation), and outputs of the derivation itself are denoted by their plain output names, e.g. "out".

  • allowedReferences
    Specifies the allowed references check. 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.

  • allowedRequisites
    Specifies the allowed requisites check. For example,

    allowedRequisites = [ foobar ];

    enforces that the output of a derivation cannot have any other runtime dependency than foobar, and in addition it enforces that foobar itself doesn’t introduce any other dependency itself.

  • disallowedReferences
    Specifies the disallowed references check. For example,

    disallowedReferences = [ foo ];

    enforces that the output of a derivation cannot have a direct runtime dependency on the derivation foo.

  • disallowedRequisites
    Specifies the disallowed requisites check. For example,

    disallowedRequisites = [ foobar ];

    enforces that the output of a derivation cannot have any runtime dependency on foobar or any other derivation depending recursively on foobar.

  • outputChecks
    When using structured attributes, the outputChecks attribute allows defining checks per-output.

    In addition to allowedReferences, allowedRequisites, disallowedReferences and disallowedRequisites, the following attributes are available:

    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;
};

Other output modifications

Build scheduling

  • preferLocalBuild
    If set to true, enables the prefer local build option. This is useful for derivations that are cheapest to build locally.

  • allowSubstitutes
    If set to false, disables the allow substitutes option, so Nix will always build this derivation (locally or remotely) rather than substituting its outputs. This is useful for derivations that are cheaper to build than to substitute.

  • requiredSystemFeatures
    Specifies the required system features option: Nix will only build the derivation on a machine that has the corresponding features set in its system-features configuration.

    For example, setting

    requiredSystemFeatures = [ "kvm" ];

    ensures that the derivation can only be built on a machine with the kvm feature.

Impure builder configuration

  • impureEnvVars
    Specifies the impure environment variables option: a list of environment variables that should be passed from the environment of the calling user to the builder. For example, fetchurl in Nixpkgs has the line

    impureEnvVars = [ "http_proxy" "https_proxy" ... ];

    to make it use the proxy server configuration specified by the user in the environment variables http_proxy and friends.

Setting the derivation type

As discussed in Derivation Outputs and Types of Derivations, there are multiples kinds of derivations / kinds of derivation outputs. The choice of the following attributes determines which kind of derivation we are making.

The three types of derivations are chosen based on the following combinations of these attributes. All other combinations are invalid.

Here is more information on the output* attributes, and what values they may be set to:

  • outputHashMode

    This specifies how the files of a content-addressing derivation output are digested to produce a content address.

    This works in conjunction with outputHashAlgo. Specifying one without the other is an error (unless [outputHash is also specified and includes its own hash algorithm as described below).

    The outputHashMode attribute determines how the hash is computed. It must be one of the following values:

    • "flat"

      This is the default.

    • "recursive" or "nar"

      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.

    • "text"

      Warning

      The use of this method for derivation outputs is part of the dynamic-derivations experimental feature.

    • "git"

      Warning

      This method is part of the git-hashing experimental feature.

    See content-addressing store objects for more information about the process this flag controls.

  • outputHashAlgo

    This specifies the hash algorithm used to digest the file system object data of a content-addressing derivation output.

    This works in conjunction with outputHashMode. Specifying one without the other is an error (unless outputHash is also specified and includes its own hash algorithm as described below).

    The outputHashAlgo attribute specifies the hash algorithm used to compute the hash. It can currently be "blake3", "sha1", "sha256", "sha512", or null.

    outputHashAlgo can only be null when outputHash follows the SRI format, because in that case the choice of hash algorithm is determined by outputHash.

  • outputHash

    This will specify the output hash of the single output of a fixed-output derivation.

    The outputHash attribute 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 Nix’s variant of Base32 encoding.

    Note

    The convertHash function shows how to convert between different encodings. The nix-hash command has information about obtaining the hash for some contents, as well as converting to and from encodings.

  • __contentAddressed

    Warning

    This attribute is part of an experimental feature.

    To use this attribute, you must enable the [ca-derivations][xp-feature-ca-derivations] experimental feature. For example, in nix.conf you could add:

    extra-experimental-features = ca-derivations

    This is a boolean with a default of false. It determines whether the derivation is floating content-addressing.