How does cppimport compare to using CMake with pybind11?

cppimport is simpler for quick prototyping and small projects, automating compilation on import without separate build files. CMake offers more control for large, complex builds with better incremental compilation and dependency management.

How to add external libraries in cppimport?

Specify external libraries using cfg['libraries'] and cfg['include_dirs'] in the Mako configuration block within your C++ file, similar to standard distutils setup, as shown in the FAQ section on compiler args.

Does cppimport work with C code or only C++?

cppimport supports both C and C++ files, but it's optimized for C++ with pybind11. For C code, you may need to adjust bindings or use alternative methods like cffi, though it can still compile C sources.

What happens if the file lock fails in cppimport?

If file locking is unsupported (e.g., on some networked filesystems), builds may hang or timeout. You can disable locking with cppimport.settings['use_filelock'] = False and manage concurrency manually, as explained in the README.

How to debug compilation errors in cppimport?

Enable verbose logging by configuring Python's logging for the 'cppimport' logger to see detailed build output. Errors will appear as standard compilation failures, and you can check the generated build directories for more info.

Can I use cppimport in a Docker container for production?

Yes, but pre-compile modules using the CLI tool (python -m cppimport build) to avoid including compilers in the container. Set release_mode to skip checksum checks for faster startup, ensuring all binaries are present.

Is cppimport suitable for projects with many header dependencies?

cppimport can track dependencies via cfg['dependencies'] in the Mako block, but for many headers, the checksum system may still trigger full rebuilds, and manual management can become cumbersome compared to more advanced build systems.

cppimport — Import C++ Files in Python

What is cppimport?

cppimport is a Python library that allows developers to import C++ source files directly as Python modules, automatically handling compilation and binding via pybind11. It solves the problem of manual compilation steps in mixed Python/C++ workflows, enabling rapid iteration on performance-critical code.

Target Audience

Python developers who need to integrate C++ code for performance reasons, such as data scientists, engineers working on numerical computing, or anyone extending Python with native modules.

Value Proposition

Developers choose cppimport because it dramatically simplifies the development cycle for Python extensions, offering automatic recompilation, seamless integration with pybind11, and a configuration system that keeps build logic close to the source code.

Import C++ files directly from Python!

Use Cases

Best For

Quickly prototyping optimized C++ functions to speed up Python bottlenecks
Creating Python bindings for existing C++ libraries with minimal setup
Educational projects demonstrating C++/Python interop without complex build systems
Research code where iterative changes to both Python and C++ are common
Small to medium-sized extensions where a full CMake setup is overkill
Enabling transparent recompilation during development of mixed-language projects

Not Ideal For

Large projects with many source files requiring incremental compilation, as distutils lacks support and rebuilds can be slow
Windows development without pre-configured compilers like MinGW or Visual C++, due to limited CI testing and setup challenges
Teams needing build configurations separate from source code, since cppimport embeds Mako templates directly in C++ files
Applications requiring advanced build features like cross-compilation or custom toolchains, as cppimport relies on basic distutils

Pros & Cons

Pros

Seamless Edit-Test Workflow

Automatically compiles C++ on import, eliminating manual build steps and enabling rapid iteration, as shown in the quick example where importing triggers compilation.

Pybind11 Integration

Works seamlessly with pybind11 for creating Python bindings, making it straightforward to export C++ functions and classes, as demonstrated in the code snippets.

Transparent Recompilation

Uses checksums and dependency tracking to recompile only when sources change, ensuring up-to-date modules without unnecessary builds, as explained in the FAQ.

Concurrent Import Safety

Implements file locking to prevent race conditions during concurrent builds, making it safe for multi-process environments, with configurable timeouts.

Production Deployment Support

Includes a CLI tool to pre-compile modules for deployment, avoiding runtime compilation overhead, and allows release mode for faster startup.

Cons

No Incremental Compilation

Lacks support for incremental compilation in multi-file extensions due to distutils limitations, forcing full rebuilds that slow development for larger projects.

Platform-Specific Hurdles

Windows support is not fully tested in CI, requiring manual compiler setup and potentially breaking in environments without proper toolchains, as noted in the README.

Embedded Configuration Complexity

Requires Mako templating within C++ files for build settings, which can obscure code and increase the risk of errors from mixed logic and syntax.

Dependency on Legacy Distutils

Relies on Python's distutils, which is deprecated and may lack features for modern build scenarios, limiting flexibility and future compatibility.

Frequently Asked Questions

What is cppimport?

Target Audience

Python developers who need to integrate C++ code for performance reasons, such as data scientists, engineers working on numerical computing, or anyone extending Python with native modules.

Value Proposition

Use Cases

Best For

Quickly prototyping optimized C++ functions to speed up Python bottlenecks
Creating Python bindings for existing C++ libraries with minimal setup
Educational projects demonstrating C++/Python interop without complex build systems
Research code where iterative changes to both Python and C++ are common
Small to medium-sized extensions where a full CMake setup is overkill
Enabling transparent recompilation during development of mixed-language projects

Not Ideal For

Large projects with many source files requiring incremental compilation, as distutils lacks support and rebuilds can be slow
Windows development without pre-configured compilers like MinGW or Visual C++, due to limited CI testing and setup challenges
Teams needing build configurations separate from source code, since cppimport embeds Mako templates directly in C++ files
Applications requiring advanced build features like cross-compilation or custom toolchains, as cppimport relies on basic distutils

Pros & Cons

Pros

Seamless Edit-Test Workflow

Automatically compiles C++ on import, eliminating manual build steps and enabling rapid iteration, as shown in the quick example where importing triggers compilation.

Pybind11 Integration

Works seamlessly with pybind11 for creating Python bindings, making it straightforward to export C++ functions and classes, as demonstrated in the code snippets.

Transparent Recompilation

Uses checksums and dependency tracking to recompile only when sources change, ensuring up-to-date modules without unnecessary builds, as explained in the FAQ.

Concurrent Import Safety

Implements file locking to prevent race conditions during concurrent builds, making it safe for multi-process environments, with configurable timeouts.

Production Deployment Support

Includes a CLI tool to pre-compile modules for deployment, avoiding runtime compilation overhead, and allows release mode for faster startup.

Cons

No Incremental Compilation

Lacks support for incremental compilation in multi-file extensions due to distutils limitations, forcing full rebuilds that slow development for larger projects.

Platform-Specific Hurdles

Windows support is not fully tested in CI, requiring manual compiler setup and potentially breaking in environments without proper toolchains, as noted in the README.

Embedded Configuration Complexity

Requires Mako templating within C++ files for build settings, which can obscure code and increase the risk of errors from mixed logic and syntax.

Dependency on Legacy Distutils

Relies on Python's distutils, which is deprecated and may lack features for modern build scenarios, limiting flexibility and future compatibility.

Frequently Asked Questions

cppimport

What is cppimport?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

cppimport

What is cppimport?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?