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

Version 2.6.1

• py::exec, py::eval, and py::eval_file now add the builtins module as "__builtins__" to their globals argument, better matching exec and eval in pure Python. #2616
• setup_helpers will no longer set a minimum macOS version higher than the current version. #2622
• Allow deleting static properties. #2629
• Seal a leak in def_buffer, cleaning up the capture object after the class_ object goes out of scope.
  #2634
• pybind11_INCLUDE_DIRS was incorrect, potentially causing a regression if it was expected to include PYTHON_INCLUDE_DIRS (please use targets instead). #2636
• Added parameter names to the py::enum_ constructor and methods, avoiding arg0 in the generated docstrings. #2637
• Added needs_recompile optional function to the ParallelCompiler helper, to allow a recompile to be skipped based on a user-defined function. #2643

Version 2.6.0

New features:

• Keyword-only arguments supported in Python 2 or 3 with py::kw_only(). #2100
• Positional-only arguments supported in Python 2 or 3 with py::pos_only(). #2459
• py::is_final() class modifier to block subclassing (CPython only). #2151
• Added py::prepend(), allowing a function to be placed at the beginning of the overload chain. #1131
• Access to the type object now provided with py::type::of<T>() and py::type::of(h). #2364
• Perfect forwarding support for methods. #2048
• Added py::error_already_set::discard_as_unraisable(). #2372
• py::hash is now public. #2217
• py::class_<union_type> is now supported. Note that writing to one data member of the union and reading another (type punning) is UB in C++. Thus pybind11-bound enums should never be used for such conversions. #2320.
• Classes now check local scope when registering members, allowing a subclass to have a member with the same name as a parent (such as an enum). #2335

Code correctness features:

• Error now thrown when __init__ is forgotten on subclasses. #2152
• Throw error if conversion to a pybind11 type if the Python object isn't a valid instance of that type, such as py::bytes(o) when py::object o isn't a bytes instance. #2349
• Throw if conversion to str fails. #2477

API changes:

• py::module was renamed py::module_ to avoid issues with C++20 when used unqualified, but an alias py::module is provided for backward compatibility. #2489
• Public constructors for py::module_ have been deprecated; please use pybind11::module_::create_extension_module if you were using the public constructor (fairly rare after PYBIND11_MODULE was introduced). #2552
• PYBIND11_OVERLOAD* macros and get_overload function replaced by correctly-named PYBIND11_OVERRIDE* and get_override, fixing inconsistencies in the presence of a closing ; in these macros. get_type_overload is deprecated. #2325

Packaging / building improvements:

• The Python package was reworked to be more powerful and useful. #2433
  • build-setuptools is easier thanks to a new pybind11.setup_helpers module, which provides utilities to use setuptools with pybind11. It can be used via PEP 518, setup_requires, or by directly importing or copying setup_helpers.py into your project.
  • CMake configuration files are now included in the Python package. Use pybind11.get_cmake_dir() or python -m pybind11 --cmakedir to get the directory with the CMake configuration files, or include the site-packages location in your CMAKE_MODULE_PATH. Or you can use the new pybind11[global] extra when you install pybind11, which installs the CMake files and headers into your base environment in the standard location.
  • pybind11-config is another way to write python -m pybind11 if you have your PATH set up.
  • Added external typing support to the helper module, code from import pybind11 can now be type checked. #2588
• Minimum CMake required increased to 3.4. #2338 and #2370
  • Full integration with CMake's C++ standard system and compile features replaces PYBIND11_CPP_STANDARD.
  • Generated config file is now portable to different Python/compiler/CMake versions.
  • Virtual environments prioritized if PYTHON_EXECUTABLE is not set (venv, virtualenv, and conda) (similar to the new FindPython mode).
  • Other CMake features now natively supported, like CMAKE_INTERPROCEDURAL_OPTIMIZATION, set(CMAKE_CXX_VISIBILITY_PRESET hidden).
  • CUDA as a language is now supported.
  • Helper functions pybind11_strip, pybind11_extension, pybind11_find_import added, see cmake/index.
  • Optional find-python-mode and nopython-mode with CMake. #2370
• Uninstall target added. #2265 and #2346
• pybind11_add_module() now accepts an optional OPT_SIZE flag that switches the binding target to size-based optimization if the global build type can not always be fixed to MinSizeRel (except in debug mode, where optimizations remain disabled). MinSizeRel or this flag reduces binary size quite substantially (~25% on some platforms). #2463

Smaller or developer focused features and fixes:

• Moved mkdoc.py to a new repo, pybind11-mkdoc. There are no longer submodules in the main repo.
• py::memoryview segfault fix and update, with new py::memoryview::from_memory in Python 3, and documentation. #2223
• Fix for buffer_info on Python 2. #2503
• If __eq__ defined but not __hash__, __hash__ is now set to None. #2291
• py::ellipsis now also works on Python 2. #2360
• Pointer to std::tuple & std::pair supported in cast. #2334
• Small fixes in NumPy support. py::array now uses py::ssize_t as first argument type. #2293
• Added missing signature for py::array. #2363
• unchecked_mutable_reference has access to operator () and [] when const. #2514
• py::vectorize is now supported on functions that return void. #1969
• py::capsule supports get_pointer and set_pointer. #1131
• Fix crash when different instances share the same pointer of the same type. #2252
• Fix for py::len not clearing Python's error state when it fails and throws. #2575
• Bugfixes related to more extensive testing, new GitHub Actions CI. #2321
• Bug in timezone issue in Eastern hemisphere midnight fixed. #2438
• std::chrono::time_point now works when the resolution is not the same as the system. #2481
• Bug fixed where py::array_t could accept arrays that did not match the requested ordering. #2484
• Avoid a segfault on some compilers when types are removed in Python. #2564
• py::arg::none() is now also respected when passing keyword arguments. #2611
• PyPy fixes, PyPy 7.3.x now supported, including PyPy3. (Known issue with PyPy2 and Windows #2596). #2146
• CPython 3.9.0 workaround for undefined behavior (macOS segfault). #2576
• CPython 3.9 warning fixes. #2253
• Improved C++20 support, now tested in CI. #2489 #2599
• Improved but still incomplete debug Python interpreter support. #2025
• NVCC (CUDA 11) now supported and tested in CI. #2461
• NVIDIA PGI compilers now supported and tested in CI. #2475
• At least Intel 18 now explicitly required when compiling with Intel. #2577
• Extensive style checking in CI, with pre-commit support. Code modernization, checked by clang-tidy.
• Expanded docs, including new main page, new installing section, and CMake helpers page, along with over a dozen new sections on existing pages.
• In GitHub, new docs for contributing and new issue templates.

Version 2.6.0 RC 3

Next release candidate.

• Factory constructor scope fix
• Support for PyPy3 on Windows 32, added to CI
• Fixes for C++20, added to CI for Clang, GCC, and MSVC 2019
• Black formatting for all Python code
• Allow ABI string overrides from 2.4 (advanced)

Version 2.6.0 RC 2

Next release candidate. Changes since RC 1:

Fixed:

• Python 3.9.0 bug workaround implemented
• Better support in CMake for packing and cross-compiling
• Fix for failing py::len leaving error state set
• Intel 18+ explicitly required, an issue with Intel compilers fixed
• Custom ipo flags disabled with RelWithDebInfo (use CMAKE_INTERPROCEDURAL_OPTIMIZATION for more control)
• Possible duplicate linker flags fixed in setup_helpers
• Changes to py::module_ constructor are no longer provisional.

New features:

• Static typing support for import pybind11

Version 2.6.0 RC 1

This is the first release candidate for pybind11 2.6.0. Please see the new features in the changelog, such as revamped CMake and setuptools support, keyword and positional argument support, and a long list of features, fixes, and improvements. Full Python 3.9 support and enhanced C++20 support.

Known issues:

• py::module_ direct construction provisionally deprecated
• Removing registered types can cause a segfault - old issue exposed by recent test additions; fix incoming
• On Python 3.9.0 and macOS, pybind11 may segfault when closing the interpreter after running the test suite