py4u blog

Wrapping C/C++ for Python using SWIG - Set 1: The Fundamentals

When performance is critical, or when you need to leverage existing C/C++ libraries, combining the power of these languages with the flexibility of Python can be a game-changer. The Simplified Wrapper and Interface Generator (SWIG) is a powerful tool that automates the process of connecting C/C++ code with high-level languages like Python. It reads C/C++ header files and generates the "glue" code needed for the languages to communicate.

This blog post is the first in a series that will guide you through using SWIG to create Python extensions. We'll cover the fundamental concepts, from a basic "Hello World" example to handling simple data types and functions. By the end of this post, you will be able to wrap a basic C library and use it seamlessly from your Python code.

2026-10

Table of Contents#

  1. What is SWIG?
  2. Installation and Setup
  3. A Simple Example: hello_world
    1. The C Source Code
    2. The Interface File
    3. Generating the Wrapper
    4. Building the Extension Module
    5. Testing in Python
  4. Understanding the Build Process
  5. Wrapping Functions and Basic Data Types
    1. Integer Types
    2. Floating-Point Types
    3. Example: A Simple Math Library
  6. Best Practices and Common Pitfalls
  7. Conclusion
  8. References

What is SWIG?#

SWIG is a compiler that integrates C and C++ with languages including Python, Perl, Ruby, Tcl, Java, and more. It works by taking an interface file (usually with a .i extension) that specifies the C/C++ functions, variables, classes, and constants you want to expose. SWIG then generates the necessary wrapper code—a C/C++ file that contains a lot of boilerplate code for converting data types between the target language and C/C++ (a process called "type marshalling") and interfacing with the Python/C API.

The primary advantage of SWIG is its automation. Writing Python extensions by hand using the Python/C API is complex and error-prone. SWIG handles the vast majority of this complexity for you.

Installation and Setup#

The easiest way to install SWIG is through your system's package manager or from the official website.

On Ubuntu/Debian:

sudo apt-get install swig

On macOS (using Homebrew):

brew install swig

On Windows: Download the precompiled binary from the SWIG website and add it to your system's PATH.

You will also need a C/C++ compiler (like gcc or clang) and Python development headers (python3-dev or similar).

Verify the installation:

swig -version

A Simple Example: hello_world#

Let's walk through the classic "Hello World" example to understand the core components of a SWIG project.

1. The C Source Code#

First, we create a simple C file, hello.c.

// hello.c
#include <stdio.h>
 
void say_hello(const char* name) {
    printf("Hello, %s!\n", name);
}
 
int count = 0;
 
int increment() {
    count++;
    return count;
}

2. The Interface File#

This is the most important file for SWIG. It tells SWIG what to wrap. Create hello.i.

/* hello.i */
%module hello
 
%{
/* This block gets inserted into the generated wrapper code.
   Use it to include header files or declarations needed for compilation. */
#include "hello.h" // We'll create this next
%}
 
/* Tell SWIG to wrap these declarations. */
extern void say_hello(const char* name);
extern int count;
extern int increment();

We also need a header file hello.h for the %{ ... %} block to include.

// hello.h
void say_hello(const char* name);
extern int count;
int increment();

Best Practice: While you can put C code directly in the interface file, it's cleaner to separate the implementation (hello.c) from the declarations (hello.h) and have the interface file (hello.i) include the header. This mirrors standard C/C++ development.

3. Generating the Wrapper#

Run SWIG with the -python option to generate wrappers for Python.

swig -python hello.i

This command produces two new files:

  • hello_wrap.c: A massive C file containing all the wrapper code.
  • hello.py: A Python module that imports the compiled C extension and provides a Pythonic interface.

4. Building the Extension Module#

Now we need to compile the original C code (hello.c) and the generated wrapper code (hello_wrap.c) into a shared library that Python can import. The output file name is critical: it must start with _ and match the module name specified in the %module directive. In our case, the final shared object should be _hello.so (or _hello.pyd on Windows).

We can use a setup.py script with distutils or setuptools to simplify this process, which also handles platform-specific details.

# setup.py
from distutils.core import setup, Extension
 
# Create an Extension module object.
hello_module = Extension(
    '_hello',           # Name of the module, must start with '_'
    sources=['hello_wrap.c', 'hello.c'], # Source files to compile
)
 
setup(
    name='hello',
    version='0.1',
    author='Your Name',
    description='Simple SWIG example',
    ext_modules=[hello_module],
    py_modules=['hello'], # The pure Python module generated by SWIG
)

Build the module by running:

python setup.py build_ext --inplace

The --inplace flag tells the build system to place the output extension (e.g., _hello.so) in the current directory.

5. Testing in Python#

Now, you can use your C module just like any other Python module!

# test_hello.py
import hello
 
hello.say_hello("SWIG Developer")  # Output: Hello, SWIG Developer!
 
print(f"Initial count: {hello.count}") # Output: Initial count: 0
 
hello.increment()
hello.increment()
print(f"Count after incrementing twice: {hello.count}") # Output: Count after incrementing twice: 2
 
# We can also modify the variable directly from Python!
hello.count = 10
print(f"Count after direct assignment: {hello.count}") # Output: Count after direct assignment: 10

Understanding the Build Process#

The entire process can be visualized as follows:

[hello.c & hello.h]      [hello.i]
        \                    /
         \                  /
          swig -python hello.i
                    |
         [hello_wrap.c] [hello.py]
                    |
         python setup.py build_ext --inplace
                    |
                [_hello.so]
  1. Inputs: Your C/C++ code and the SWIG interface file.
  2. SWIG Processing: Generates the wrapper code (hello_wrap.c) and a Python helper file (hello.py).
  3. Compilation: The C compiler builds hello.c and hello_wrap.c into a shared object file (_hello.so).
  4. Runtime: When you import hello in Python, it loads hello.py, which in turn imports the _hello native module.

Wrapping Functions and Basic Data Types#

SWIG handles basic C data types automatically by converting them to and from corresponding Python types.

Integer Types#

  • int, short, long -> Python int
  • unsigned versions -> Python int (values are promoted as needed)

Floating-Point Types#

  • float, double -> Python float

Example: A Simple Math Library#

Let's create a more practical example with a small math library.

mathlib.h

#ifndef MATHLIB_H
#define MATHLIB_H
 
// Returns the greatest common divisor of two integers
int gcd(int a, int b);
 
// Calculates the volume of a cylinder: PI * radius^2 * height
double cylinder_volume(double radius, double height);
 
#endif

mathlib.c

#include "mathlib.h"
 
int gcd(int a, int b) {
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}
 
double cylinder_volume(double radius, double height) {
    const double PI = 3.14159265358979323846;
    return PI * radius * radius * height;
}

mathlib.i

%module mathlib
%{
#include "mathlib.h"
%}
 
%include "mathlib.h"

Notice we use %include "mathlib.h" instead of listing each function. This is a common practice to avoid duplication. SWIG will parse the header file and wrap everything it finds.

Build and Test:

swig -python mathlib.i
python setup.py build_ext --inplace
# Ensure your setup.py is updated for the 'mathlib' module
import mathlib
 
print(f"GCD of 48 and 18 is: {mathlib.gcd(48, 18)}") # Output: 6
 
vol = mathlib.cylinder_volume(3.0, 5.0)
print(f"Volume of cylinder (r=3, h=5) is: {vol:.2f}") # Output: ~141.37

Best Practices and Common Pitfalls#

  1. Start Simple: Begin with a minimal example to verify your toolchain works before moving to complex code.
  2. Use Interface Files Effectively:
    • Use %include for header files to keep the interface file in sync with your C/C++ code.
    • The %{ ... %} block is for code that must appear in the wrapper before the SWIG-generated declarations. Use it for #include directives and other essential code.
  3. Manage the Build: Use setup.py or a build system like CMake instead of manual compiler commands. It's more portable and reliable.
  4. Module Naming is Critical: The compiled shared library must be named _<module>.so (or .pyd). If Python cannot find it, you'll get an ImportError.
  5. Beware of Global Variables: As shown in the first example, SWIG provides access to global C variables. However, this can be dangerous if the variable is modified from multiple places (C and Python). Use with caution.
  6. Check SWIG Output: If you encounter strange errors, look at the generated _wrap.c file. It can be large, but searching for the function you're trying to call can provide clues.

Conclusion#

In this first part of the series, we've covered the foundational steps of using SWIG to create Python bindings for C code. We've seen how to create an interface file, generate wrapper code, build a Python extension module, and call simple functions from Python. SWIG successfully automates the tedious task of writing boilerplate code for data type conversion.

In the next set, we will dive into more advanced topics, such as handling pointers, arrays, structures, and memory management, which are crucial for wrapping real-world C/C++ libraries.

References#

  1. SWIG Official Documentation: http://www.swig.org/doc.html - The ultimate resource, especially the "SWIG and Python" chapter.
  2. Python Distutils Documentation: https://docs.python.org/3/extending/building.html - Official guide for building C/C++ extensions.
  3. GitHub Repository with Examples: https://github.com/swig/swig/tree/master/Examples - A vast collection of examples for various languages and use cases.