pybind11/AGENTS.md

Agent instructions

What this is

pybind11 v3 is a header-only C++ library that exposes C++ types to Python and vice versa. The "library" is entirely the headers under include/pybind11/; there is nothing to compile or link for a consumer. Everything else in the repo — the Python package, CMake tooling, and tests — exists to package, distribute, and verify those headers.

The version of record lives in include/pybind11/detail/common.h (as PYBIND11_VERSION_* macros); pybind11/_version.py parses it from there.

Build & test

The C++ tests need a compiler; the recommended flow uses CMake presets + uv:

cmake --workflow venv          # set up a .venv and run all tests (config + build + check)

Break it apart to control Python version or target:

cmake --preset venv -DPYBIND11_CREATE_WITH_UV=3.13t   # configure (e.g. free-threaded 3.13)
cmake --build --preset venv                           # build the test extension modules
cmake --build --preset venv -t cpptest                # build/run just the C++ (Catch2) tests

The default preset uses an existing Python/venv rather than creating one. Presets default to Ninja, Debug, PYBIND11_WERROR=ON, DOWNLOAD_CATCH=ON, DOWNLOAD_EIGEN=ON, and export compile_commands.json.

Manual full setup (no presets):

cmake -S . -B build -DDOWNLOAD_CATCH=ON -DDOWNLOAD_EIGEN=ON
cmake --build build -j4

Test targets

Run via cmake --build build --target <name>:

• check — everything (pytest + cpptest + cmake build tests)
• pytest — Python tests only
• cpptest — C++ Catch2 tests only
• test_cmake_build — install / add_subdirectory integration tests

Tests come in pairs: tests/test_<name>.cpp (binds C++ test fixtures into a module) and tests/test_<name>.py (exercises them with pytest). To build only a subset, configure with -DPYBIND11_TEST_OVERRIDE="test_callbacks;test_pickling" (names without extension; empty = all).

Run a single Python test directly (the .so is not installed into the venv, so run from the build tree's tests/ dir):

cd build && source .venv/bin/activate && cd tests
python -m pytest test_callbacks.py -k some_test

Pass pytest flags via PYTEST_ADDOPTS, e.g. env PYTEST_ADDOPTS="-s -x" cmake --build build --target pytest.

nox shortcuts (minimal setup, slower)

nox -s lint, nox -s tests-3.9, nox -s docs -- serve, nox -s build. With uvx nox you don't even need nox installed.

Linting

Use prek -a --quiet (Rust version of pre-commit run -a) before committing. Pre-commit handles all formatting and most linting.

clang-tidy support is built into CMake (cmake --preset tidy), normally run in CI/Docker, not locally.

Architecture of the headers

include/pybind11/pybind11.h is the main entry point that most users include; it pulls in the core machinery. Key layers:

• detail/ — internal implementation, not part of the public API. This is where the hard parts live:
  • type_caster_base.h, cast.h (include/pybind11/cast.h) — the type conversion system that maps C++ ↔ Python values. Most binding behavior ultimately routes through type casters.
  • internals.h — the per-interpreter global state (registered types, instances, etc.), shared across modules via a capsule. ABI compatibility is gated by an ID; changing internals layout is an ABI break.
  • struct_smart_holder.h / using_smart_holder.h — smart_holder was added in v3, enabling safe passing of objects between shared_ptr/unique_ptr and Python ownership. It is the recommended holder for most situations, but for backward compatibility it is not the default holder, and there are no plans to make it the default holder in the future.
  • class.h, init.h — class registration and constructor (py::init) machinery.
• pytypes.h — C++ wrappers for Python objects (py::object, py::dict, py::str, …) with reference counting.
• Feature headers — opt-in includes: stl.h / stl/ / stl_bind.h (STL conversions), numpy.h + eigen/ (array/matrix interop), functional.h (std::function), chrono.h, complex.h, eval.h, embed.h (embedding the interpreter), iostream.h, gil.h / gil_safe_call_once.h, subinterpreter.h, native_enum.h, typing.h, warnings.h.
• conduit/ — pybind11_conduit_v1, a stable cross-binding-framework protocol for sharing C++ objects between independently-built extension modules (even different pybind11 versions / other frameworks).

Because consumers can mix modules built against different pybind11 versions in one process, ABI stability is a first-class concern — be deliberate about anything touching internals.h, holders, or the platform ABI id (conduit/pybind11_platform_abi_id.h).

The Python package (pybind11/)

Separate from the C++ library: it ships the headers and CMake config so downstream projects can build extensions. Notable modules:

• setup_helpers.py — Pybind11Extension / build_ext and the intree_extensions helper for setuptools-based builds; this file is intentionally standalone-copyable.
• commands.py / __main__.py — python -m pybind11 --includes / --cmakedir etc., used by build systems to locate headers and CMake files.

Packaging produces two distributions: the normal pybind11 (headers live inside the package, found via the functions above) and pybind11-global (installs to <env>/include/pybind11 and <env>/share/cmake/pybind11 for system-wide CMake discovery). Build with nox -s build and nox -s build_global. The build backend is scikit-build-core. Packaging tests live in tests/extra_python_package (nox -s tests_packaging).

CMake tooling (tools/)

pybind11Common.cmake, pybind11Tools.cmake (classic FindPythonLibs path), and pybind11NewTools.cmake (CMake 3.12+ FindPython path, selected with -DPYBIND11_FINDPYTHON=ON) implement the pybind11_add_module() interface and the pybind11::* interface targets that downstream CMakeLists.txt files consume.

Conventions

• Small, self-contained PRs; this project deliberately favors minimal-code general solutions.
• Any new functionality needs a test (add to or create the paired .cpp/.py in tests/, and register the test in tests/CMakeLists.txt).
• Bug fixes should be paired with new tests that fail without the fix.
• 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)