{"id":7999,"library":"ccimport","title":"ccimport","description":"ccimport is a lightweight Python package designed for rapidly building C++ bindings for Python. It streamlines the process of compiling and importing C++ extension modules directly from Python code. As of version 0.4.4, it supports Python versions 3.6 and above. The library is actively maintained with periodic releases.","status":"active","version":"0.4.4","language":"en","source_language":"en","source_url":"https://github.com/FindDefinition/ccimport","tags":["C++","binding","extension","compilation","pybind11"],"install":[{"cmd":"pip install ccimport","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"While specific functions like 'load' or 'imp' are used, the primary interaction usually starts with importing the top-level 'ccimport' module.","wrong":"from ccimport import load # Or similar direct imports for functions like 'load' or 'imp'","symbol":"ccimport","correct":"import ccimport"}],"quickstart":{"code":"import ccimport\nimport os\n\n# Create a dummy C++ file that uses pybind11\ncpp_code = '''\n// somecode.cpp\n// cppimport\n#include <pybind11/pybind11.h>\n\nint add(int i, int j) {\n    return i + j;\n}\n\n// PYBIND11_MODULE must match the base filename (somecode)\nPYBIND11_MODULE(somecode, m) {\n    m.doc() = \"pybind11 example plugin\"; // optional module docstring\n    m.def(\"add\", &add, \"A function that adds two numbers\");\n}\n'''\n\nwith open('somecode.cpp', 'w') as f:\n    f.write(cpp_code)\n\ntry:\n    # Load the C++ module\n    # ccimport.load will automatically compile if needed\n    some_module = ccimport.load('somecode.cpp')\n    print(f\"Result of add(1, 2): {some_module.add(1, 2)}\")\nexcept Exception as e:\n    print(f\"Error loading/executing C++ module: {e}\")\nfinally:\n    # Clean up the generated C++ file\n    if os.path.exists('somecode.cpp'):\n        os.remove('somecode.cpp')\n    # ccimport may create a build directory, clean it up if known\n    # This part is highly dependent on ccimport's internal logic and temp file naming.\n    # For a robust cleanup, one might need to inspect ccimport.settings or known build paths.\n","lang":"python","description":"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."},"warnings":[{"fix":"Ensure `// cppimport` is the very first line of your C++ source file.","message":"C++ 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade 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`).","message":"`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.","severity":"breaking","affected_versions":"< 0.3.0"},{"fix":"For 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions (when using release/production optimizations)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `// 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.","cause":"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.","error":"ModuleNotFoundError: No module named 'your_module_name'"},{"fix":"Check 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.","cause":"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`).","error":"Error: C import failed"},{"fix":"Double-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.","cause":"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.","error":"TypeError: 'module' object is not callable"}]}