Install & Compatibility
Where this runs
tested against v3.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.9s · import 0.280s · 324MB
326MB installed
● package 326MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
eigenpy
✓ import eigenpy
The primary module exposing Eigen types and conversion utilities.
enableEigenPy
✓ eigenpy.enableEigenPy()
Must be called once to register Eigen types and enable conversions.
MatrixXd
✓ eigenpy.MatrixXd
✗ eigenpy.hpp.MatrixXd
In EigenPy v3.x, Eigen types like MatrixXd are directly under the 'eigenpy' namespace, not 'eigenpy.hpp' as in older versions.
toEigen
✓ eigenpy.toEigen
Converts a NumPy array to an Eigen matrix (creates a copy by default).
toNumpy
✓ eigenpy.toNumpy
Converts an Eigen matrix to a NumPy array (creates a view by default).
This quickstart demonstrates the core functionality of EigenPy: enabling the bindings, creating an Eigen matrix, converting it to a NumPy array (showing view semantics), and converting a NumPy array back to an Eigen matrix (showing copy semantics).
import eigenpy
import numpy as np
# IMPORTANT: Enable EigenPy functionality
eigenpy.enableEigenPy()
# Create an Eigen MatrixXd instance (from C++ bindings)
mat_eigen = eigenpy.MatrixXd(3, 3)
mat_eigen.setRandom()
print('Eigen MatrixXd (random):\n', mat_eigen)
# Convert Eigen matrix to NumPy array (creates a view by default)
np_view = np.asarray(mat_eigen)
print('\nNumPy view of Eigen matrix:\n', np_view)
# Modifying the NumPy view also modifies the underlying Eigen matrix
np_view[0, 0] = 99.0
print('\nEigen MatrixXd after NumPy view modification:\n', mat_eigen)
# Convert NumPy array to Eigen matrix (creates a copy by default)
numpy_orig = np.array([[1.0, 2.0], [3.0, 4.0]])
mat_eigen_from_np = eigenpy.toEigen(numpy_orig)
print('\nEigen matrix from NumPy array:\n', mat_eigen_from_np)
Debug
Known issues
breakingWith the release of EigenPy v3.0.0, the exposed Eigen C++ types moved from a nested namespace (e.g., `eigenpy.hpp.MatrixXd`) directly into the main `eigenpy` module.fixUpdate your imports: change `from eigenpy.hpp import MatrixXd` or `eigenpy.hpp.MatrixXd` to `from eigenpy import MatrixXd` or `eigenpy.MatrixXd`.
affects: >=3.0.0
gotchaThe function `eigenpy.enableEigenPy()` must be called exactly once in your program's lifecycle before any EigenPy functionality (like type conversions or creating Eigen objects) can be used. Forgetting this will lead to errors.fixEnsure `eigenpy.enableEigenPy()` is called at the beginning of your script or application initialization.
affects: All versions
gotchaConversions between Eigen matrices and NumPy arrays have different memory semantics. Converting an Eigen matrix to NumPy using `np.asarray(eigen_matrix)` creates a *view* (no copy), meaning changes to the NumPy array will reflect in the Eigen matrix. Conversely, converting a NumPy array to Eigen using `eigenpy.toEigen(numpy_array)` creates a *copy* by default.fixBe explicit about desired memory behavior. For guaranteed copies, use `eigenpy.toNumpyCopy(eigen_matrix)` or `eigenpy.toEigenCopy(numpy_array)`. To work with views, use `np.asarray(eigen_matrix)` carefully.
affects: All versions, especially >=3.10.0
gotchaEigenPy leverages Boost.Python for its bindings. While transparent for basic use, advanced users developing custom C++ extensions that interact with EigenPy might need to ensure their build system (e.g., CMake) correctly links against Boost.Python and Eigen versions compatible with the installed EigenPy wheel.fixRefer to the EigenPy GitHub repository and examples for guidance on integrating custom C++ code with EigenPy bindings.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'eigenpy'
The eigenpy package is not installed in the Python environment, or the Python interpreter cannot find it in its search path.
fixInstall eigenpy using pip or conda: `pip install eigenpy` or `conda install eigenpy -c conda-forge`.
from eigenpy.hpp import MatrixXd
In EigenPy v3.0.0 and later, Eigen C++ types (like MatrixXd) were moved directly into the main `eigenpy` module, removing the `hpp` submodule.
fixUpdate your import statement to directly import from `eigenpy`: `from eigenpy import MatrixXd` or `eigenpy.MatrixXd`.
error: use of undeclared identifier 'PyArray_TypeNumFromName'
This compilation error occurs when building eigenpy against NumPy 2.0 beta or newer, as the `PyArray_TypeNumFromName` C-API function was removed in NumPy 2.0.
fixDowngrade NumPy to a version compatible with eigenpy (e.g., NumPy 1.x) or wait for an eigenpy release that officially supports NumPy 2.x.
TypeError: Unregistered type : Eigen::Transform<double, 3, 2, 0>
This error indicates that a specific Eigen type, such as `Eigen::Transform` (or `Eigen::Affine` types derived from it), does not have a registered Python binding, meaning EigenPy or the underlying `pybind11` configuration does not natively support direct conversion for this particular complex Eigen type.
fixManually convert the `Eigen::Transform` data to a supported EigenPy type (like `Eigen::MatrixXd`) before passing it to Python, or implement custom `pybind11` converters for `Eigen::Transform` if you are extending the bindings.
ImportError: undefined symbol: _ZN5Eigen...
The 'eigenpy' shared library was built successfully but cannot find a required symbol from its C++ dependencies (e.g., Eigen or Boost) at runtime, often due to mismatched library versions or incorrect linker paths.
fixEnsure all C++ dependencies are correctly installed and visible to the linker. Reinstall 'eigenpy' in a clean environment or use `conda install eigenpy -c conda-forge`.
Upgrade
Version history
3.13.0latest on PyPI · released May 21, 2026
Audit
Dependencies
numpyrequiredCore functionality relies on interoperability with NumPy arrays.