From c9e14abf7ebfc2b7a2994db91f62d8de90c1c101 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 14 Nov 2026 23:55:49 -0500 Subject: [PATCH 1/4] 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. From 0c491e866835e08dd82fd2165661734e63cf29b0 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sun, 15 Nov 2026 21:50:04 -0500 Subject: [PATCH 2/4] docs: remove outdated entries from limitations page Assisted-by: ClaudeCode:claude-opus-5-5 --- docs/limitations.rst | 33 +++++---------------------------- 1 file changed, 5 insertions(+), 28 deletions(-) diff --git a/docs/limitations.rst b/docs/limitations.rst index 1b06ea8728..6de87573fb 100644 --- a/docs/limitations.rst +++ b/docs/limitations.rst @@ -24,21 +24,6 @@ pybind11; see `pybind11_json `_ for an example. -Known bugs -^^^^^^^^^^ - -These are issues that hopefully will one day be fixed, but currently are -unsolved. If you know how to help with one of these issues, contributions -are welcome! - -- Intel 20.2 is currently having an issue with the test suite. - `#2573 `_ - -- Debug mode Python does not support 1-5 tests in the test suite currently. - `#2422 `_ - -- PyPy3 7.3.1 and 7.3.2 have issues with several tests on 32-bit Windows. - Known limitations ^^^^^^^^^^^^^^^^^ @@ -53,16 +38,8 @@ clean, well written patch would likely be accepted to solve them. Python 3.9.0 warning ^^^^^^^^^^^^^^^^^^^^ -Combining older versions of pybind11 (< 2.6.0) with Python on exactly 3.9.0 -will trigger undefined behavior that typically manifests as crashes during -interpreter shutdown (but could also destroy your data. **You have been -warned**). - -This issue was `fixed in Python `_. -As a mitigation for this bug, pybind11 2.6.0 or newer includes a workaround -specifically when Python 3.9.0 is detected at runtime, leaking about 50 bytes -of memory when a callback function is garbage collected. For reference, the -pybind11 test suite has about 2,000 such callbacks, but only 49 are garbage -collected before the end-of-process. Wheels (even if built with Python 3.9.0) -will correctly avoid the leak when run in Python 3.9.1, and this does not -affect other 3.X versions. +pybind11 older than 2.6.0 with Python 3.9.0 causes undefined behavior, which +usually shows as a crash at interpreter shutdown. The bug was `fixed in Python +3.9.1 `_. pybind11 2.6.0 and newer +detect 3.9.0 at runtime and leak about 50 bytes each time a callback function is +garbage collected to avoid the bug. Use Python 3.9.1 or newer. From 8d7888bdfa74a55ab64d650fbf5b6fbc2f290f27 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sun, 15 Nov 2026 21:53:32 -0500 Subject: [PATCH 3/4] docs: revise supported versions page Assisted-by: ClaudeCode:claude-opus-5-5 --- docs/index.rst | 2 +- docs/supported.rst | 30 ++++++++++++------------------ 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 633192da19..f10e51779e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,7 +20,6 @@ :maxdepth: 2 installing - supported basics classes compiling @@ -47,5 +46,6 @@ faq benchmark limitations + supported reference cmake/index diff --git a/docs/supported.rst b/docs/supported.rst index 2707c826d7..d056a38329 100644 --- a/docs/supported.rst +++ b/docs/supported.rst @@ -6,17 +6,13 @@ 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. + The oldest version that CI tests. -When you change one of these minimums (in the headers, in CMake, in -``pyproject.toml``, or in the CI matrix), update this table too. +**Minimum expected** + The oldest version that we hope works. Usually the headers or the build + system reject older versions with an error. We fix bugs reported for this + version and later, but CI does not test them. Python ====== @@ -44,21 +40,23 @@ Python * - CPython, free-threaded stable ABI (``abi3t``) - 3.15t - 3.15t - - + - First release of ``abi3t``. * - PyPy - - 3.10 + - 3.10 (some v7 edition) - 3.11 (v7.3.23) - - + - We support v8 too. * - GraalPy - 25.0 - 25.0 - - + - Older versions supported 24.x somewhat. We plan to drop 3.13t support soon, as it was experimental. Use 3.14t or newer. C++ standard and compilers ========================== +We support C++11 through C++23. + .. list-table:: :header-rows: 1 :widths: 30 20 20 30 @@ -67,10 +65,6 @@ C++ standard and compilers - Minimum expected - Minimum tested - Notes - * - C++ standard - - C++11 - - C++11 - - CI tests C++11 through C++23. * - GCC - 4.8 - 8 (AlmaLinux 8) @@ -114,7 +108,7 @@ Build tools and optional dependencies * - CMake - 3.15 - 3.15 - - The newest tested version is 4.2. + - 4.x supported too. * - Eigen - 3.2.7 - 3.3.9 From a653115bb1759b5f8a830cf5b94f31e6fefc2438 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 21 Nov 2026 13:24:19 -0500 Subject: [PATCH 4/4] docs: align GraalPy and PyPy minimums with the README Assisted-by: ClaudeCode:claude-fable-5-2 --- README.rst | 2 +- docs/supported.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 2a00cc984e..467f15bcf1 100644 --- a/README.rst +++ b/README.rst @@ -81,7 +81,7 @@ Goodies In addition to the core functionality, pybind11 provides some extra goodies: -- CPython 3.9+, PyPy3 7.3.17+, and GraalPy 24.1+ are supported with an +- CPython 3.9+, PyPy3 7.3.17+, and GraalPy 25.0+ are supported with an implementation-agnostic interface (see older versions for older CPython and PyPy versions). diff --git a/docs/supported.rst b/docs/supported.rst index d056a38329..83708f56ae 100644 --- a/docs/supported.rst +++ b/docs/supported.rst @@ -42,13 +42,13 @@ Python - 3.15t - First release of ``abi3t``. * - PyPy - - 3.10 (some v7 edition) + - 3.10 (v7.3.17) - 3.11 (v7.3.23) - We support v8 too. * - GraalPy - 25.0 - 25.0 - - Older versions supported 24.x somewhat. + - CI tested 24.x before pybind11 3.1. It can work, but we do not test it. We plan to drop 3.13t support soon, as it was experimental. Use 3.14t or newer.