nanoeigenpy

This is a collection of tools for using Eigen together with nanobind, as a successor to the eigenpy support library. Its aim is to help the transition away from Boost.Python.

It reintroduces a few features (e.g. bindings for Eigen matrix decompositions) which are not in nanobind at time of writing.

Table of contents

• nanoeigenpy
  • Rationale
  • Features
    • Optional features
  • Example usage
    • Using the nanoeigenpy headers (with CMake)
    • Using the compiled Python module
  • Installation
    • Dependencies
      • Conda
      • Building
  • Contribution
  • Core-dev team
  • Credits

Rationale

Eigenpy was based on Boost.Python, an aging, complex, heavily templated library with little community support. Support for many library features initially present in Boost, and which were added to the STL since C++11/14/17, for over a decade (nearly two), were just never added in Boost.Python. This includes support for {boost,std}::optional, {boost,std}::variant, {boost,std}::unique_ptr, proper support for map types… whereas they have been present in pybind11, and now nanobind, for years.

These features were finally added to eigenpy with a lot of developer effort. This created additional need for supporting these additional features ourselves, including many downstream consumers (mainly in the robotics community).

Features

nanoeigenpy provides the following features to help you write bindings between Eigen and Python:

• bindings for Eigen’s Geometry module - quaternions, angle-axis representations…
• bindings for Eigen’s matrix dense and sparse decompositions and solvers

Optional features

nanoeigenpy also provides bindings for Eigen’s Cholmod and Apple Accelerate modules.

[!NOTE] The Accelerate module is available since Eigen 5.0 (Oct. 2025).

Cholmod is part of the SuiteSparse algorithms library. It can be installed standalone from conda.

Example usage

The features included in nanoeigenpy are distributed in a Python module which can be imported, or through standalone headers which can be included in your own Python bindings code using a CMake target.

Using the nanoeigenpy headers (with CMake)

To directly use the tools in nanoeigenpy’s headers, link to it in CMake (or whichever build tool you have, but only CMake support is planned so far).

# look for the nanoeigenpy CMake package
find_package(nanoeigenpy REQUIRED)

nanobind_add_module(my_ext NB_STATIC my_ext.cpp)
target_link_libraries(my_ext PRIVATE nanoeigenpy::nanoeigenpy_headers)

Then, in your C++ extension module code, include the relevant headers and call functions to expose the required type:

#include <nanoeigenpy/geometry/quaternion.hpp>

namespace nb = nanobind;

void f(const Eigen::Quaterniond &quat) {
    // ...
}

NB_MODULE(my_ext, m) {
    nanoeigenpy::exposeQuaternion<double>(m, "Quaternion");
    m.def("f", f, nb::arg("quat"));
}

Using the compiled Python module

In the case above, nanoeigenpy’s Python extension module already includes bindings for Eigen::Quaternion with the double scalar type (AKA Eigen::Quaterniond). Then, we can simply get nanobind to import it in our extension module:

```cpp #include <Eigen/Geometry>

namespace nb = nanobind;

void f(const Eigen::Quaterniond &quat) { // … }

NB_MODULE(my_ext, m) { // import nanoeigenpy’s module here

File truncated at 100 lines see the full file

Contributing Guidelines

Thank you for your interest in contributing to nanoeigenpy. Whether it’s a bug report, a new feature, a fix, or documentation, we value every contribution.

Read this document before opening an issue or a pull request.

All communication on this project must follow the Code of Conduct.

Table of contents

• Contributing Guidelines
  • Reporting bugs and feature requests
  • Asking questions
  • Contributing via pull requests
    • Choosing an issue
    • Set up the development environment
    • Keeping the pull request up-to-date
    • Pull request content
    • Running tests
    • Code style
    • Changelog
  • AI-assisted contributions
    • Responsibility
    • Disclosure
    • Communication
    • Translation
    • AI agent
  • Licensing

Reporting bugs and feature requests

Use the GitHub issue tracker to report bugs or suggest features.

Before opening an issue, check existing open and closed issues to avoid duplicates.

Use the appropriate template and give as much detail as possible. If you don’t use the template, maintainers may close your issue without explanation.

Asking questions

Ask questions in the discussions section. It separates development topics from community questions. Questions posted in the issue tracker will be moved to the discussions section.

Contributing via pull requests

Choosing an issue

Every external contributor pull request needs an associated issue. Open an issue first. Core developers will review it.

An issue is ready for a pull request when:

• It has the ready label.
• It is not assigned.
• It does not have the core developers label.

Issues with the core developers label are reserved for core developers.

If an issue meets these criteria, claim it with a short comment.

Set up the development environment

The easiest way to set up a development environment is to use pixi, as described in the build documentation.

See the CI workflows for examples with other package managers.

Pull request content

To create a pull request, follow the GitHub guides on forking a repository and creating a pull request.

In your pull request:

• Use a descriptive title and follow the pull request template.
• If the pull request is not ready for review, keep it as a draft.
• Keep it to a single self-contained change. Don’t mix unrelated fixes.
• Keep backward compatibility. Don’t break the API.
• Write tests that cover your changes.
• Add an entry to the changelog.
• Make sure code style checks pass (pixi run lint or pre-commit run --all-files).
• Make sure the CI is green. Ask for help if you’re stuck on a CI issue.
• Check all the appropriate items in the pull request template checklist.

Keeping the pull request up-to-date

You must rebase your work on the upstream main branch.

git pull --rebase origin main

Don’t omit the --rebase argument or a merge commit will be created. Using merge commits to update your pull request is discouraged as it creates a non-linear git history.

Running tests

File truncated at 100 lines see the full file