#4031·Nuitka

recommend an explicit CPython version range for each release

Author: h3harCreated Sep 9, 2026Updated Sep 14, 2026
Labelsenhancementexcellent_report

In theory, the release of a new CPython patch version can always introduce undefined behaviour into any wheel that was compiled with Nuitka prior to that release even if the wheel tag implies compatibility (e.g., cp314), since there's no way that Nuitka at the time could have guaranteed support for a not-yet-known CPython release, due to the reliance on unstable internal APIs, memory layouts, etc.

I recommend properly tracking which CPython patch version ranges each Nuitka release is intended to support (i.e., versions that it has been developed/tested against) so that users can actually avoid running Nuitka wheels by accident on CPython versions that may be completely incompatible or may introduce undefined behaviour into their program (not even as a result of a Nuitka "bug").

For example:

  • Custom static metadata in Nuitka distributions (e.g., *.dist-info/nuitka.json)
  • Metadata accessible from nuitka at runtime (e.g., via the CLI, or via a Python API)
  • Metadata recorded in Nuitka compiled modules (e.g., via a module's __compiled__ attribute)
  • ...or all of the above

It's then up to users of Nuitka how they want to use this information (e.g., they could use it to constrain the Requires-Python in distributions for packages compiled with Nuitka to avoid running on versions that may produce undefined behaviour and then issue new patch releases with builds from newer Nuitka versions and looser Requires-Python requirements).