cppimport

26.4.17 verified Fri May 01 auth: no python

Import C++ files directly from Python by automatically compiling them with pybind11. Version 26.4.17, updated to work with Python up to 3.14, replacing deprecated distutils with setuptools._distutils.

pip install cppimport

Common errors

error ModuleNotFoundError: No module named 'cppimport' ↓

cause cppimport is not installed or the Python environment does not have it.

fix

Run 'pip install cppimport' in the correct environment.

error RuntimeError: Cannot load cppimport extension: No such file or directory: ... ↓

cause The C++ source file is missing or the filename does not match the import statement.

fix

Create the .cpp file with the correct name (e.g., mymodule.cpp for 'import mymodule').

error ImportError: dynamic module does not define module export function (PyInit_...) ↓

cause The PYBIND11_MODULE macro in the C++ file does not match the module name used in Python.

fix

Update PYBIND11_MODULE(mymodule, m) to match the filename (mymodule.cpp).

error AttributeError: module 'cppimport' has no attribute 'force_reload' ↓

cause Using an old version of cppimport that does not have force_reload (added in v22.05.10?).

fix

Upgrade to the latest version with 'pip install --upgrade cppimport'.

Warnings

breaking Version 26.4.17 removed the use of distutils and the 'dry-run' kwarg, which may break code relying on older internal APIs. ↓

fix Upgrade to >=26.4.17. If you used cppimport internals referencing distutils, update to setuptools._distutils.

gotcha cppimport does not recompile automatically when the C++ source changes; you must call cppimport.force_reload() or delete the .so file. ↓

fix Call cppimport.force_reload() before importing the module after modifying the .cpp file.

gotcha The C++ file must define a valid PYBIND11_MODULE (or similar) entry point, and the module name in the macro must match the filename. ↓

fix Ensure your .cpp file contains PYBIND11_MODULE(your_filename, m) where your_filename matches the .cpp filename.

deprecated Older versions (<22.08.02) did not expose version via __version__. ↓

fix Upgrade to get package version via cppimport.__version__.

Imports

cppimport
```
import cppimport
```
Main module for importing C++ files.

Quickstart

After installing, create a C++ file with a .cpp extension and a corresponding .py file with the same name (or use PYBIND11_MODULE macro). Use cppimport.force_reload() to recompile if the C++ source changes.

import cppimport
cppimport.force_reload()
import my_cpp_module  # assumes my_cpp_module.cpp exists and is configured