From c9e14abf7ebfc2b7a2994db91f62d8de90c1c101 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 14 Nov 2026 23:55:49 -0500 Subject: [PATCH] docs: add a supported versions page List the minimum expected and minimum tested version of each Python implementation, compiler, and dependency. Assisted-by: ClaudeCode:claude-opus-5-5 --- AGENTS.md | 1 + README.rst | 4 +- docs/index.rst | 1 + docs/supported.rst | 129 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 docs/supported.rst diff --git a/AGENTS.md b/AGENTS.md index b7d60f6610..06c90331c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,6 +100,7 @@ Packaging produces two distributions: the normal `pybind11` (headers live inside introduces or broadens a path that can discard or replace the primary error, flag it to the human reviewer and explain whether the policy's exceptional-case allowance is justified. +- If you change a minimum supported version (headers, CMake, `pyproject.toml`, or the CI matrix), update `docs/supported.rst`. - Try to add to an existing test file if possible (more files slow down tests). - Default C++ standard follows the consumer's toolchain; CI exercises a wide matrix (CPython 3.9+, PyPy, GraalPy; multiple compilers and C++ standards). Keep changes portable across that matrix. - PR descriptions follow a template, the key part is under "Suggested changelog entry", which is how we generate our changelog (with `nox -s make_changelog`) diff --git a/README.rst b/README.rst index c68f03bbf3..2a00cc984e 100644 --- a/README.rst +++ b/README.rst @@ -124,7 +124,9 @@ Supported platforms & compilers ------------------------------- pybind11 is exercised in continuous integration across a range of operating -systems, Python versions, C++ standards, and toolchains. For an up-to-date +systems, Python versions, C++ standards, and toolchains. The +`supported versions `_ +page lists the minimum version of each one. For an up-to-date view of the combinations we currently test, please see the `pybind11 GitHub Actions `_ and `AppVeyor `_ logs. diff --git a/docs/index.rst b/docs/index.rst index a25684f54f..633192da19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,7 @@ :maxdepth: 2 installing + supported basics classes compiling diff --git a/docs/supported.rst b/docs/supported.rst new file mode 100644 index 0000000000..2707c826d7 --- /dev/null +++ b/docs/supported.rst @@ -0,0 +1,129 @@ +.. _supported: + +Supported versions +################## + +This page lists the oldest version of each tool or dependency that pybind11 +supports. Each entry has two values: + +**Minimum expected** + The oldest version that we intend to work. Usually the headers or the build + system reject older versions with an error. We fix bugs reported for these + versions, but CI does not always test them. + +**Minimum tested** + The oldest version that CI tests. Versions between the two minimums + usually work, but we do not test them. + +When you change one of these minimums (in the headers, in CMake, in +``pyproject.toml``, or in the CI matrix), update this table too. + +Python +====== + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Implementation + - Minimum expected + - Minimum tested + - Notes + * - CPython + - 3.9 + - 3.9 + - + * - CPython, free-threaded + - 3.13t + - 3.14t + - See :ref:`misc_free_threading`. + * - CPython, stable ABI (``abi3``) + - 3.12 + - 3.12 + - See :doc:`advanced/stable_abi`. + * - CPython, free-threaded stable ABI (``abi3t``) + - 3.15t + - 3.15t + - + * - PyPy + - 3.10 + - 3.11 (v7.3.23) + - + * - GraalPy + - 25.0 + - 25.0 + - + +We plan to drop 3.13t support soon, as it was experimental. Use 3.14t or newer. + +C++ standard and compilers +========================== + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Compiler + - Minimum expected + - Minimum tested + - Notes + * - C++ standard + - C++11 + - C++11 + - CI tests C++11 through C++23. + * - GCC + - 4.8 + - 8 (AlmaLinux 8) + - + * - Clang + - 3.3 + - 5 + - + * - Apple Clang + - Xcode 5 + - Xcode 16 + - The version of the default macOS runner. + * - MSVC + - 2019 (19.20) + - 2022 + - GitHub Actions does not have MSVC 2019 runners. + * - Intel ICC (classic) + - 18 (C++11), 19 (C++14) + - Latest classic ICC + - + * - NVCC (CUDA) + - + - 12.2 + - + * - NVIDIA HPC SDK + - + - 26.5 + - + +Build tools and optional dependencies +===================================== + +.. list-table:: + :header-rows: 1 + :widths: 30 20 20 30 + + * - Tool + - Minimum expected + - Minimum tested + - Notes + * - CMake + - 3.15 + - 3.15 + - The newest tested version is 4.2. + * - Eigen + - 3.2.7 + - 3.3.9 + - ``pybind11/eigen/tensor.h`` needs Eigen 3.3.0 or newer. + * - NumPy + - + - 1.21 + - NumPy 2 needs pybind11 2.12 or newer. + * - scikit-build-core + - 0.11.2 + - latest + - Only needed to build the pybind11 Python package from source.