{"id":1533,"library":"libclang","title":"libclang Python Bindings","description":"libclang provides Python bindings for Clang, the LLVM project's C, C++, and Objective-C compiler front-end. It allows programmatic access to Clang's AST (Abstract Syntax Tree), diagnostics, and other compiler functionalities. The `libclang` PyPI package, currently at version 18.1.1, mirrors the official LLVM project's Python bindings to simplify installation and is released in sync with major LLVM versions.","status":"active","version":"18.1.1","language":"en","source_language":"en","source_url":"https://github.com/sighingnow/libclang","tags":["llvm","clang","compiler","bindings","c++","c","ast","static analysis"],"install":[{"cmd":"pip install libclang","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary API is exposed through the 'clang.cindex' module, not 'libclang' directly.","wrong":"from libclang import Index","symbol":"Index","correct":"from clang.cindex import Index"},{"symbol":"CursorKind","correct":"from clang.cindex import CursorKind"},{"note":"Configuration utilities are part of the 'cindex' submodule.","wrong":"from clang import Config","symbol":"Config","correct":"from clang.cindex import Config"}],"quickstart":{"code":"from clang.cindex import Index, TranslationUnit\n\n# Source code to parse\nsource_code = \"\"\"\n#include <stdio.h>\n\nint add(int a, int b) {\n    return a + b;\n}\n\nint main() {\n    printf(\"Sum: %d\\n\", add(5, 3));\n    return 0;\n}\n\"\"\"\n\n# Create an index\nindex = Index.create()\n\n# Parse the source code from a string. For files, use Index.parse('path/to/file.c')\ntu = index.parse('test.c', unsaved_files=[('test.c', source_code)])\n\n# Check for diagnostics (errors/warnings)\nfor diagnostic in tu.diagnostics:\n    print(f\"Diagnostic: {diagnostic}\")\n\n# Iterate through the AST to find functions\nprint(\"\\nFunctions found:\")\nfor cursor in tu.cursor.get_children():\n    if cursor.kind == TranslationUnit.CursorKind.FUNCTION_DECL:\n        print(f\"  Function: {cursor.spelling}, return type: {cursor.result_type.spelling}\")\n        for arg in cursor.get_arguments():\n            print(f\"    Argument: {arg.spelling}, type: {arg.type.spelling}\")\n\nprint(\"\\nFirst 10 tokens:\")\nfor token in tu.get_tokens(extent=tu.cursor.extent)[:10]:\n    print(f\"  Token: '{token.spelling}' (kind: {token.kind})\")","lang":"python","description":"This quickstart demonstrates how to parse C/C++ code, check for diagnostics, iterate through the Abstract Syntax Tree (AST) to find function declarations and their arguments, and access tokens. When installed via the official `libclang` wheel, the library attempts to automatically locate the necessary `libclang` shared library, making manual configuration via `Config.set_library_file()` often unnecessary."},"warnings":[{"fix":"Manually specify the path to your `libclang` shared library (e.g., `libclang.so`, `libclang.dll`, `libclang.dylib`) using `from clang.cindex import Config; Config.set_library_file('/path/to/libclang.so')` or `Config.set_library_path('/path/to/llvm/lib')` before any other `clang.cindex` calls. Ensure the path points to the correct LLVM version.","message":"Shared Library Not Found (`SharedLibraryNotFound`) is the most common error. While the `libclang` PyPI package attempts to auto-configure the library path when installed via wheels, this can fail in custom environments (e.g., development setups, using a system-installed LLVM, or manual Python installations).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the official LLVM Clang C API documentation for the specific version you are targeting. Review the `llvm-project/clang/bindings/python` directory in the LLVM source for changes relevant to the Python bindings.","message":"API changes in the underlying Clang C API are directly reflected in the `libclang` Python bindings. Upgrading to a new major `libclang` version (e.g., from 17.x to 18.x) may introduce breaking changes in function signatures, enum values, or object structures.","severity":"breaking","affected_versions":"All major version upgrades (e.g., 17.x -> 18.x)"},{"fix":"Ensure you are using Python 3.6 or newer. Older versions might have limited or no compatibility.","message":"The `libclang` Python bindings are primarily designed for Python 3. Support for Python 2.x has been dropped in recent LLVM versions, and wheels for older Python versions are no longer provided.","severity":"breaking","affected_versions":"Versions 13.0.0 and newer"},{"fix":"For incremental changes, use `TranslationUnit.reparse()` rather than parsing the entire file again. Consider using `Index.parse()` with `options` to reduce the amount of information stored (e.g., `TranslationUnit.PARSE_SKIP_FUNCTION_BODIES`). Profile your application to identify bottlenecks during AST traversal.","message":"Performance considerations when parsing large codebases. Creating an `Index` and `TranslationUnit` can be resource-intensive, and traversing large ASTs can be slow.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}