{"id":3288,"library":"swig","title":"SWIG (Simplified Wrapper and Interface Generator)","description":"SWIG is a software development tool that facilitates connecting programs written in C and C++ with a variety of high-level programming languages, including Python. It works by generating 'wrapper' code that allows scripting languages to access underlying C/C++ code. The current version is 4.4.1, with releases focused on C/C++ standard improvements, expanded language support, and Python compatibility updates.","status":"active","version":"4.4.1","language":"en","source_language":"en","source_url":"https://github.com/swig/swig","tags":["C++","C","wrapper","binding","FFI","extension","code generation"],"install":[{"cmd":"pip install swig","lang":"bash","label":"Install SWIG (might build from source)"},{"cmd":"sudo apt-get install swig","lang":"bash","label":"Install SWIG on Debian/Ubuntu (recommended for the tool)"},{"cmd":"brew install swig","lang":"bash","label":"Install SWIG on macOS (recommended for the tool)"}],"dependencies":[],"imports":[{"note":"SWIG generates Python modules (e.g., `_example.so` and `example.py` from `example.i`) that are then imported. There is no central 'swig' module to import for core functionality; SWIG is a code generation tool.","symbol":"<module_name>","correct":"import <module_name>"}],"quickstart":{"code":"/* C/C++ file: example.h */\n#ifndef EXAMPLE_H\n#define EXAMPLE_H\n\nint fact(int n);\nint my_mod(int x, int y);\n\n#endif // EXAMPLE_H\n\n/* C/C++ file: example.c */\n#include \"example.h\"\n\nint fact(int n) {\n    if (n < 0) return 0; /* Or handle error appropriately */\n    if (n == 0) return 1;\n    return n * fact(n - 1);\n}\n\nint my_mod(int x, int y) {\n    if (y == 0) return 0; /* Or handle error appropriately */\n    return x % y;\n}\n\n/* SWIG interface file: example.i */\n%module example\n%{\n#define SWIG_FILE_WITH_INIT\n#include \"example.h\"\n%}\n\nint fact(int n);\nint my_mod(int x, int y);\n\n# Build and run steps in bash\n# 1. Generate SWIG wrapper code\n# swig -python -c++ example.i\n\n# 2. Compile C/C++ source and SWIG wrapper\n# g++ -c example.c example_wrap.cxx -I/usr/include/python3.10 -fPIC\n\n# 3. Link into a shared library\n# g++ -shared example.o example_wrap.o -o _example.so\n\n# Python usage:\nimport example\n\nprint(f\"Factorial of 5: {example.fact(5)}\")\nprint(f\"7 mod 3: {example.my_mod(7, 3)}\")","lang":"python","description":"This quickstart demonstrates the full SWIG workflow: defining C/C++ functions, creating a SWIG interface file (`.i`), using the `swig` command to generate Python wrapper code and a Python module file, compiling the C/C++ source with the generated wrapper, linking them into a shared library, and finally importing and using the module in Python. Note that the compilation commands (g++) are platform-dependent and assume a C++ compiler and Python development headers are installed."},"warnings":[{"fix":"Review your build system and generated wrapper code for compatibility with heap types and multi-phase initialization. If using `Py_LIMITED_API`, ensure compatibility, as fixes for combinations with recent Python versions were added in 4.4.1.","message":"SWIG 4.4.0 changed the default generation of static types to heap types and introduced multi-phase module initialization for modern Python wrappers. This might require adjustments in older build systems or specific configurations, especially for projects relying on specific Python C API internals.","severity":"breaking","affected_versions":"4.4.0+"},{"fix":"Avoid `from <module> import *` when dealing with multiple SWIG modules. Instead, use `import <module_name>` and access global variables via `<module_name>.cvar.<variable_name>`.","message":"When importing multiple SWIG-generated modules using `from <module> import *`, you might encounter a name clash on the special `cvar` object used to access global variables. This means only the `cvar` from the last loaded module will be accessible directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your compilation/linking step creates a shared library named `_<module_name>.so` (or `_<module_name>.pyd` on Windows) that matches the `%module` directive in your `.i` file.","message":"The generated Python shared library filename must precisely match the module name specified in the SWIG interface file (`%module <module_name>`), typically with a leading underscore (e.g., `_example.so` for `%module example`). A mismatch will lead to import errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Provide explicit definitions for opaque types (e.g., `typedef void* HWND;` in the interface file) or use custom typemaps to instruct SWIG on how to manage the memory for such pointers, for instance, by treating handles as integers.","message":"Memory leaks can occur when SWIG wraps C/C++ pointers to opaque types (e.g., `HWND*` on Windows) and doesn't find a corresponding destructor. SWIG treats them as raw pointers without proper memory management.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully ensure that C++ namespaces are correctly set in your SWIG interface file, especially when dealing with classes and callbacks that pass parameters by reference. This helps SWIG correctly map the C++ types to their Python representations.","message":"Issues can arise when C++ callbacks pass references to parameters that are then accessed in Python. The underlying C++ type might not correctly align with the Python instance, leading to errors when attempting to access methods of the referenced object in Python.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}