Version 2.10.1

This is the first version to fully support embedding the newly released Python 3.11.

Changes:

• Allow pybind11::capsule constructor to take null destructor pointers. #4221
• embed.h was changed so that PYTHONPATH is used also with Python 3.11 (established behavior). #4119
• A PYBIND11_SIMPLE_GIL_MANAGEMENT option was added (cmake, C++ define), along with many additional tests in test_gil_scoped.py. The option may be useful to try when debugging GIL-related issues, to determine if the more complex default implementation is or is not to blame. See #4216 for background. WARNING: Please be careful to not create ODR violations when using the option: everything that is linked together with mutual symbol visibility needs to be rebuilt. #4216
• PYBIND11_EXPORT_EXCEPTION was made non-empty only under macOS. This makes Linux builds safer, and enables the removal of warning suppression pragmas for Windows. #4298

Bug fixes:

• Fixed a bug where UnicodeDecodeError was not propagated from various py::str ctors when decoding surrogate utf characters. #4294
• Revert perfect forwarding for make_iterator. This broke at least one valid use case. May revisit later. #4234
• Fix support for safe casts to void* (regression in 2.10.0). #4275
• Fix char8_t support (regression in 2.9). #4278
• Unicode surrogate character in Python exception message leads to process termination in error_already_set::what(). #4297
• Fix MSVC 2019 v.1924 & C++14 mode error for overload_cast. #4188
• Make augmented assignment operators non-const for the object-api. Behavior was previously broken for augmented assignment operators. #4065
• Add proper error checking to C++ bindings for Python list append and insert. #4208
• Work-around for Nvidia's CUDA nvcc compiler in versions 11.4.0 - 11.8.0. #4220
• A workaround for PyPy was added in the py::error_already_set implementation, related to PR #1895 released with v2.10.0. #4079
• Fixed compiler errors when C++23 std::forward_like is available. #4136
• Properly raise exceptions in contains methods (like when an object in unhashable). #4209
• Further improve another error in exception handling. #4232
• get_local_internals() was made compatible with finalize_interpreter(), fixing potential freezes during interpreter finalization. #4192

Performance and style:

• Reserve space in set and STL map casters if possible. This will prevent unnecessary rehashing / resizing by knowing the number of keys ahead of time for Python to C++ casting. This improvement will greatly speed up the casting of large unordered maps and sets. #4194
• GIL RAII scopes are non-copyable to avoid potential bugs. #4183
• Explicitly default all relevant ctors for pytypes in the PYBIND11_OBJECT macros and enforce the clang-tidy checks modernize-use-equals-default in macros as well. #4017
• Optimize iterator advancement in C++ bindings. #4237
• Use the modern PyObject_GenericGetDict and PyObject_GenericSetDict for handling dynamic attribute dictionaries. #4106
• Document that users should use PYBIND11_NAMESPACE instead of using pybind11 when opening namespaces. Using namespace declarations and namespace qualification remain the same as pybind11. This is done to ensure consistent symbol visibility. #4098
• Mark detail::forward_like as constexpr. #4147
• Optimize unpacking_collector when processing arg_v arguments. #4219
• Optimize casting C++ object to None. #4269

Build system improvements:

• CMake: revert overwrite behavior, now opt-in with PYBIND11_PYTHONLIBS_OVERRWRITE OFF. #4195
• Include a pkg-config file when installing pybind11, such as in the Python package. #4077
• Avoid stripping debug symbols when CMAKE_BUILD_TYPE is set to DEBUG instead of Debug. #4078
• Followup to #3948, fixing vcpkg again. #4123

Version 2.10.0

Removed support for Python 2.7, Python 3.5, and MSVC 2015. Support for MSVC 2017 is limited due to availability of CI runners; we highly recommend MSVC 2019 or 2022 be used. Initial support added for Python 3.11.

New features:

• py::anyset & py::frozenset were added, with copying (cast) to std::set (similar to set). #3901
• Support bytearray casting to string. #3707
• type_caster<std::monostate> was added. std::monostate is a tag type that allows std::variant to act as an optional, or allows default construction of a std::variant holding a non-default constructible type. #3818
• pybind11::capsule::set_name added to mutate the name of the capsule instance. #3866
• NumPy: dtype constructor from type number added, accessors corresponding to Python API dtype.num, dtype.byteorder, dtype.flags and dtype.alignment added. #3868

Changes:

• Python 3.6 is now the minimum supported version. #3688 #3719
• The minimum version for MSVC is now 2017. #3722
• Fix issues with CPython 3.11 betas and add to supported test matrix. #3923
• error_already_set is now safer and more performant, especially for exceptions with long tracebacks, by delaying computation. #1895
• Improve exception handling in python str bindings. #3826
• The bindings for capsules now have more consistent exception handling. #3825
• PYBIND11_OBJECT_CVT and PYBIND11_OBJECT_CVT_DEFAULT macro can now be used to define classes in namespaces other than pybind11. #3797
• Error printing code now uses PYBIND11_DETAILED_ERROR_MESSAGES instead of requiring NDEBUG, allowing use with release builds if desired. #3913
• Implicit conversion of the literal 0 to pybind11::handle is now disabled. #4008

Bug fixes:

• Fix exception handling when pybind11::weakref() fails. #3739
• module_::def_submodule was missing proper error handling. This is fixed now. #3973
• The behavior or error_already_set was made safer and the highly opaque "Unknown internal error occurred" message was replaced with a more helpful message. #3982
• error_already_set::what() now handles non-normalized exceptions correctly. #3971
• Support older C++ compilers where filesystem is not yet part of the standard library and is instead included in std::experimental::filesystem. #3840
• Fix -Wfree-nonheap-object warnings produced by GCC by avoiding returning pointers to static objects with return_value_policy::take_ownership. #3946
• Fix cast from pytype rvalue to another pytype. #3949
• Ensure proper behavior when garbage collecting classes with dynamic attributes in Python >=3.9. #4051
• A couple long-standing PYBIND11_NAMESPACE __attribute__((visibility("hidden"))) inconsistencies are now fixed (affects only unusual environments). #4043
• pybind11::detail::get_internals() is now resilient to in-flight Python exceptions. #3981
• Arrays with a dimension of size 0 are now properly converted to dynamic Eigen matrices (more common in NumPy 1.23). #4038
• Avoid catching unrelated errors when importing NumPy. #3974

Performance and style:

• Added an accessor overload of (object &&key) to reference steal the object when using python types as keys. This prevents unnecessary reference count overhead for attr, dictionary, tuple, and sequence look ups. Added additional regression tests. Fixed a performance bug the caused accessor assignments to potentially perform unnecessary copies. #3970
• Perfect forward all args of make_iterator. #3980
• Avoid potential bug in pycapsule destructor by adding an error_guard to one of the dtors. #3958
• Optimize dictionary access in strip_padding for numpy. #3994
• stl_bind.h bindings now take slice args as a const-ref. #3852
• Made slice constructor more consistent, and improve performance of some casters by allowing reference stealing. #3845
• Change numpy dtype from_args method to use const ref. #3878
• Follow rule of three to ensure PyErr_Restore is called only once. #3872
• Added missing perfect forwarding for make_iterator functions. #3860
• Optimize c++ to python function casting by using the rvalue caster. #3966
• Optimize Eigen sparse matrix casting by removing unnecessary temporary. #4064
• Avoid potential implicit copy/assignment constructors causing double free in strdup_gaurd. #3905
• Enable clang-tidy checks misc-definitions-in-headers, modernize-loop-convert, and modernize-use-nullptr. #3881 #3988

Build system improvements:

• CMake: Fix file extension on Windows with cp36 and cp37 using FindPython. #3919
• CMake: Support multiple Python targets (such as on vcpkg). #3948
• CMake: Fix issue with NVCC on Windows. #3947
• CMake: Drop the bitness check on cross compiles (like targeting WebAssembly via Emscripten). #3959
• Add MSVC builds in debug mode to CI. #3784
• MSVC 2022 C++20 coverage was added to GitHub Actions, including Eigen. #3732, #3741

Backend and tidying up:

• New theme for the documentation. #3109
• Remove idioms in code comments. Use more inclusive language. #3809
• #include <iostream> was removed from the pybind11/stl.h header. Your project may break if it has a transitive dependency on this include. The fix is to "Include What You Use". #3928
• Avoid setup.py <command> usage in internal tests. #3734

Version 2.9.2

Changes:

• Enum now has an __index__ method on Python <3.8 too. #3700
• Local internals are now cleared after finalizing the interpreter. #3744

Bug fixes:

• Better support for Python 3.11 alphas. #3694
• PYBIND11_TYPE_CASTER now uses fully qualified symbols, so it can be used outside of pybind11::detail. #3758
• Some fixes for PyPy 3.9. #3768
• Fixed a potential memleak in PyPy in get_type_override. #3774
• Fix usage of VISIBILITY_INLINES_HIDDEN. #3721

Build system improvements:

• Uses sysconfig module to determine installation locations on Python >= 3.10, instead of distutils which has been deprecated. #3764
• Support Catch 2.13.5+ (supporting GLIBC 2.34+). #3679
• Fix test failures with numpy 1.22 by ignoring whitespace when comparing str() of dtypes. #3682

Backend and tidying up:

• clang-tidy: added readability-qualified-auto, readability-braces-around-statements, cppcoreguidelines-prefer-member-initializer, clang-analyzer-optin.performance.Padding, cppcoreguidelines-pro-type-static-cast-downcast, and readability-inconsistent-declaration-parameter-name. #3702, #3699, #3716, #3709
• clang-format was added to the pre-commit actions, and the entire code base automatically reformatted (after several iterations preparing for this leap). #3713

Version 2.9.1

Changes:

• If possible, attach Python exception with py::raise_from to TypeError when casting from C++ to Python. This will give additional info if Python exceptions occur in the caster. Adds a test case of trying to convert a set from C++ to Python when the hash function is not defined in Python. #3605
• Add a mapping of C++11 nested exceptions to their Python exception equivalent using py::raise_from. This attaches the nested exceptions in Python using the __cause__ field. #3608
• Propagate Python exception traceback using raise_from if a pybind11 function runs out of overloads. #3671
• py::multiple_inheritance is now only needed when C++ bases are hidden from pybind11. #3650 and #3659

Bug fixes:

• Remove a boolean cast in numpy.h that causes MSVC C4800 warnings when compiling against Python 3.10 or newer. #3669
• Render py::bool_ and py::float_ as bool and float respectively. #3622

Build system improvements:

• Fix CMake extension suffix computation on Python 3.10+. #3663
• Allow CMAKE_ARGS to override CMake args in pybind11's own setup.py. #3577
• Remove a few deprecated c-headers. #3610
• More uniform handling of test targets. #3590
• Add clang-tidy readability check to catch potentially swapped function args. #3611

Version 2.9.0

This is the last version to support Python 2.7 and 3.5.

New Features:

• Allow py::args to be followed by other arguments; the remaining arguments are implicitly keyword-only, as if a py::kw_only{} annotation had been used. #3402

Changes:

• Make str/bytes/memoryview more interoperable with std::string_view. #3521
• Replace _ with const_name in internals, avoid defining pybind::_ if _ defined as macro (common gettext usage) #3423

Bug fixes:

• Fix a rare warning about extra copy in an Eigen constructor. #3486
• Fix caching of the C++ overrides. #3465
• Add missing std::forward calls to some cpp_function overloads. #3443
• Support PyPy 7.3.7 and the PyPy3.8 beta. Test python-3.11 on PRs with the python dev label. #3419
• Replace usage of deprecated Eigen::MappedSparseMatrix with Eigen::Map<Eigen::SparseMatrix<...>> for Eigen 3.3+. #3499
• Tweaks to support Microsoft Visual Studio 2022. #3497

Build system improvements:

• Nicer CMake printout and IDE organisation for pybind11's own tests. #3479
• CMake: report version type as part of the version string to avoid a spurious space in the package status message. #3472
• Flags starting with -g in $CFLAGS and $CPPFLAGS are no longer overridden by .Pybind11Extension. #3436
• Ensure ThreadPool is closed in setup_helpers. #3548
• Avoid LTS on mips64 and ppc64le (reported broken). #3557

Version 2.8.1

v2.8.1 (Oct 27, 2021)

Changes and additions:

• The simple namespace creation shortcut added in 2.8.0 was deprecated due to usage of CPython internal API, and will be removed soon. Use py::module_::import("types").attr("SimpleNamespace"). #3374
• Add C++ Exception type to throw and catch AttributeError. Useful for defining custom __setattr__ and __getattr__ methods. #3387

Fixes:

• Fixed the potential for dangling references when using properties with std::optional types. #3376
• Modernize usage of PyCodeObject on Python 3.9+ (moving toward support for Python 3.11a1) #3368
• A long-standing bug in eigen.h was fixed (originally PR #3343). The bug was unmasked by newly added static_assert's in the Eigen 3.4.0 release. #3352
• Support multiple raw inclusion of CMake helper files (Conan.io does this for multi-config generators). #3420
• Fix harmless warning on upcoming CMake 3.22. #3368
• Fix 2.8.0 regression with MSVC 2017 + C++17 mode + Python 3. #3407
• Fix 2.8.0 regression that caused undefined behavior (typically segfaults) in make_key_iterator/make_value_iterator if dereferencing the iterator returned a temporary value instead of a reference. #3348

Version 2.8.0

New features:

• Added py::raise_from to enable chaining exceptions. #3215
• Allow exception translators to be optionally registered local to a module instead of applying globally across all pybind11 modules. Use register_local_exception_translator(ExceptionTranslator&& translator) instead of register_exception_translator(ExceptionTranslator&& translator) to keep your exception remapping code local to the module. #2650
• Add make_simple_namespace function for instantiating Python SimpleNamespace objects. #2840
• pybind11::scoped_interpreter and initialize_interpreter have new arguments to allow sys.argv initialization. #2341
• Allow Python builtins to be used as callbacks in CPython. #1413
• Added view to view arrays with a different datatype. #987
• Implemented reshape on arrays. #984
• Enable defining custom __new__ methods on classes by fixing bug preventing overriding methods if they have non-pybind11 siblings. #3265
• Add make_value_iterator(), and fix make_key_iterator() to return references instead of copies. #3293
• Improve the classes generated by bind_map: #3310
  • Change .items from an iterator to a dictionary view.
  • Add .keys and .values (both dictionary views).
  • Allow __contains__ to take any object.
• pybind11::custom_type_setup was added, for customizing the PyHeapTypeObject corresponding to a class, which may be useful for enabling garbage collection support, among other things. #3287

Changes:

• Set __file__ constant when running eval_file in an embedded interpreter. #3233
• Python objects and (C++17) std::optional now accepted in py::slice constructor. #1101
• The pybind11 proxy types str, bytes, bytearray, tuple, list now consistently support passing ssize_t values for sizes and indexes. Previously, only size_t was accepted in several interfaces. #3219
• Avoid evaluating PYBIND11_TLS_REPLACE_VALUE arguments more than once. #3290

Fixes:

• Bug fix: enum value's __int__ returning non-int when underlying type is bool or of char type #1334
• Fixes bug in setting error state in Capsule's pointer methods. #3261
• A long-standing memory leak in py::cpp_function::initialize was fixed. #3229
• Fixes thread safety for some pybind11::type_caster which require lifetime extension, such as for std::string_view. #3237
• Restore compatibility with gcc 4.8.4 as distributed by ubuntu-trusty, linuxmint-17. #3270

Build system improvements:

• Fix regression in CMake Python package config: improper use of absolute path. #3144
• Cached Python version information could become stale when CMake was re-run with a different Python version. The build system now detects this and updates this information. #3299
• Specified UTF8-encoding in setup.py calls of open(). #3137
• Fix a harmless warning from CMake 3.21 with the classic Python discovery. #3220
• Eigen repo and version can now be specified as cmake options. #3324

Backend and tidying up:

• Reduced thread-local storage required for keeping alive temporary data for type conversion to one key per ABI version, rather than one key per extension module. This makes the total thread-local storage required by pybind11 2 keys per ABI version. #3275
• Optimize NumPy array construction with additional moves. #3183
• Conversion to std::string and std::string_view now avoids making an extra copy of the data on Python >= 3.3. #3257
• Remove const modifier from certain C++ methods on Python collections (list, set, dict) such as (clear(), append(), insert(), etc...) and annotated them with py-non-const.
• Enable readability clang-tidy-const-return and remove useless consts. #3254 #3194
• The clang-tidy google-explicit-constructor option was enabled. #3250
• Mark a pytype move constructor as noexcept (perf). #3236
• Enable clang-tidy check to guard against inheritance slicing. #3210
• Legacy warning suppression pragma were removed from eigen.h. On Unix platforms, please use -isystem for Eigen include directories, to suppress compiler warnings originating from Eigen headers. Note that CMake does this by default. No adjustments are needed for Windows. #3198
• Format pybind11 with isort consistent ordering of imports #3195
• The warnings-suppression "pragma clamp" at the top/bottom of pybind11 was removed, clearing the path to refactoring and IWYU cleanup. #3186
• Enable most bugprone checks in clang-tidy and fix the found potential bugs and poor coding styles. #3166
• Add clang-tidy-readability rules to make boolean casts explicit improving code readability. Also enabled other misc and readability clang-tidy checks. #3148
• Move object in .pop() for list. #3116

Version 2.7.1

Minor missing functionality added:

• Allow Python builtins to be used as callbacks in CPython. #1413

Bug fixes:

• Fix regression in CMake Python package config: improper use of absolute path. #3144
• Fix Mingw64 and add to the CI testing matrix. #3132
• Specified UTF8-encoding in setup.py calls of open(). #3137
• Add clang-tidy-readability rules to make boolean casts explicit improving code readability. Also enabled other misc and readability clang-tidy checks. #3148
• Move object in .pop() for list. #3116

Backend and tidying up:

• Removed and fixed warning suppressions. #3127 #3129 #3135 #3141 #3142 #3150 #3152 #3160 #3161

Version 2.7.0

New features:

• Enable py::implicitly_convertible<py::none, ...> for py::class_-wrapped types. #3059
• Allow function pointer extraction from overloaded functions. #2944
• NumPy: added .char_() to type which gives the NumPy public char result, which also distinguishes types by bit length (unlike .kind()). #2864
• Add pybind11::bytearray to manipulate bytearray similar to bytes. #2799
• pybind11/stl/filesystem.h registers a type caster that, on C++17/Python 3.6+, converts std::filesystem::path to pathlib.Path and any os.PathLike to std::filesystem::path. #2730
• A PYBIND11_VERSION_HEX define was added, similar to PY_VERSION_HEX. #3120

Changes:

• py::str changed to exclusively hold PyUnicodeObject. Previously py::str could
  also hold bytes, which is probably surprising, was never documented, and can mask bugs (e.g. accidental use of py::str instead of py::bytes). #2409
• Add a safety guard to ensure that the Python GIL is held when C++ calls back into Python via object_api<>::operator() (e.g. py::function __call__). (This feature is available for Python 3.6+ only.) #2919
• Catch a missing self argument in calls to __init__(). #2914
• Use std::string_view if available to avoid a copy when passing an object to a std::ostream. #3042
• An important warning about thread safety was added to the iostream.h documentation; attempts to make py::scoped_ostream_redirect thread safe have been removed, as it was only partially effective. #2995

Fixes:

• Performance: avoid unnecessary strlen calls. #3058
• Fix auto-generated documentation string when using const T in pyarray_t. #3020
• Unify error messages thrown by simple_collector/unpacking_collector. #3013
• pybind11::builtin_exception is now explicitly exported, which means the types included/defined in different modules are identical, and exceptions raised in different modules can be caught correctly. The documentation was updated to explain that custom exceptions that are used across module boundaries need to be explicitly exported as well. #2999
• Fixed exception when printing UTF-8 to a scoped_ostream_redirect. #2982
• Pickle support enhancement: setstate implementation will attempt to setattr __dict__ only if the unpickled dict object is not empty, to not force use of py::dynamic_attr() unnecessarily. #2972
• Allow negative timedelta values to roundtrip. #2870
• Fix unchecked errors could potentially swallow signals/other exceptions. #2863
• Add null pointer check with std::localtime. #2846
• Fix the weakref constructor from py::object to create a new weakref on conversion. #2832
• Avoid relying on exceptions in C++17 when getting a shared_ptr holder from a shared_from_this class. #2819
• Allow the codec's exception to be raised instead of RuntimeError when casting from py::str to std::string. #2903

Build system improvements:

• In setup_helpers.py, test for platforms that have some multiprocessing features but lack semaphores, which ParallelCompile requires. #3043
• Fix pybind11_INCLUDE_DIR in case CMAKE_INSTALL_INCLUDEDIR is absolute. #3005
• Fix bug not respecting WITH_SOABI or WITHOUT_SOABI to CMake. #2938
• Fix the default Pybind11Extension compilation flags with a Mingw64 python. #2921
• Clang on Windows: do not pass /MP (ignored flag). #2824
• pybind11.setup_helpers.intree_extensions can be used to generate Pybind11Extension instances from cpp files placed in the Python
  package source tree. #2831

Backend and tidying up:

• Enable clang-tidy performance, readability, and modernization checks throughout the codebase to enforce best coding practices. #3046, #3049, #3051, #3052, #3080, and #3094
• Checks for common misspellings were added to the pre-commit hooks. #3076
• Changed Werror to stricter Werror-all for Intel compiler and fixed minor issues. #2948
• Fixed compilation with GCC < 5 when the user defines _GLIBCXX_USE_CXX11_ABI. #2956
• Added nox support for easier local testing and linting of contributions. #3101 and #3121
• Avoid RTD style issue with docutils 0.17+. #3119
• Support pipx run, such as pipx run pybind11 --include for a quick compile. #3117

Version 2.6.2

Minor missing functionality added:

• enum: add missing Enum.value property. #2739
• Allow thread termination to be avoided during shutdown for CPython 3.7+ via .disarm for gil_scoped_acquire/gil_scoped_release. #2657

Fixed or improved behavior in a few special cases:

• Fix bug where the constructor of object subclasses would not throw on being passed a Python object of the wrong type. #2701
• The type_caster for integers does not convert Python objects with __int__ anymore with noconvert or during the first round of trying overloads. #2698
• When casting to a C++ integer, __index__ is always called and not considered as conversion, consistent with Python 3.8+. #2801

Build improvements:

• Setup helpers: extra_compile_args and extra_link_args automatically set by Pybind11Extension are now prepended, which allows them to be overridden by user-set extra_compile_args and extra_link_args. #2808
• Setup helpers: Don't trigger unused parameter warning. #2735
• CMake: Support running with --warn-uninitialized active. #2806
• CMake: Avoid error if included from two submodule directories. #2804
• CMake: Fix STATIC / SHARED being ignored in FindPython mode. #2796
• CMake: Respect the setting for CMAKE_CXX_VISIBILITY_PRESET if defined. #2793
• CMake: Fix issue with FindPython2/FindPython3 not working with pybind11::embed. #2662
• CMake: mixing local and installed pybind11's would prioritize the installed one over the local one (regression in 2.6.0). #2716

Bug fixes:

• Fixed segfault in multithreaded environments when using scoped_ostream_redirect. #2675
• Leave docstring unset when all docstring-related options are disabled, rather than set an empty string. #2745
• The module key in builtins that pybind11 uses to store its internals changed from std::string to a python str type (more natural on Python 2, no change on Python 3). #2814
• Fixed assertion error related to unhandled (later overwritten) exception in CPython 3.8 and 3.9 debug builds. #2685
• Fix py::gil_scoped_acquire assert with CPython 3.9 debug build. #2683
• Fix issue with a test failing on PyTest 6.2. #2741

Warning fixes:

• Fix warning modifying constructor parameter 'flag' that shadows a field of 'set_flag' [-Wshadow-field-in-constructor-modified]. #2780
• Suppressed some deprecation warnings about old-style __init__/__setstate__ in the tests. #2759

Valgrind work:

• Fix invalid access when calling a pybind11 __init__ on a non-pybind11 class instance. #2755
• Fixed various minor memory leaks in pybind11's test suite. #2758
• Resolved memory leak in cpp_function initialization when exceptions occurred. #2756
• Added a Valgrind build, checking for leaks and memory-related UB, to CI. #2746

Compiler support:

• Intel compiler was not activating C++14 support due to a broken define. #2679
• Support ICC and NVIDIA HPC SDK in C++17 mode. #2729
• Support Intel OneAPI compiler (ICC 20.2) and add to CI. #2573