Passthru Attributes in Nix Derivations

# Passthru-attributes {#chap-passthru} []{#var-stdenv-passthru} []{#special-variables}  As opposed to most other `mkDerivation` input attributes, `passthru` is not passed to the derivation's [`builder` executable](https://nixos.org/manual/nix/stable/expressions/derivations.html#attr-builder). Changing it will not trigger a rebuild – it is "passed through". Its value can be accessed as if it was set inside a derivation. ::: {.note} `passthru` attributes follow no particular schema, but there are a few [conventional patterns](#sec-common-passthru-attributes). ::: :::{.example #ex-accessing-passthru} ## Setting and accessing `passthru` attributes ```nix { stdenv, fetchGit }: let hello = stdenv.mkDerivation { pname = "hello"; src = fetchGit { # ... }; passthru = { foo = "bar"; baz = { value1 = 4; value2 = 5; }; }; }; in hello.baz.value1 ``` ``` 4 ``` ::: ## Common `passthru`-attributes {#sec-common-passthru-attributes} Many `passthru` attributes are situational, so this section only lists recurring patterns. They fall in one of these categories: - Global conventions, which are applied almost universally in Nixpkgs. Generally these don't entail any special support built into the derivation they belong to. Common examples of this type are [`passthru.tests`](#var-passthru-tests) and [`passthru.updateScript`](#var-passthru-updateScript). - Conventions for adding extra functionality to a derivation. These tend to entail support from the derivation or the `passthru` attribute in question. Common examples of this type are `passthru.optional-dependencies`, `passthru.withPlugins`, and `passthru.withPackages`. All of those allow associating the package with a set of components built for that specific package, such as when building Python runtime environments using (`python.withPackages`)[#python.withpackages-function]. Attributes that apply only to particular [build helpers](#part-builders) or [language ecosystems](#chap-language-support) are documented there. ### `passthru.tests` {#var-passthru-tests} []{#var-meta-tests}  An attribute set with tests as values. A test is a derivation that builds when the test passes and fails to build otherwise. Run these tests with: ```ShellSession $ cd path/to/nixpkgs $ nix-build -A your-package.tests ``` :::{.note} The Nixpkgs systems for continuous integration [Hydra](https://hydra.nixos.org/) and [`nixpkgs-review`](https://github.com/Mic92/nixpkgs-review) don't build these derivations by default, and ([`@ofborg`](https://github.com/NixOS/ofborg)) only builds them when evaluating pull requests for that particular package, or when manually instructed. ::: #### Package tests {#var-passthru-tests-packages} []{#var-meta-tests-packages}  Besides tests provided by upstream, that you run in the [`checkPhase`](#ssec-check-phase), you may want to define tests derivations in the `passthru.tests` attribute, which won't change the build. `passthru.tests` have several advantages over running tests during any of the [standard phases](#sec-stdenv-phases): - They access the package as consumers would, independently from the environment in which it was built - They can be run and debugged without rebuilding the package, which is useful if that takes a long time - They don't add overhead to each build, as opposed checks added to the [`installCheckPhase`](#ssec-installCheck-phase), such as [`versionCheckHook`](#versioncheckhook). It is also possible to use `passthru.tests` to test the version with [`testVersion`](#tester-testVersion), but since that is pretty trivial and recommended thing to do, we recommend using [`versionCheckHook`](#versioncheckhook) for that, which has the following advantages over `passthru.tests`:

The `passthru` attribute in `mkDerivation` allows you to pass values that are accessible outside the derivation without affecting the build process. These attributes are not passed to the builder executable, and changes to them do not trigger rebuilds. They serve various purposes, including global conventions like `passthru.tests` and `passthru.updateScript`, as well as conventions for adding extra functionality such as `passthru.optional-dependencies` and `passthru.withPackages`. The `passthru.tests` attribute is commonly used to define test derivations that can be run independently of the build environment, offering advantages over running tests during standard phases.