{"id":9632,"library":"ctypesgen","title":"ctypesgen","description":"ctypesgen is a Python wrapper generator for `ctypes`, designed to automate the creation of Python bindings for C header files. It parses C/C++ header files and generates Python modules that use the `ctypes` foreign function interface to call functions and access data structures in shared C libraries. The current version is 1.1.1, with releases occurring periodically to address bugs and introduce new features, often yearly or bi-annually.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/ctypesgen/ctypesgen","tags":["ctypes","FFI","C","bindings","code generation","wrapper"],"install":[{"cmd":"pip install ctypesgen","lang":"bash","label":"Install ctypesgen"}],"dependencies":[{"reason":"Used for parsing C header files (lexer/parser generator).","package":"ply","optional":false}],"imports":[{"note":"The primary programmatic entry point is `ctypesgen.main.main()`, which takes a list of command-line arguments.","wrong":"import ctypesgen","symbol":"main","correct":"import ctypesgen.main"}],"quickstart":{"code":"import os\nimport ctypesgen.main\n\n# 1. Define your C header content\nheader_content = \"\"\"\n// my_library.h\n#ifndef MY_LIBRARY_H\n#define MY_LIBRARY_H\n\nint add_numbers(int a, int b);\nvoid print_message(const char* msg);\n\n#endif\n\"\"\"\n\n# 2. Create a temporary header file\nheader_file = \"my_library.h\"\nwith open(header_file, \"w\") as f:\n    f.write(header_content)\n\n# 3. Define the output Python bindings file\noutput_file = \"my_library_bindings.py\"\n\n# 4. Run ctypesgen programmatically using its main function\n# Arguments are passed as a list of strings, just like command-line arguments.\nctypesgen.main.main([\"-o\", output_file, header_file])\n\nprint(f\"Successfully generated bindings to '{output_file}'\")\nprint(\"To use them, compile 'my_library.h' into a shared library (e.g., .so, .dylib, .dll),\\n\"+\n      \"then import 'my_library_bindings' in Python and load the shared library.\")\n\n# 5. Clean up temporary files\nos.remove(header_file)\n","lang":"python","description":"This quickstart demonstrates how to use `ctypesgen` programmatically to generate Python bindings for a simple C header file. It creates a dummy header, invokes `ctypesgen.main.main` with appropriate arguments to create a Python file, and then prints instructions for how to use the generated bindings (which requires compiling the C code into a shared library)."},"warnings":[{"fix":"Upgrade to Python 3.7+ or use ctypesgen<1.1.0 for Python 2 projects.","message":"Python 2 support was completely dropped in version 1.1.0. Older projects relying on ctypesgen with Python 2 must remain on a pre-1.1.0 version or migrate to Python 3.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Ensure a C/C++ compiler is installed and accessible via your system's PATH. On Linux, install `build-essential`. On macOS, install Xcode Command Line Tools (`xcode-select --install`). On Windows, install MinGW or MSVC.","message":"`ctypesgen` relies on an underlying C compiler (like `gcc` or `clang`) being present in your system's PATH to parse C header files. If not found, it will fail to process headers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pass arguments as a list: `ctypesgen.main.main(['-o', 'output.py', 'input.h'])`.","message":"When using `ctypesgen.main.main()` programmatically, arguments must be passed as a single list of strings, mimicking `sys.argv[1:]`. Passing them as separate arguments will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `--no-embed-preamble` to your ctypesgen arguments for separate preamble/loader files, then import them as needed.","message":"By default, `ctypesgen` embeds a preamble (library loader code) in each generated output file. For packaging or reducing duplication, use `--no-embed-preamble` to generate the preamble and loader into separate files.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `ctypesgen` correctly using `pip install ctypesgen` or manually `pip install ply`.","cause":"The `ply` package is a mandatory dependency for `ctypesgen` to parse C header files, but it was not installed.","error":"ModuleNotFoundError: No module named 'ply'"},{"fix":"Install a C/C++ compiler (e.g., `build-essential` on Debian/Ubuntu, Xcode Command Line Tools on macOS, or MinGW/MSVC on Windows) and ensure it's added to your system's PATH.","cause":"ctypesgen uses an external C compiler (like `gcc` or `clang`) to preprocess and parse C header files. This error indicates that the compiler is not found in the system's PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'gcc'"},{"fix":"Pass all arguments as a single list: `ctypesgen.main.main(['-o', 'output.py', 'input.h'])`.","cause":"When calling `ctypesgen.main.main()`, command-line arguments are expected as a single list of strings, not separate arguments.","error":"TypeError: main() takes 1 positional argument but 2 were given"}]}