Please be advised that the reference documentation discussing pybind11 internals is currently incomplete. Please refer to the previous sections and the pybind11 header files for the nitty gritty details.



PYBIND11_MODULE(name, variable)

This macro creates the entry point that will be invoked when the Python interpreter imports an extension module. The module name is given as the fist argument and it should not be in quotes. The second macro argument defines a variable of type py::module which can be used to initialize the module.

PYBIND11_MODULE(example, m) {
    m.doc() = "pybind11 example module";

    // Add bindings here
    m.def("foo", []() {
        return "Hello, World!";

Convenience classes for arbitrary Python types

Common member functions

template <typename Derived>
class object_api

A mixin class which adds common functions to handle, object and various accessors. The only requirement for Derived is to implement PyObject *Derived::ptr() const.

Inherits from pyobject_tag

Public Functions

iterator begin() const

Return an iterator equivalent to calling iter() in Python. The object must be a collection which supports the iteration protocol.

iterator end() const

Return a sentinel which ends iteration.

item_accessor operator[](handle key) const

Return an internal functor to invoke the object’s sequence protocol. Casting the returned detail::item_accessor instance to a handle or object subclass causes a corresponding call to __getitem__. Assigning a handle or object subclass causes a call to __setitem__.

item_accessor operator[](const char *key) const

See above (the only difference is that they key is provided as a string literal)

obj_attr_accessor attr(handle key) const

Return an internal functor to access the object’s attributes. Casting the returned detail::obj_attr_accessor instance to a handle or object subclass causes a corresponding call to getattr. Assigning a handle or object subclass causes a call to setattr.

str_attr_accessor attr(const char *key) const

See above (the only difference is that they key is provided as a string literal)

args_proxy operator*() const

Matches * unpacking in Python, e.g. to unpack arguments out of a tuple or list for a function call. Applying another * to the result yields ** unpacking, e.g. to unpack a dict as function keyword arguments. See Calling Python functions.

template <typename T>
bool contains(T &&item) const

Check if the given item is contained within this object, i.e. item in obj.

template <return_value_policy policy = return_value_policy::automatic_reference, typename… Args>
object operator()(Args&&... args) const

Assuming the Python object is a function or implements the __call__ protocol, operator() invokes the underlying function, passing an arbitrary set of parameters. The result is returned as a object and may need to be converted back into a Python object using handle::cast().

When some of the arguments cannot be converted to Python objects, the function will throw a cast_error exception. When the Python function call fails, a error_already_set exception is thrown.

bool is(object_api const &other) const

Equivalent to obj is other in Python.

bool is_none() const

Equivalent to obj is None in Python.

bool equal(object_api const &other) const

Equivalent to obj == other in Python.

str_attr_accessor doc() const

Get or set the object’s docstring, i.e. obj.__doc__.

int ref_count() const

Return the object’s current reference count.

handle get_type() const

Return a handle to the Python type object underlying the instance.

Without reference counting

class handle

Holds a reference to a Python object (no reference counting)

The handle class is a thin wrapper around an arbitrary Python object (i.e. a PyObject * in Python’s C API). It does not perform any automatic reference counting and merely provides a basic C++ interface to various Python API functions.

See also

The object class inherits from handle and adds automatic reference counting features.

Inherits from detail::object_api< handle >

Subclassed by args_proxy, kwargs_proxy, object

Public Functions


The default constructor creates a handle with a nullptr-valued pointer.

handle(PyObject *ptr)

Creates a handle from the given raw Python object pointer.

PyObject *ptr() const

Return the underlying PyObject * pointer.

const handle &inc_ref() const

Manually increase the reference count of the Python object. Usually, it is preferable to use the object class which derives from handle and calls this function automatically. Returns a reference to itself.

const handle &dec_ref() const

Manually decrease the reference count of the Python object. Usually, it is preferable to use the object class which derives from handle and calls this function automatically. Returns a reference to itself.

template <typename T>
T cast() const

Attempt to cast the Python object into the given C++ type. A cast_error will be throw upon failure.

operator bool() const

Return true when the handle wraps a valid Python object.

bool operator==(const handle &h) const

Deprecated: Check that the underlying pointers are the same. Equivalent to obj1 is obj2 in Python.

With reference counting

class object

Holds a reference to a Python object (with reference counting)

Like handle, the object class is a thin wrapper around an arbitrary Python object (i.e. a PyObject * in Python’s C API). In contrast to handle, it optionally increases the object’s reference count upon construction, and it always decreases the reference count when the object instance goes out of scope and is destructed. When using object instances consistently, it is much easier to get reference counting right at the first attempt.

Inherits from handle

Subclassed by bool_, buffer, bytes, capsule, dict, dtype, exception< type >, float_, function, generic_type, int_, iterable, iterator, list, memoryview, module, none, sequence, set, slice, str, tuple, weakref

Public Functions

object(const object &o)

Copy constructor; always increases the reference count.

object(object &&other)

Move constructor; steals the object from other and preserves its reference count.


Destructor; automatically calls handle::dec_ref()

handle release()

Resets the internal pointer to nullptr without without decreasing the object’s reference count. The function returns a raw handle to the original Python object.

template <typename T>
T reinterpret_borrow(handle h)

Declare that a handle or PyObject * is a certain type and borrow the reference. The target type T must be object or one of its derived classes. The function doesn’t do any conversions or checks. It’s up to the user to make sure that the target type is correct.

PyObject *p = PyList_GetItem(obj, index);
py::object o = reinterpret_borrow<py::object>(p);
// or
py::tuple t = reinterpret_borrow<py::tuple>(p); // <-- `p` must be already be a `tuple`

template <typename T>
T reinterpret_steal(handle h)

Like reinterpret_borrow(), but steals the reference.

PyObject *p = PyObject_Str(obj);
py::str s = reinterpret_steal<py::str>(p); // <-- `p` must be already be a `str`

Convenience classes for specific Python types

class module

Wrapper for Python extension modules.

Inherits from object

Public Functions

module(const char *name, const char *doc = nullptr)

Create a new top-level Python module with the given name and docstring.

template <typename Func, typename… Extra>
module &def(const char *name_, Func &&f, const Extra&... extra)

Create Python binding for a new function within the module scope. Func can be a plain C++ function, a function pointer, or a lambda function. For details on the Extra&& ... extra argument, see section Passing extra arguments to def or class_.

module def_submodule(const char *name, const char *doc = nullptr)

Create and return a new Python submodule with the given name and docstring. This also works recursively, i.e.

py::module m("example", "pybind11 example plugin");
py::module m2 = m.def_submodule("sub", "A submodule of 'example'");
py::module m3 = m2.def_submodule("subsub", "A submodule of 'example.sub'");

void reload()

Reload the module or throws error_already_set.

Public Static Functions

static module import(const char *name)

Import and return a module or throws error_already_set.

group pytypes


template <typename Unsigned>
Unsigned as_unsigned(PyObject *o)
bytes(const pybind11::str &s)
str(const bytes &b)
class iterator
#include <pytypes.h>

Wraps a Python iterator so that it can also be used as a C++ input iterator

Caveat: copying an iterator does not (and cannot) clone the internal state of the Python iterable. This also applies to the post-increment operator. This iterator should only be used to retrieve the current value using operator*().

Inherits from object

Public Static Functions

static iterator sentinel()

The value which marks the end of the iteration. it == iterator::sentinel() is equivalent to catching StopIteration in Python.

void foo(py::iterator it) {
    while (it != py::iterator::sentinel()) {
       // use `*it`

class iterable

Inherits from object

class str

Inherits from object

Public Functions

str(handle h)

Return a string representation of the object. This is analogous to the str() function in Python.

class bytes

Inherits from object

class none

Inherits from object

class bool_

Inherits from object

class int_

Inherits from object

class float_

Inherits from object

class weakref

Inherits from object

class slice

Inherits from object

class capsule

Inherits from object

class tuple

Inherits from object

Subclassed by args

class dict

Inherits from object

Subclassed by kwargs

class sequence

Inherits from object

class list

Inherits from object

class args

Inherits from tuple

class kwargs

Inherits from dict

class set

Inherits from object

class function

Inherits from object

Subclassed by cpp_function

class buffer

Inherits from object

Subclassed by array

class memoryview

Inherits from object

Passing extra arguments to def or class_

group annotations
struct is_method
#include <attr.h>

Annotation for methods.

struct is_operator
#include <attr.h>

Annotation for operators.

struct scope
#include <attr.h>

Annotation for parent scope.

struct doc
#include <attr.h>

Annotation for documentation.

struct name
#include <attr.h>

Annotation for function names.

struct sibling
#include <attr.h>

Annotation indicating that a function is an overload associated with a given “sibling”.

template <typename T>
struct base
#include <attr.h>

Annotation indicating that a class derives from another given type.

template <size_t Nurse, size_t Patient>
struct keep_alive
#include <attr.h>

Keep patient alive while nurse lives.

struct multiple_inheritance
#include <attr.h>

Annotation indicating that a class is involved in a multiple inheritance relationship.

struct dynamic_attr
#include <attr.h>

Annotation which enables dynamic attributes, i.e. adds __dict__ to a class.

struct buffer_protocol
#include <attr.h>

Annotation which enables the buffer protocol for a type.

struct metaclass
#include <attr.h>

Annotation which requests that a special metaclass is created for a type.

Public Functions

metaclass(handle value)

Override pybind11’s default metaclass.

struct module_local
#include <attr.h>

Annotation that marks a class as local to the module:

struct arithmetic
#include <attr.h>

Annotation to mark enums as an arithmetic type.

template <typename… Ts>
struct call_guard
#include <attr.h>

A call policy which places one or more guard variables (Ts...) around the function call.

For example, this definition:

m.def("foo", foo, py::call_guard<T>());

is equivalent to the following pseudocode:

m.def("foo", [](args...) {
    T scope_guard;
    return foo(args...); // forwarded arguments

struct arg
#include <cast.h>

Annotation for arguments

Subclassed by arg_v

Public Functions

constexpr arg(const char *name = nullptr)

Constructs an argument with the name of the argument; if null or omitted, this is a positional argument.

template <typename T>
arg_v operator=(T &&value) const

Assign a value to this argument.

arg &noconvert(bool flag = true)

Indicate that the type should not be converted in the type caster.

arg &none(bool flag = true)

Indicates that the argument should/shouldn’t allow None (e.g. for nullable pointer args)

Public Members

const char *name

If non-null, this is a named kwargs argument.

bool flag_noconvert

If set, do not allow conversion (requires a supporting type caster!)

bool flag_none

If set (the default), allow None to be passed to this argument.

struct arg_v
#include <cast.h>

Annotation for arguments with values

Inherits from arg

Public Functions

template <typename T>
arg_v(const char *name, T &&x, const char *descr = nullptr)

Direct construction with name, default, and description.

template <typename T>
arg_v(const arg &base, T &&x, const char *descr = nullptr)

Called internally when invoking py::arg("a") = value

arg_v &noconvert(bool flag = true)

Same as arg::noconvert(), but returns *this as arg_v&, not arg&.

arg_v &none(bool flag = true)

Same as arg::nonone(), but returns *this as arg_v&, not arg&.

Public Members

object value

The default value.

const char *descr

The (optional) description of the default value.

std::string type

The C++ type name of the default value (only available when compiled in debug mode)

Embedding the interpreter

PYBIND11_EMBEDDED_MODULE(name, variable)

Add a new module to the table of builtins for the interpreter. Must be defined in global scope. The first macro parameter is the name of the module (without quotes). The second parameter is the variable which will be used as the interface to add functions and classes to the module.

    // ... initialize functions and classes here
    m.def("foo", []() {
        return "Hello, World!";

void initialize_interpreter(bool init_signal_handlers = true)

Initialize the Python interpreter. No other pybind11 or CPython API functions can be called before this is done; with the exception of PYBIND11_EMBEDDED_MODULE. The optional parameter can be used to skip the registration of signal handlers (see the Python documentation for details). Calling this function again after the interpreter has already been initialized is a fatal error.

If initializing the Python interpreter fails, then the program is terminated. (This is controlled by the CPython runtime and is an exception to pybind11’s normal behavior of throwing exceptions on errors.)

void finalize_interpreter()

Shut down the Python interpreter. No pybind11 or CPython API functions can be called after this. In addition, pybind11 objects must not outlive the interpreter:

{ // BAD
    auto hello = py::str("Hello, World!");
} // <-- BOOM, hello's destructor is called after interpreter shutdown

{ // GOOD
    { // scoped
        auto hello = py::str("Hello, World!");
    } // <-- OK, hello is cleaned up properly

    py::scoped_interpreter guard{};
    auto hello = py::str("Hello, World!");


The interpreter can be restarted by calling initialize_interpreter() again. Modules created using pybind11 can be safely re-initialized. However, Python itself cannot completely unload binary extension modules and there are several caveats with regard to interpreter restarting. All the details can be found in the CPython documentation. In short, not all interpreter memory may be freed, either due to reference cycles or user-created global data.

class scoped_interpreter

Scope guard version of initialize_interpreter() and finalize_interpreter(). This a move-only guard and only a single instance can exist.

#include <pybind11/embed.h>

int main() {
    py::scoped_interpreter guard{};
    py::print(Hello, World!);
} // <-- interpreter shutdown

Redirecting C++ streams

class scoped_ostream_redirect

This a move-only guard that redirects output.

#include <pybind11/iostream.h>


    py::scoped_ostream_redirect output;
    std::cout << "Hello, World!"; // Python stdout
} // <-- return std::cout to normal

You can explicitly pass the c++ stream and the python object, for example to guard stderr instead.

    py::scoped_ostream_redirect output{std::cerr, py::module::import("sys").attr("stderr")};
    std::cerr << "Hello, World!";

Subclassed by scoped_estream_redirect

class scoped_estream_redirect

Like scoped_ostream_redirect, but redirects cerr by default. This class is provided primary to make py::call_guard easier to make.

m.def("noisy_func", &noisy_func,

Inherits from scoped_ostream_redirect

class_<detail::OstreamRedirect> add_ostream_redirect(module m, std::string name = "ostream_redirect")

This is a helper function to add a C++ redirect context manager to Python instead of using a C++ guard. To use it, add the following to your binding code:

#include <pybind11/iostream.h>


py::add_ostream_redirect(m, "ostream_redirect");

You now have a Python context manager that redirects your output:

with m.ostream_redirect():

This manager can optionally be told which streams to operate on:

with m.ostream_redirect(stdout=true, stderr=true):

Python built-in functions

group python_builtins

Unless stated otherwise, the following C++ functions behave the same as their Python counterparts.


dict globals()

Return a dictionary representing the global variables in the current execution frame, or __main__.__dict__ if there is no frame (usually when the interpreter is embedded).

template <typename T, detail::enable_if_t< std::is_base_of< object, T >::value, int > = 0>
bool isinstance(handle obj)

Return true if obj is an instance of T. Type T must be a subclass of object or a class which was exposed to Python as py::class_<T>.

bool isinstance(handle obj, handle type)

Return true if obj is an instance of the type.

bool hasattr(handle obj, handle name)
bool hasattr(handle obj, const char *name)
object getattr(handle obj, handle name)
object getattr(handle obj, const char *name)
object getattr(handle obj, handle name, handle default_)
object getattr(handle obj, const char *name, handle default_)
void setattr(handle obj, handle name, handle value)
void setattr(handle obj, const char *name, handle value)
ssize_t hash(handle obj)
size_t len(handle h)
str repr(handle h)
iterator iter(handle obj)


class error_already_set

Fetch and hold an error which was already set in Python. An instance of this is typically thrown to propagate python-side errors back through C++ which can either be caught manually or else falls back to the function dispatcher (which then raises the captured error back to python).

Inherits from runtime_error

Public Functions


Constructs a new exception from the current Python error indicator, if any. The current Python error indicator will be cleared.

void restore()

Give the currently-held error back to Python, if any. If there is currently a Python error already set it is cleared first. After this call, the current object no longer stores the error variables (but the .what() string is still available).

bool matches(handle ex) const

Check if the currently trapped error type matches the given Python exception class (or a subclass thereof). May also be passed a tuple to search for any exception class matches in the given tuple.

class builtin_exception

C++ bindings of builtin Python exceptions.

Inherits from runtime_error

Subclassed by cast_error, index_error, key_error, reference_cast_error, stop_iteration, type_error, value_error

Public Functions

virtual void set_error() const = 0

Set the error using the Python C API.


namespace literals


constexpr arg operator""_a(const char *name, size_t)

String literal version of arg

str operator""_s(const char *s, size_t size)

String literal version of str