staging-next 2025-05-30 (#412425)

- `dontVersionCheck`: Disable adding this hook to the [`preInstallCheckHooks`](#ssec-installCheck-phase). Useful if you do want to load the bash functions of the hook, but run them differently.

- `versionCheckProgram`: The full path to the program that should print the `${version}` string. Defaults roughly to `${placeholder "out"}/bin/${pname}`. Using `$out` in the value of this variable won't work, as environment variables from this variable are not expanded by the hook. Hence using `placeholder` is unavoidable.

- `versionCheckProgramArg`: The argument that needs to be passed to `versionCheckProgram`. If undefined the hook tries first `--help` and then `--version`. Examples: `version`, `-V`, `-v`.

- `versionCheckKeepEnvironment`: A list of environment variables to keep and pass to the command. Only those variables should be added to this list that are actually required for the version command to work. If it is not feasible to explicitly list all these environment variables you can set this parameter to the special value `"*"` to disable the `--ignore-environment` flag and thus keep all environment variables.

- `preVersionCheck`: A hook to run before the check is done.

- `postVersionCheck`: A hook to run after the check is done.

and the aliases

* `pkgs.python2Packages` pointing to `pkgs.python27Packages`

* `pkgs.python3Packages` pointing to `pkgs.python312Packages`

* `pkgs.python3Packages` pointing to `pkgs.python313Packages`

* `pkgs.pythonPackages` pointing to `pkgs.python2Packages`

* `pkgs.pypy2Packages` pointing to `pkgs.pypy27Packages`

* `pkgs.pypy3Packages` pointing to `pkgs.pypy310Packages`

Several versions of the Python interpreter are available on Nix, as well as a

high amount of packages. The attribute `python3` refers to the default

interpreter, which is currently CPython 3.12. The attribute `python` refers to

interpreter, which is currently CPython 3.13. The attribute `python` refers to

CPython 2.7 for backwards-compatibility. It is also possible to refer to

specific versions, e.g. `python312` refers to CPython 3.12, and `pypy` refers to

specific versions, e.g. `python313` refers to CPython 3.13, and `pypy` refers to

the default PyPy interpreter.

Python is used a lot, and in different ways. This affects also how it is

The interpreters have several common attributes. One of these attributes is

`pkgs`, which is a package set of Python libraries for this specific

interpreter. E.g., the `toolz` package corresponding to the default interpreter

is `python3.pkgs.toolz`, and the CPython 3.12 version is `python312.pkgs.toolz`.

is `python3.pkgs.toolz`, and the CPython 3.13 version is `python313.pkgs.toolz`.

The main package set contains aliases to these package sets, e.g.

`pythonPackages` refers to `python.pkgs` and `python312Packages` to

`python312.pkgs`.

`pythonPackages` refers to `python.pkgs` and `python313Packages` to

`python313.pkgs`.

#### Installing Python and packages {#installing-python-and-packages}

executables are wrapped to be able to find each other and all of the modules.

In the following examples we will start by creating a simple, ad-hoc environment

with a nix-shell that has `numpy` and `toolz` in Python 3.12; then we will create

with a nix-shell that has `numpy` and `toolz` in Python 3.13; then we will create

a re-usable environment in a single-file Python script; then we will create a

full Python environment for development with this same environment.

their runtime dependencies), with no other Python packages in the Python

interpreter's scope.

To create a Python 3.12 session with `numpy` and `toolz` available, run:

To create a Python 3.13 session with `numpy` and `toolz` available, run:

```sh

$ nix-shell -p 'python312.withPackages(ps: with ps; [ numpy toolz ])'

$ nix-shell -p 'python313.withPackages(ps: with ps; [ numpy toolz ])'

```

By default `nix-shell` will start a `bash` session with this interpreter in our

```Python console

[nix-shell:~/src/nixpkgs]$ python3

Python 3.12.4 (main, Jun  6 2024, 18:26:44) [GCC 13.3.0] on linux

Python 3.13.3 (main, Apr  8 2025, 13:54:08) [GCC 14.2.1 20250322] on linux

Type "help", "copyright", "credits" or "license" for more information.

>>> import numpy; import toolz

```

directly like so:

```sh

$ nix-shell -p "python312.withPackages (ps: with ps; [ numpy toolz requests ])" --run python3

Python 3.12.4 (main, Jun  6 2024, 18:26:44) [GCC 13.3.0] on linux

$ nix-shell -p "python313.withPackages (ps: with ps; [ numpy toolz requests ])" --run python3

Python 3.13.3 (main, Apr  8 2025, 13:54:08) [GCC 14.2.1 20250322] on linux

Type "help", "copyright", "credits" or "license" for more information.

>>> import requests

>>>

in the previous section, we could startup a shell and just run it like so:

```ShellSession

$ nix-shell -p 'python312.withPackages (ps: with ps; [ numpy ])' --run 'python3 foo.py'

$ nix-shell -p 'python313.withPackages (ps: with ps; [ numpy ])' --run 'python3 foo.py'

The dot product of [1 2] and [3 4] is: 11

```

development we're usually working in an entire package repository.

As explained [in the `nix-shell` section](https://nixos.org/manual/nix/stable/command-ref/nix-shell) of the Nix manual, `nix-shell` can also load an expression from a `.nix` file.

Say we want to have Python 3.12, `numpy` and `toolz`, like before,

Say we want to have Python 3.13, `numpy` and `toolz`, like before,

in an environment. We can add a `shell.nix` file describing our dependencies:

```nix

with import <nixpkgs> { };

(python312.withPackages (

(python313.withPackages (

  ps: with ps; [

    numpy

    toolz

   imports the `<nixpkgs>` function, `{}` calls it and the `with` statement

   brings all attributes of `nixpkgs` in the local scope. These attributes form

   the main package set.

2. Then we create a Python 3.12 environment with the [`withPackages`](#python.withpackages-function) function, as before.

2. Then we create a Python 3.13 environment with the [`withPackages`](#python.withpackages-function) function, as before.

3. The [`withPackages`](#python.withpackages-function) function expects us to provide a function as an argument

   that takes the set of all Python packages and returns a list of packages to

   include in the environment. Here, we select the packages `numpy` and `toolz`

```nix

with import <nixpkgs> { };

let

  pythonEnv = python312.withPackages (ps: [

  pythonEnv = python313.withPackages (ps: [

    ps.numpy

    ps.toolz

  ]);

An expression for `toolz` can be found in the Nixpkgs repository. As explained

in the introduction of this Python section, a derivation of `toolz` is available

for each interpreter version, e.g. `python312.pkgs.toolz` refers to the `toolz`

derivation corresponding to the CPython 3.12 interpreter.

for each interpreter version, e.g. `python313.pkgs.toolz` refers to the `toolz`

derivation corresponding to the CPython 3.13 interpreter.

The above example works when you're directly working on

`pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,

(

  let

    my_toolz = python312.pkgs.buildPythonPackage rec {

    my_toolz = python313.pkgs.buildPythonPackage rec {

      pname = "toolz";

      version = "0.10.0";

      pyproject = true;

      };

      build-system = [

        python312.pkgs.setuptools

        python313.pkgs.setuptools

      ];

      # has no tests

    };

  in

  python312.withPackages (

  python313.withPackages (

    ps: with ps; [

      numpy

      my_toolz

```

Executing `nix-shell` will result in an environment in which you can use

Python 3.12 and the `toolz` package. As you can see we had to explicitly mention

Python 3.13 and the `toolz` package. As you can see we had to explicitly mention

for which Python version we want to build a package.

So, what did we do here? Well, we took the Nix expression that we used earlier

When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will

have timestamp 1. The [`buildPythonPackage`](#buildpythonpackage-function) function sets `DETERMINISTIC_BUILD=1`

and [PYTHONHASHSEED=0](https://docs.python.org/3.12/using/cmdline.html#envvar-PYTHONHASHSEED).

and [PYTHONHASHSEED=0](https://docs.python.org/3.13/using/cmdline.html#envvar-PYTHONHASHSEED).

Both are also exported in `nix-shell`.

### How to provide automatic tests to Python packages? {#automatic-tests}

  It does not need to be set explicitly unless the package requires a specific platform.

* The file is formatted with `nixfmt-rfc-style`.

* Commit names of Python libraries must reflect that they are Python

  libraries (e.g. `python312Packages.numpy: 1.11 -> 1.12` rather than `numpy: 1.11 -> 1.12`).

  libraries (e.g. `python313Packages.numpy: 1.11 -> 1.12` rather than `numpy: 1.11 -> 1.12`).

* The current default version of python should be included

  in commit messages to enable automatic builds by ofborg.

  For example `python312Packages.numpy: 1.11 -> 1.12` should be used rather

  For example `python313Packages.numpy: 1.11 -> 1.12` should be used rather

  than `python3Packages.numpy: 1.11 -> 1.12`.

  Note that `pythonPackages` is an alias for `python27Packages`.

* Attribute names in `python-packages.nix` as well as `pname`s should match the

  "footnote-stdenv-find-inputs-location.__back.0": [

    "index.html#footnote-stdenv-find-inputs-location.__back.0"

  ],

  "strictflexarrays1": [

    "index.html#strictflexarrays1"

  ],

  "strictflexarrays3": [

    "index.html#strictflexarrays3"

  ],

  "tester-shfmt": [

    "index.html#tester-shfmt"

  ],

- Added `rewriteURL` attribute to the nixpkgs `config`, to allow for rewriting the URLs downloaded by `fetchurl`.

- `vmalert` now supports multiple instances with the option `services.vmalert.instances."".enable`

  et al..

- New hardening flags, `strictflexarrays1` and `strictflexarrays3` were made available, corresponding to the gcc/clang options `-fstrict-flex-arrays=1` and `-fstrict-flex-arrays=3` respectively.

- `gramps` has been updated to 6.0.0

  Upstream recommends [backing up your Family Trees](https://gramps-project.org/wiki/index.php/Gramps_6.0_Wiki_Manual_-_Manage_Family_Trees#Backing_up_a_Family_Tree) before upgrading.

Static libraries need to be compiled with `-fPIE` so that executables can link them in with the `-pie` linker option.

If the libraries lack `-fPIE`, you will get the error `recompile with -fPIE`.

#### `strictflexarrays1` {#strictflexarrays1}

This flag adds the `-fstrict-flex-arrays=1` compiler option, which reduces the cases the compiler treats as "flexible arrays" to those declared with length `[1]`, `[0]` or (the correct) `[]`. This increases the coverage of fortify checks, because such arrays declared as the trailing element of a structure can normally not have their intended length determined by the compiler.

Enabling this flag on packages that still use length declarations of flexible arrays >1 may cause the package to fail to compile citing accesses beyond the bounds of an array or even crash at runtime by detecting an array access as an "overrun". Few projects still use length declarations of flexible arrays >1.

Disabling `strictflexarrays1` implies disablement of `strictflexarrays3`.

#### `strictflexarrays3` {#strictflexarrays3}

This flag adds the `-fstrict-flex-arrays=3` compiler option, which reduces the cases the compiler treats as "flexible arrays" to only those declared with length as (the correct) `[]`. This increases the coverage of fortify checks, because such arrays declared as the trailing element of a structure can normally not have their intended length determined by the compiler.

Enabling this flag on packages that still use non-empty length declarations for flexible arrays may cause the package to fail to compile citing accesses beyond the bounds of an array or even crash at runtime by detecting an array access as an "overrun". Many projects still use such non-empty length declarations for flexible arrays.

Enabling this flag implies enablement of `strictflexarrays1`. Disabling this flag does not imply disablement of `strictflexarrays1`.

#### `shadowstack` {#shadowstack}

Adds the `-fcf-protection=return` compiler option. This enables the Shadow Stack feature supported by some newer processors, which maintains a user-inaccessible copy of the program's stack containing only return-addresses. When returning from a function, the processor compares the return-address value on the two stacks and throws an error if they do not match, considering it a sign of corruption and possible tampering. This should significantly increase the difficulty of ROP attacks.