Version 3.0.0 (final)

Pybind11 3.0 includes an ABI bump, the first required bump in many years on Unix (Windows has had required bumps more often). This release contains the smart-holder branch, multi-phase init and subinterpreter support, py::native_enum, an interface to warnings, typing improvements, and more. CMake now defaults to FindPython mode. Please check our upgrade guide for more info on upgrading!

Support for Python 3.14, 3.14t, GraalPy, and PyPy 3.11 has been added, while legacy support for Python 3.7, PyPy 3.8/3.9, and CMake <3.15 has been removed. Most deprecated features have been kept for this release, but anything producing a warning in 3.0 may be removed in a future 3.x version. We also now have a deprecation page.

New Features:

• The smart_holder branch has been merged, enabling py::class_<T, py::smart_holder>, which handles two-way conversion with std::unique_ptr<T> and std::shared_ptr<T> (simultaneously), disowning a Python object being passed to std::unique_ptr<T>, trampoline objects, and std::enable_shared_from_this. #5542

  • Added support for std::shared_ptr<const T> in py::init() when using py::smart_holder, complementing existing support for std::unique_ptr<const T>. #5731

  • Support const-only smart pointers. #5718

  • Eliminate cross-DSO RTTI reliance from trampoline_self_life_support functionality, smart_holder deleter detection, and other smart_holder bookkeeping. Resolves platform-specific issues on macOS related to cross-DSO dynamic_cast and typeid mismatches. #5728 (replaces #5700)

• Changed PYBIND11_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes. #5574 and avoid destruction #5688

• Support for sub-interpreters (both isolated (with separate GILs) and legacy (with a global GIL). Add the py::multiple_interpreters::per_interpreter_gil() tag (or, py::multiple_interpreters::shared_gil() for legacy interpreter support) to PYBIND11_MODULE calls (as the third parameter) to indicate that a module supports running with sub-interpreters. #5564

  • Rename macro PYBIND11_SUBINTERPRETER_SUPPORT -> PYBIND11_HAS_SUBINTERPRETER_SUPPORT to meet naming convention. #5682

  • Allow subinterpreter support to be disabled if defined to 0. This is mostly an emergency workaround, and is not exposed in CMake. #5708 and #5710

  • Modify internals pointer-to-pointer implementation to not use thread_local (better iOS support). #5709

  • Support implementations without subinterpreter support. #5732

• Changed PYBIND11_EMBEDDED_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes and to support py::mod_gil_not_used(), py::multiple_interpreters::per_interpreter_gil() and py::multiple_interpreters::shared_gil(). #5665 and consolidate code #5670

• Added API in pybind11/subinterpreter.h for embedding sub-intepreters (requires Python 3.12+). #5666

• py::native_enum was added, for conversions between Python's native (stdlib) enum types and C++ enums. #5555

  • Add class doc string to py::native_enum. #5617

  • Fix signature for functions with a native_enum in the signature. #5619

• Support py::numpy_scalar<> / py::make_scalar() for NumPy types. #5726

• A py::release_gil_before_calling_cpp_dtor option (for py::class_) was added to resolve the long-standing issue #1446. #5522

• Add dtype::normalized_num and dtype::num_of. #5429

• Add support for array_t<handle> and array_t<object>. #5427

• Added py::warnings namespace with py::warnings::warn and py::warnings::new_warning_type that provides the interface for Python warnings. #5291

• stl.h list|set|map_caster were made more user friendly: it is no longer necessary to explicitly convert Python iterables to tuple(), set(), or map() in many common situations. #4686

• The array_caster in pybind11/stl.h was enhanced to support value types that are not default-constructible. #5305

• pybind11/conduit/pybind11_platform_abi_id.h was factored out, to maximize reusability of PYBIND11_PLATFORM_ABI_ID (for other Python/C++ binding systems). Separately, a note was added to explain that the conduit feature only covers from-Python-to-C++ conversions. #5375 | #5740

• Added support for finding pybind11 using pkgconf distributed on pypi. #5552

• Support --extension-suffix on the pybind11 command. #5360

• Add semi-public API: pybind11::detail::is_holder_constructed and update example for pybind11::custom_type_setup in documentation. #5669

• Added py::scoped_critical_section to support free-threaded mode. #5684 | #5706

New Features / fixes (typing):

• Added option for different arg/return type hints to type_caster. Updated stl/filesystem to use correct arg/return type hints. Updated pybind11::typing to use correct arg/return type hints for nested types. #5450

• Updated type hint for py::capsule to type.CapsuleType. #5567

• Adds support for typing.SupportsInt and typing.SupportsFloat. Update Final to be narrower type hint. Make std::function match Callable type. Fix io_name bug in attr_with_type_hint. #5540

• Rework of arg/return type hints to support .noconvert(). #5486

• Add attr_with_type for declaring attribute types and Final, ClassVar type annotations. #5460

• Allow annotate methods with py::pos_only when only have the self argument. Make arguments for auto-generated dunder methods positional-only. #5403

• Added py::Args and py::KWArgs to enable custom type hinting of *args and **kwargs (see PEP 484). #5357

• Switched to numpy.typing.NDArray and numpy.typing.ArrayLike. #5212

• Use numpy.object_ instead of object. #5571

• Fix module type hint. #5469

• Fix Buffer type hint. #5662

• Added support for collections.abc in type hints and convertible checks of STL casters and py::buffer. #5566

• Fix typing and collections.abc type hint ambiguity. #5663

• Add typing_extensions alternatives for all types that need them. #5693

Removals:

• Remove support for pybind11 v2 internals versions (4, 5, 6). (The internals version number has been bumped for pybind11 v3.) #5512 | #5530

• Remove make_simple_namespace (added in 2.8.0, deprecated in 2.8.1). #5597

• Legacy-mode option PYBIND11_NUMPY_1_ONLY has been removed. #5595

• Add a deprecation warning to .get_type (deprecated in pybind11 2.6 in 2020). #5596

Bug fixes:

• Set __file__ on submodules. #5584. Except on embedded modules. #5650

• pybind11-bound functions are now pickleable. #5580

• Fix bug in attr_with_type_hint to allow objects to be in attr_with_type_hint. #5576

• A -Wmaybe-uninitialized warning suppression was added in pybind11/eigen/matrix.h. #5516

• PYBIND11_WARNING_POP was incorrectly defined as PYBIND11_PRAGMA(clang diagnostic push). #5448

• PYBIND11_PLATFORM_ABI_ID (which is used in composing PYBIND11_INTERNALS_ID) was modernized to reflect actual ABI compatibility more accurately. #4953 | [#5439](https://github.com...

Version 3.0.0 RC 4

What's Changed

• feat: numpy scalars by @henryiii in #5726
• fix: TSan warning in sub-interpreter test by @b-pass in #5729
• fix: add support for shared_ptr<const T> in py::init() with smart_holder by @rwgk in #5731
• fix: add support for const-only smart pointers by @Rosdf in #5718
• fix: android CMake support by @henryiii in #5733
• fix: eliminate cross-DSO RTTI reliance in smart_holder functionality (for platforms like macOS). by @rwgk in #5728
• fix: handle implementations without subinterpreter support by @msimacek in #5732
• ci: avoid 3.13.4 on Windows by @henryiii in #5725
• ci: check latest on 3.13 by @henryiii in #5734
• ci: cibw update to 3.0.0rc2 by @henryiii in #5717
• docs: Add documentation entry for warnings by @jiwaszki in #5356
• tests: better test for const only smart ptr by @Rosdf in #5727
• tests: run pytest under Python devmode by @XuehaiPan in #5715
• chore(deps): bump pypa/cibuildwheel from 3.0.0rc2 to 3.0 in the actions group by @dependabot in #5721
• chore(deps): bump requests from 2.32.3 to 2.32.4 in /docs by @dependabot in #5720
• chore(deps): bump urllib3 from 2.2.2 to 2.5.0 in /docs by @dependabot in #5735
• chore: prepare for 3.0.0rc4 by @henryiii in #5736

Important

This RC has an ABI bump. This is expected to be the last bump (and last RC) unless something comes up.

New Contributors

• @Rosdf made their first contribution in #5718

Full Changelog: v3.0.0rc3...v3.0.0rc4

Version 3.0.0 RC 3

This is another release candidate. See the changelog in the docs for the combined changelog; this is just the changes since RC 2:

• fix(types): type hints from future python versions by @InvincibleRMC in #5693
• fix: allow subinterpreters to be manually disabled by @henryiii in #5708
• fix: follow rest of pybind11 closer with PYBIND11_HAS_SUBINTERPRETER_SUPPORT by @henryiii in #5710
• fix: modify the internals pointer-to-pointer implementation to not use thread_local by @b-pass in #5709
• fix: expose required symbol using clang by @petersteneteg in #5700
• fix: handle null py::handle and add tests for py::scoped_critical_section by @XuehaiPan in #5706
• ci: avoid brownout (and removal) of windows-2019 by @henryiii in #5712
• ci: ios by @henryiii in #5705
• ci: reduced runs on draft PRs by @henryiii in #5707
• docs: prepare for RC 3 by @henryiii in #5713

Warning

Note our iOS support requires a cibuildwheel 3.0 beta currently, the cibuildwheel v3.0.0rc1 does not work.

Important

This RC has an ABI bump. We might need one more ABI bump before 3.0 final to improve the protection of our internals.

New Contributors

• @petersteneteg made their first contribution in #5700

Full Changelog: v3.0.0rc2...v3.0.0rc3

Version 3.0.0 RC 2

This is another release candidate. See the changelog in the docs for the combined changelog; this is just the changes since RC 1:

• feat: scoped_critical_section by @henryiii in #5684
• fix(cmake): regression in include guard by @henryiii in #5691
• fix: don't destruct module objects in atexit by @b-pass in #5688
• fix: prepare for 3.14 beta 2 by @henryiii in #5697
• chore(cmake): add compile commands to preset by @henryiii in #5685
• chore: bump maximum clang tested to 20 by @henryiii in #5692
• chore: rename macro PYBIND11_SUBINTERPRETER_SUPPORT -> PYBIND11_HAS_SUBINTERPRETER_SUPPORT to meet naming convention by @XuehaiPan in #5682
• chore: use CPython macros to construct PYBIND11_VERSION_HEX by @XuehaiPan in #5683
• docs: more warnings about locking and the GIL by @henryiii in #5689
• docs: update contributing/release guide a little by @henryiii in #5681
• tests: always disable on the nogil build by @henryiii in #5701
• tests: expect free-threaded import warnings by @henryiii in #5680
• tests: skip some flaky gil tests on nogil by @henryiii in #5699

Full Changelog: v3.0.0rc1...v3.0.0rc2

Version 3.0.0 RC 1

What's Changed

Since this is a large release, we are providing a release candidate to give projects time to test! We also now provide SPEC 4 nightly wheels. We are hoping to split up std.h; that work is approved to be added during the RC phase if it's ready in time. We expect the RC phase to last around a week.

Pybind11 3.0 includes an ABI bump, the first required bump in many years on Unix (Windows has had required bumps more often). This release contains the smart-holder branch, multi-phase init and subinterpreter support, py::native_enum, an interface to warnings, typing improvements, and more. CMake now defaults to FindPython mode. Please check our upgrade guide for more info on upgrading!

Support for Python 3.14, 3.14t, GraalPy, and PyPy 3.11 has been added, while legacy support for Python 3.7, PyPy 3.8/3.9, and CMake <3.15 has been removed. Most deprecated features have been kept for this release, but anything producing a warning in 3.0 may be removed in a future 3.x version. We also now have a deprecation page.

New Features:

• The smart_holder branch has been merged, enabling py::class_<T, py::smart_holder>, which handles two-way conversion
  with std::unique_ptr<T> and std::shared_ptr<T> (simultaneously), disowning a Python object being passed to std::unique_ptr<T>, trampoline objects, and std::enable_shared_from_this. #5542
• Changed PYBIND11_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes. #5574
• Support for sub-interpreters (both isolated (with separate GILs) and legacy (with a global GIL). Add the
  py::multiple_interpreters::per_interpreter_gil() tag (or, py::multiple_interpreters::shared_gil() for legacy interpreter
  support) to PYBIND11_MODULE calls (as the third parameter) to indicate that a module supports running with sub-interpreters. #5564
• Changed PYBIND11_EMBEDDED_MODULE macro implementation to perform multi-phase module initialization (PEP 489) behind the scenes and to support py::mod_gil_not_used(), py::multiple_interpreters::per_interpreter_gil() and py::multiple_interpreters::shared_gil(). #5665 and consolidate code #5670
• Added API in pybind11/subinterpreter.h for embedding sub-intepreters (requires Python 3.12+). #5666
• py::native_enum was added, for conversions between Python's native (stdlib) enum types and C++ enums. #5555
  • Add class doc string to py::native_enum. #5617.
  • Fix signature for functions with a native_enum in the signature. #5619
• A py::release_gil_before_calling_cpp_dtor option (for py::class_) was added to resolve the long-standing issue #1446. #5522
• Add dtype::normalized_num and dtype::num_of. #5429
• Add support for array_t<handle> and array_t<object>. #5427
• Added py::warnings namespace with py::warnings::warn and py::warnings::new_warning_type that provides the interface for
  Python warnings. #5291
• stl.h list|set|map_caster were made more user friendly: it is no longer necessary to explicitly convert Python iterables to tuple(),
  set(), or map() in many common situations. #4686
• The array_caster in pybind11/stl.h was enhanced to support value types that are not default-constructible. #5305
• pybind11/conduit/pybind11_platform_abi_id.h was factored out, to maximize reusability of PYBIND11_PLATFORM_ABI_ID (for other Python/C++ binding systems). #5375
• Added support for finding pybind11 using pkgconf distributed on pypi. #5552
• Support --extension-suffix on the pybind11 command. #5360
• Add semi-public API: pybind11::detail::is_holder_constructed and update example for pybind11::custom_type_setup in documentation. #5669

New Features / fixes (typing):

• Added option for different arg/return type hints to type_caster. Updated stl/filesystem to use correct arg/return type hints. Updated pybind11::typing to use correct arg/return type hints for nested types. #5450
• Updated type hint for py::capsule to type.CapsuleType. #5567
• Adds support for typing.SupportsInt and typing.SupportsFloat. Update Final to be narrower type hint. Make std::function match Callable type. Fix io_name bug in attr_with_type_hint. #5540
• Rework of arg/return type hints to support .noconvert(). #5486
• Add attr_with_type for declaring attribute types and Final, ClassVar type annotations. #5460
• Allow annotate methods with py::pos_only when only have the self argument. Make arguments for auto-generated dunder methods positional-only. #5403
• Added py::Args and py::KWArgs to enable custom type hinting of *args and **kwargs (see PEP 484). #5357
• Switched to numpy.typing.NDArray and numpy.typing.ArrayLike. #5212
• Use numpy.object_ instead of object. #5571
• Fix module type hint. #5469
• Fix Buffer type hint. #5662
• Added support for collections.abc in type hints and convertible checks of STL casters and py::buffer.
  #5566
• Fix typing and collections.abc type hint ambiguity. #5663

Removals:

• Remove support for pybind11 v2 internals versions (4, 5, 6). (The internals version number has been bumped for pybind11 v3.) #5512 | #5530
• Remove make_simple_namespace (added in 2.8.0, deprecated in 2.8.1). #5597
• Legacy-mode option PYBIND11_NUMPY_1_ONLY has been removed. #5595
• Add a deprecation warning to .get_type (deprecated in pybind11 2.6 in 2020). #5596

Bug fixes:

• Set __file__ on submodules. #5584. Except on
  embedded modules. #5650
• pybind11-bound functions are now pickleable. #5580
• Fix bug in attr_with_type_hint to allow objects to be in attr_with_type_hint. #5576
• A -Wmaybe-uninitialized warning suppression was added in pybind11/eigen/matrix.h. #5516
• PYBIND11_WARNING_POP was incorrectly defined as PYBIND11_PRAGMA(clang diagnostic push). #5448
• PYBIND11_PLATFORM_ABI_ID (which is used in composing PYBIND11_INTERNALS_ID) was modernized to reflect actual ABI
  compatibility more accurately. #4953 | #5439
• Fix buffer protocol implementation. #5407
• Fix iterator increment operator does not skip first item. #5400
• When getting or deleting an element in a container bound by bind_map, print the key in KeyError if it does not exist. #5397
• pybind11::builtin_exception is now explicitly exported when linked to libc++. #5390
• Allow subclasses of py::args and py::kwargs. #5381
• Disable false-positive GCC 12 Bound Check warning. #5355
• fix: using __cpp_nontype_template_args instead of __cpp_nontype_template_parameter_class. #5330
• Properly translate C++ exception to Python exception when creating Python buffer from wrapped object. #5324
• Update the dict when restoring pickles, instead of assigning a replacement dict. #5658
• Properly define _DEBUG macro to 1 instead of defining it without value. #5639
• Fix a missing time cast causing a compile error for newer ICC. #5621
• Change the behavior of the default constructor of py::slice to be equivalent to :: in Python. #5620

Bug fixes (CMake):

• Enable FindPython mode by default, with a COMPAT mode that sets some of the old variabl...

Version 2.13.6

New Features:

• A new self._pybind11_conduit_v1_() method is automatically added to all py::class_-wrapped types, to enable type-safe interoperability between different independent Python/C++ bindings systems, including pybind11 versions with different PYBIND11_INTERNALS_VERSION's. Supported on pybind11 2.11.2, 2.12.1, and 2.13.6+. #5296

Bug fixes:

• Using __cpp_nontype_template_args instead of __cpp_nontype_template_parameter_class. #5330
• Properly translate C++ exception to Python exception when creating Python buffer from wrapped object. #5324

Documentation:

• Adds an answer (FAQ) for "What is a highly conclusive and simple way to find memory leaks?". #5340

Version 2.12.1

New Features:

• A new self._pybind11_conduit_v1_() method is automatically added to all py::class_-wrapped types, to enable type-safe interoperability between different independent Python/C++ bindings systems, including pybind11 versions with different PYBIND11_INTERNALS_VERSION's. Supported on pybind11 2.11.2, 2.12.1, and 2.13.6+. #5296

Version 2.11.2

New Features:

• A new self._pybind11_conduit_v1_() method is automatically added to all py::class_-wrapped types, to enable type-safe interoperability between different independent Python/C++ bindings systems, including pybind11 versions with different PYBIND11_INTERNALS_VERSION's. Supported on pybind11 2.11.2, 2.12.1, and 2.13.6+. #5296

Version 2.13.5

Bug fixes:

• Fix includes when using Windows long paths (\\?\ prefix). #5321
• Support -Wpedantic in C++20 mode. #5322
• Fix and test <ranges> support for py::tuple and py::list. #5314

Version 2.13.4

Bug fixes:

• Fix paths with spaces, including on Windows. (Replaces regression from #5302) #4874

Documentation:

• Remove repetitive words. #5308

Full Changelog: v2.13.3...v2.13.4