Install & Compatibility
Where this runs
tested against v0.4.4 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.143s · 22.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.3s · import 0.137s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ccimport
✓ import ccimport
✗ from ccimport import load # Or similar direct imports for functions like 'load' or 'imp'
While specific functions like 'load' or 'imp' are used, the primary interaction usually starts with importing the top-level 'ccimport' module.
This quickstart demonstrates how to define a C++ function using pybind11, save it to a `.cpp` file, and then use `ccimport.load()` to compile and import it directly into Python. Note the `// cppimport` comment on the first line of the C++ file, which is crucial for `ccimport` to process it.
import ccimport
import os
# Create a dummy C++ file that uses pybind11
cpp_code = '''
// somecode.cpp
// cppimport
#include <pybind11/pybind11.h>
int add(int i, int j) {
return i + j;
}
// PYBIND11_MODULE must match the base filename (somecode)
PYBIND11_MODULE(somecode, m) {
m.doc() = "pybind11 example plugin"; // optional module docstring
m.def("add", &add, "A function that adds two numbers");
}
'''
with open('somecode.cpp', 'w') as f:
f.write(cpp_code)
try:
# Load the C++ module
# ccimport.load will automatically compile if needed
some_module = ccimport.load('somecode.cpp')
print(f"Result of add(1, 2): {some_module.add(1, 2)}")
except Exception as e:
print(f"Error loading/executing C++ module: {e}")
finally:
# Clean up the generated C++ file
if os.path.exists('somecode.cpp'):
os.remove('somecode.cpp')
# ccimport may create a build directory, clean it up if known
# This part is highly dependent on ccimport's internal logic and temp file naming.
# For a robust cleanup, one might need to inspect ccimport.settings or known build paths.
Debug
Known issues
gotchaC++ source files intended for `ccimport` (or its underlying mechanism `cppimport`) *must* include the comment `// cppimport` on the first line. Without this, the library will ignore the file, potentially leading to 'module not found' errors or unexpected behavior.fixEnsure `// cppimport` is the very first line of your C++ source file.
affects: All versions
breaking`ccimport` version 0.3 and above requires Python 3.6+. Older versions (0.2.x) supported Python 3.5. Attempting to use newer `ccimport` versions on Python < 3.6 will result in installation or runtime errors.fixUpgrade to Python 3.6 or newer, or use an older `ccimport` version compatible with Python 3.5 if absolutely necessary (e.g., `ccimport==0.2.x`).
affects: < 0.3.0
gotchaWhen distributing applications that use `ccimport`, compiled binaries should be pre-built and included. If `ccimport` is configured for 'release mode' (or similar performance optimizations), it may skip checksum and existence checks. If binaries are missing in this mode, it will cause exceptions instead of recompiling.fixFor production, pre-compile all C++ extension modules and ensure they are present. Avoid relying on runtime compilation in critical deployment scenarios. If using `cppimport`'s `release_mode` setting, ensure all binaries exist.
affects: All versions (when using release/production optimizations)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'your_module_name'
The C++ source file (e.g., `your_module_name.cpp`) either lacks the `// cppimport` comment on the first line, or `ccimport` cannot find the file in the Python import path.
fixAdd `// cppimport` as the very first line of `your_module_name.cpp`. Ensure the directory containing `your_module_name.cpp` is in `sys.path` or use `ccimport.load('/path/to/your_module_name.cpp')` with an absolute or relative path. Error: C import failed
This error typically indicates that the C++ compiler encountered issues when trying to build the extension module, often due to missing header files, incorrect syntax in the C++ code, or an inability to locate necessary libraries (e.g., `pybind11`).
fixCheck your C++ code for syntax errors. Ensure all required C++ header files are correctly included and accessible by the compiler. If using `pybind11`, verify it's correctly installed and its headers are discoverable by the build system. Check `ccimport`'s verbose output for specific compiler errors.
TypeError: 'module' object is not callable
This usually happens when you try to call a C++ function directly from the imported Python module object, but the function was not correctly exposed via `pybind11` (or similar binding library) or was misspelled.
fixDouble-check the `PYBIND11_MODULE` definition in your C++ code to ensure the function (`m.def("function_name", &function_pointer, "docstring")`) is correctly defined and its name matches what you are calling in Python. Verify the function signature in C++ matches the binding. Upgrade
Version history
0.4.4latest on PyPI · released Oct 15, 2024
Audit
Dependencies
No dependency data recorded yet.