Nix `passthru` Attributes and Their Uses

# 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 a pretty trivial and recommended thing to do, we recommend using [`versionCheckHook`](#versioncheckhook) for that, which has the following advantages over `passthru.tests`:

This document explains `passthru` attributes, a special type of input for `mkDerivation` in Nix that are not passed to the builder executable and do not trigger rebuilds. `passthru` allows associating additional metadata or functionality with a derivation, which can be accessed externally. While they follow no strict schema, common patterns include global conventions like `passthru.tests` and attributes for extending derivation functionality such as `passthru.withPlugins`. The text provides an example of setting and accessing `passthru` attributes and elaborates on `passthru.tests`, which are derivations used for independent package testing, offering benefits like debugging without rebuilding and avoiding overhead during the main package build.