Derivation Options

Title: Derivation Options

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: JSON representation of Nix's DerivationOptions type.

This schema describes various build-time options and constraints that can be specified for a derivation.

Warning

This JSON format is currently experimental and subject to change.

PropertyTypePatternTitle/Description
+ outputChecksCombinationNoOutput Check
+ unsafeDiscardReferencesobjectNoUnsafe Discard References
+ passAsFilearray of stringNoPass As File
+ exportReferencesGraphobjectNoExport References Graph
+ additionalSandboxProfilestringNoAdditional Sandbox Profile
+ noChrootbooleanNoNo Chroot
+ impureHostDepsarray of stringNoImpure Host Dependencies
+ impureEnvVarsarray of stringNoImpure Environment Variables
+ allowLocalNetworkingbooleanNoAllow Local Networking
+ requiredSystemFeaturesarray of stringNoRequired System Features
+ preferLocalBuildbooleanNoPrefer Local Build
+ allowSubstitutesbooleanNoAllow Substitutes

1. Property outputChecks

Title: Output Check

Typecombining
RequiredYes
Additional propertiesAny type allowed

Description: Constraints on what the derivation's outputs can and cannot reference. Can either apply to all outputs or be specified per output.

1.1. Property Output Checks For All Outputs

Title: Output Checks For All Outputs

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: Output checks that apply to all outputs of the derivation.

PropertyTypePatternTitle/Description
+ forAllOutputsobjectNoOutput Check Specification

1.1.1. Property forAllOutputs

Title: Output Check Specification

Typeobject
RequiredYes
Additional propertiesNot allowed
Defined in#/$defs/outputCheckSpec

Description: Constraints on what a specific output can reference.

PropertyTypePatternTitle/Description
+ ignoreSelfRefsbooleanNoIgnore Self References
+ maxSizeinteger or nullNoMaximum Size
+ maxClosureSizeinteger or nullNoMaximum Closure Size
+ allowedReferencesCombinationNoAllowed References
+ allowedRequisitesCombinationNoAllowed Requisites
+ disallowedReferencesarrayNoDisallowed References
+ disallowedRequisitesarrayNoDisallowed Requisites
1.1.1.1. Property ignoreSelfRefs

Title: Ignore Self References

Typeboolean
RequiredYes

Description: Whether references from this output to itself should be ignored when checking references.

1.1.1.2. Property maxSize

Title: Maximum Size

Typeinteger or null
RequiredYes

Description: Maximum allowed size of this output in bytes, or null for no limit.

Restrictions
Minimum≥ 0
1.1.1.3. Property maxClosureSize

Title: Maximum Closure Size

Typeinteger or null
RequiredYes

Description: Maximum allowed size of this output's closure in bytes, or null for no limit.

Restrictions
Minimum≥ 0
1.1.1.4. Property allowedReferences

Title: Allowed References

Typecombining
RequiredYes
Additional propertiesAny type allowed

Description: If set, the output can only reference paths in this list. If null, no restrictions apply.

One of(Option)
item 0
item 1
1.1.1.4.1. Property item 0
Typearray
RequiredNo
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
drvRef-
1.1.1.4.1.1. drvRef
Typecombining
RequiredNo
Additional propertiesAny type allowed
Defined in#/$defs/drvRef
1.1.1.4.1.1.1. Property Current derivation Output Reference

Title: Current derivation Output Reference

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: A reference to a specific output of the current derivation.

PropertyTypePatternTitle/Description
+ drvPathconstNoThis derivation
+ outputstringNoOutput Name
1.1.1.4.1.1.1.1. Property drvPath

Title: This derivation

Typeconst
RequiredYes

Description: Won't be confused for a deriving path

Specific value: "self"

1.1.1.4.1.1.1.2. Property output

Title: Output Name

Typestring
RequiredYes

Description: The name of the output being referenced.

1.1.1.4.1.1.2. Property Deriving Path

Title: Deriving Path

Typecombining
RequiredNo
Additional propertiesAny type allowed
Defined inderiving-path-v1.yaml

Description: This schema describes the JSON representation of Nix's Deriving Path.

One of(Option)
Constant
Output
1.1.1.4.1.1.2.1. Property Constant

Title: Constant

Typestring
RequiredNo
Defined instore-path-v1.yaml

Description: See Constant deriving path.

Restrictions
Min length34
Must match regular expression^[0123456789abcdfghijklmnpqrsvwxyz]{32}-.+$ Test
1.1.1.4.1.1.2.2. Property Output

Title: Output

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: See Output deriving path.

PropertyTypePatternTitle/Description
+ drvPathobjectNoDeriving Path
+ outputstringNoThe name of an output produced by that derivation (e.g. "out", "doc", etc.).
1.1.1.4.1.1.2.2.1. Property drvPath

Title: Deriving Path

Typecombining
RequiredYes
Additional propertiesAny type allowed
Same definition asDeriving Path

Description: A deriving path to a Derivation, whose output is being referred to.

1.1.1.4.1.1.2.2.2. Property output
Typestring
RequiredYes

Description: The name of an output produced by that derivation (e.g. "out", "doc", etc.).

1.1.1.4.2. Property item 1
Typenull
RequiredNo
1.1.1.5. Property allowedRequisites

Title: Allowed Requisites

Typecombining
RequiredYes
Additional propertiesAny type allowed

Description: If set, the output's closure can only contain paths in this list. If null, no restrictions apply.

One of(Option)
item 0
item 1
1.1.1.5.1. Property item 0
Typearray
RequiredNo
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
drvRef-
1.1.1.5.1.1. drvRef
Typecombining
RequiredNo
Additional propertiesAny type allowed
Same definition asoutputChecks_oneOf_i0_forAllOutputs_allowedReferences_oneOf_i0_items
1.1.1.5.2. Property item 1
Typenull
RequiredNo
1.1.1.6. Property disallowedReferences

Title: Disallowed References

Typearray
RequiredYes

Description: The output must not reference any paths in this list.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
drvRef-
1.1.1.6.1. drvRef
Typecombining
RequiredNo
Additional propertiesAny type allowed
Same definition asoutputChecks_oneOf_i0_forAllOutputs_allowedReferences_oneOf_i0_items
1.1.1.7. Property disallowedRequisites

Title: Disallowed Requisites

Typearray
RequiredYes

Description: The output's closure must not contain any paths in this list.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
drvRef-
1.1.1.7.1. drvRef
Typecombining
RequiredNo
Additional propertiesAny type allowed
Same definition asoutputChecks_oneOf_i0_forAllOutputs_allowedReferences_oneOf_i0_items

1.2. Property Output Checks Per Output

Title: Output Checks Per Output

Typeobject
RequiredNo
Additional propertiesNot allowed

Description: Output checks specified individually for each output.

PropertyTypePatternTitle/Description
+ perOutputobjectNo-

1.2.1. Property perOutput

Typeobject
RequiredYes
Additional propertiesEach additional property must conform to the schema
PropertyTypePatternTitle/Description
- objectNoOutput Check Specification
1.2.1.1. Property Output Check Specification

Title: Output Check Specification

Typeobject
RequiredNo
Additional propertiesNot allowed
Same definition asforAllOutputs

Description: Constraints on what a specific output can reference.

2. Property unsafeDiscardReferences

Title: Unsafe Discard References

Typeobject
RequiredYes
Additional propertiesEach additional property must conform to the schema

Description: A map specifying which references should be unsafely discarded from each output. This is generally not recommended and requires special permissions.

PropertyTypePatternTitle/Description
- array of stringNo-

2.1. Property additionalProperties

Typearray of string
RequiredNo
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
additionalProperties items-

2.1.1. additionalProperties items

Typestring
RequiredNo

3. Property passAsFile

Title: Pass As File

Typearray of string
RequiredYes

Description: List of environment variable names whose values should be passed as files rather than directly.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
passAsFile items-

3.1. passAsFile items

Typestring
RequiredNo

4. Property exportReferencesGraph

Title: Export References Graph

Typeobject
RequiredYes
Additional propertiesEach additional property must conform to the schema

Description: Specify paths whose references graph should be exported to files.

PropertyTypePatternTitle/Description
- arrayNo-

4.1. Property additionalProperties

Typearray
RequiredNo
Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
Deriving PathThis schema describes the JSON representation of Nix's Deriving Path.

4.1.1. Deriving Path

Title: Deriving Path

Typecombining
RequiredNo
Additional propertiesAny type allowed
Same definition asDeriving Path

Description: This schema describes the JSON representation of Nix's Deriving Path.

5. Property additionalSandboxProfile

Title: Additional Sandbox Profile

Typestring
RequiredYes

Description: Additional sandbox profile directives (macOS specific).

6. Property noChroot

Title: No Chroot

Typeboolean
RequiredYes

Description: Whether to disable the build sandbox, if allowed.

7. Property impureHostDeps

Title: Impure Host Dependencies

Typearray of string
RequiredYes

Description: List of host paths that the build can access.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
impureHostDeps items-

7.1. impureHostDeps items

Typestring
RequiredNo

8. Property impureEnvVars

Title: Impure Environment Variables

Typearray of string
RequiredYes

Description: List of environment variable names that should be passed through to the build from the calling environment.

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
impureEnvVars items-

8.1. impureEnvVars items

Typestring
RequiredNo

9. Property allowLocalNetworking

Title: Allow Local Networking

Typeboolean
RequiredYes

Description: Whether the build should have access to local network (macOS specific).

10. Property requiredSystemFeatures

Title: Required System Features

Typearray of string
RequiredYes

Description: List of system features required to build this derivation (e.g., "kvm", "nixos-test").

Array restrictions
Min itemsN/A
Max itemsN/A
Items unicityFalse
Additional itemsFalse
Tuple validationSee below
Each item of this array must beDescription
requiredSystemFeatures items-

10.1. requiredSystemFeatures items

Typestring
RequiredNo

11. Property preferLocalBuild

Title: Prefer Local Build

Typeboolean
RequiredYes

Description: Whether this derivation should preferably be built locally rather than its outputs substituted.

12. Property allowSubstitutes

Title: Allow Substitutes

Typeboolean
RequiredYes

Description: Whether substituting from other stores should be allowed for this derivation's outputs.


Examples

Input-addressed derivations

Default options

{
  "additionalSandboxProfile": "",
  "allowLocalNetworking": false,
  "allowSubstitutes": true,
  "exportReferencesGraph": {},
  "impureEnvVars": [],
  "impureHostDeps": [],
  "noChroot": false,
  "outputChecks": {
    "forAllOutputs": {
      "allowedReferences": null,
      "allowedRequisites": null,
      "disallowedReferences": [],
      "disallowedRequisites": [],
      "ignoreSelfRefs": true,
      "maxClosureSize": null,
      "maxSize": null
    }
  },
  "passAsFile": [],
  "preferLocalBuild": false,
  "requiredSystemFeatures": [],
  "unsafeDiscardReferences": {}
}

All options set

{
  "additionalSandboxProfile": "sandcastle",
  "allowLocalNetworking": true,
  "allowSubstitutes": false,
  "exportReferencesGraph": {
    "refs1": [
      "p0hax2lzvjpfc2gwkk62xdglz0fcqfzn-foo"
    ],
    "refs2": [
      "vj2i49jm2868j2fmqvxm70vlzmzvgv14-bar.drv"
    ]
  },
  "impureEnvVars": [
    "UNICORN"
  ],
  "impureHostDeps": [
    "/usr/bin/ditto"
  ],
  "noChroot": true,
  "outputChecks": {
    "forAllOutputs": {
      "allowedReferences": [
        "p0hax2lzvjpfc2gwkk62xdglz0fcqfzn-foo"
      ],
      "allowedRequisites": [
        {
          "drvPath": "self",
          "output": "bin"
        },
        "z0rjzy29v9k5qa4nqpykrbzirj7sd43v-foo-dev"
      ],
      "disallowedReferences": [
        {
          "drvPath": "self",
          "output": "dev"
        },
        "r5cff30838majxk5mp3ip2diffi8vpaj-bar"
      ],
      "disallowedRequisites": [
        "9b61w26b4avv870dw0ymb6rw4r1hzpws-bar-dev"
      ],
      "ignoreSelfRefs": true,
      "maxClosureSize": null,
      "maxSize": null
    }
  },
  "passAsFile": [],
  "preferLocalBuild": true,
  "requiredSystemFeatures": [
    "rainbow",
    "uid-range"
  ],
  "unsafeDiscardReferences": {}
}

Default options (structured attributes)

{
  "additionalSandboxProfile": "",
  "allowLocalNetworking": false,
  "allowSubstitutes": true,
  "exportReferencesGraph": {},
  "impureEnvVars": [],
  "impureHostDeps": [],
  "noChroot": false,
  "outputChecks": {
    "perOutput": {}
  },
  "passAsFile": [],
  "preferLocalBuild": false,
  "requiredSystemFeatures": [],
  "unsafeDiscardReferences": {}
}

All options set (structured attributes)

{
  "additionalSandboxProfile": "sandcastle",
  "allowLocalNetworking": true,
  "allowSubstitutes": false,
  "exportReferencesGraph": {
    "refs1": [
      "p0hax2lzvjpfc2gwkk62xdglz0fcqfzn-foo"
    ],
    "refs2": [
      "vj2i49jm2868j2fmqvxm70vlzmzvgv14-bar.drv"
    ]
  },
  "impureEnvVars": [
    "UNICORN"
  ],
  "impureHostDeps": [
    "/usr/bin/ditto"
  ],
  "noChroot": true,
  "outputChecks": {
    "perOutput": {
      "bin": {
        "allowedReferences": null,
        "allowedRequisites": null,
        "disallowedReferences": [
          {
            "drvPath": "self",
            "output": "dev"
          },
          "r5cff30838majxk5mp3ip2diffi8vpaj-bar"
        ],
        "disallowedRequisites": [
          "9b61w26b4avv870dw0ymb6rw4r1hzpws-bar-dev"
        ],
        "ignoreSelfRefs": false,
        "maxClosureSize": null,
        "maxSize": null
      },
      "dev": {
        "allowedReferences": null,
        "allowedRequisites": null,
        "disallowedReferences": [],
        "disallowedRequisites": [],
        "ignoreSelfRefs": false,
        "maxClosureSize": 5909,
        "maxSize": 789
      },
      "out": {
        "allowedReferences": [
          "p0hax2lzvjpfc2gwkk62xdglz0fcqfzn-foo"
        ],
        "allowedRequisites": [
          {
            "drvPath": "self",
            "output": "bin"
          },
          "z0rjzy29v9k5qa4nqpykrbzirj7sd43v-foo-dev"
        ],
        "disallowedReferences": [],
        "disallowedRequisites": [],
        "ignoreSelfRefs": false,
        "maxClosureSize": null,
        "maxSize": null
      }
    }
  },
  "passAsFile": [],
  "preferLocalBuild": true,
  "requiredSystemFeatures": [
    "rainbow",
    "uid-range"
  ],
  "unsafeDiscardReferences": {}
}

Content-addressed derivations

All options set

{
  "additionalSandboxProfile": "sandcastle",
  "allowLocalNetworking": true,
  "allowSubstitutes": false,
  "exportReferencesGraph": {
    "refs1": [
      {
        "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
        "output": "out"
      }
    ],
    "refs2": [
      "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv"
    ]
  },
  "impureEnvVars": [
    "UNICORN"
  ],
  "impureHostDeps": [
    "/usr/bin/ditto"
  ],
  "noChroot": true,
  "outputChecks": {
    "forAllOutputs": {
      "allowedReferences": [
        {
          "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
          "output": "out"
        }
      ],
      "allowedRequisites": [
        {
          "drvPath": "self",
          "output": "bin"
        },
        {
          "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
          "output": "dev"
        }
      ],
      "disallowedReferences": [
        {
          "drvPath": "self",
          "output": "dev"
        },
        {
          "drvPath": "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv",
          "output": "out"
        }
      ],
      "disallowedRequisites": [
        {
          "drvPath": "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv",
          "output": "dev"
        }
      ],
      "ignoreSelfRefs": true,
      "maxClosureSize": null,
      "maxSize": null
    }
  },
  "passAsFile": [],
  "preferLocalBuild": true,
  "requiredSystemFeatures": [
    "rainbow",
    "uid-range"
  ],
  "unsafeDiscardReferences": {}
}

All options set (structured attributes)

{
  "additionalSandboxProfile": "sandcastle",
  "allowLocalNetworking": true,
  "allowSubstitutes": false,
  "exportReferencesGraph": {
    "refs1": [
      {
        "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
        "output": "out"
      }
    ],
    "refs2": [
      "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv"
    ]
  },
  "impureEnvVars": [
    "UNICORN"
  ],
  "impureHostDeps": [
    "/usr/bin/ditto"
  ],
  "noChroot": true,
  "outputChecks": {
    "perOutput": {
      "bin": {
        "allowedReferences": null,
        "allowedRequisites": null,
        "disallowedReferences": [
          {
            "drvPath": "self",
            "output": "dev"
          },
          {
            "drvPath": "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv",
            "output": "out"
          }
        ],
        "disallowedRequisites": [
          {
            "drvPath": "qnml92yh97a6fbrs2m5qg5cqlc8vni58-bar.drv",
            "output": "dev"
          }
        ],
        "ignoreSelfRefs": false,
        "maxClosureSize": null,
        "maxSize": null
      },
      "dev": {
        "allowedReferences": null,
        "allowedRequisites": null,
        "disallowedReferences": [],
        "disallowedRequisites": [],
        "ignoreSelfRefs": false,
        "maxClosureSize": 5909,
        "maxSize": 789
      },
      "out": {
        "allowedReferences": [
          {
            "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
            "output": "out"
          }
        ],
        "allowedRequisites": [
          {
            "drvPath": "self",
            "output": "bin"
          },
          {
            "drvPath": "j56sf12rxpcv5swr14vsjn5cwm6bj03h-foo.drv",
            "output": "dev"
          }
        ],
        "disallowedReferences": [],
        "disallowedRequisites": [],
        "ignoreSelfRefs": false,
        "maxClosureSize": null,
        "maxSize": null
      }
    }
  },
  "passAsFile": [],
  "preferLocalBuild": true,
  "requiredSystemFeatures": [
    "rainbow",
    "uid-range"
  ],
  "unsafeDiscardReferences": {}
}