Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down
6 changes: 4 additions & 2 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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 <https://pybind11.readthedocs.io/en/latest/supported.html>`_
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 <https://github.com/pybind/pybind11/actions?query=branch%3Amaster>`_
and `AppVeyor <https://ci.appveyor.com/project/wjakob/pybind11>`_ logs.
Expand Down
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,5 +46,6 @@
faq
benchmark
limitations
supported
reference
cmake/index
33 changes: 5 additions & 28 deletions docs/limitations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,21 +24,6 @@ pybind11; see `pybind11_json <https://github.com/pybind/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 <https://github.com/pybind/pybind11/pull/2573>`_

- Debug mode Python does not support 1-5 tests in the test suite currently.
`#2422 <https://github.com/pybind/pybind11/pull/2422>`_

- PyPy3 7.3.1 and 7.3.2 have issues with several tests on 32-bit Windows.

Known limitations
^^^^^^^^^^^^^^^^^

Expand All @@ -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 <https://github.com/python/cpython/pull/22670>`_.
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 <https://github.com/python/cpython/pull/22670>`_. 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.
123 changes: 123 additions & 0 deletions docs/supported.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
.. _supported:

Supported versions
##################

This page lists the oldest version of each tool or dependency that pybind11
supports. Each entry has two values:

**Minimum tested**
The oldest version that CI tests.

**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
======

.. 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
- First release of ``abi3t``.
* - PyPy
- 3.10 (v7.3.17)
- 3.11 (v7.3.23)
- We support v8 too.
* - GraalPy
- 25.0
- 25.0
- 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.

C++ standard and compilers
==========================

We support C++11 through C++23.

.. list-table::
:header-rows: 1
:widths: 30 20 20 30

* - Compiler
- Minimum expected
- Minimum tested
- Notes
* - 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
- 4.x supported too.
* - 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.
Loading