Install & Compatibility
Where this runs
tested against v18.1.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.036s · 79.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.042s · 79MB
77MB installed
● package 77MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Index
✓ from clang.cindex import Index
✗ from libclang import Index
The primary API is exposed through the 'clang.cindex' module, not 'libclang' directly.
CursorKind
✓ from clang.cindex import CursorKind
Config
✓ from clang.cindex import Config
✗ from clang import Config
Configuration utilities are part of the 'cindex' submodule.
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.
from clang.cindex import Index, TranslationUnit
# Source code to parse
source_code = """
#include <stdio.h>
int add(int a, int b) {
return a + b;
}
int main() {
printf("Sum: %d\n", add(5, 3));
return 0;
}
"""
# Create an index
index = Index.create()
# Parse the source code from a string. For files, use Index.parse('path/to/file.c')
tu = index.parse('test.c', unsaved_files=[('test.c', source_code)])
# Check for diagnostics (errors/warnings)
for diagnostic in tu.diagnostics:
print(f"Diagnostic: {diagnostic}")
# Iterate through the AST to find functions
print("\nFunctions found:")
for cursor in tu.cursor.get_children():
if cursor.kind == TranslationUnit.CursorKind.FUNCTION_DECL:
print(f" Function: {cursor.spelling}, return type: {cursor.result_type.spelling}")
for arg in cursor.get_arguments():
print(f" Argument: {arg.spelling}, type: {arg.type.spelling}")
print("\nFirst 10 tokens:")
for token in tu.get_tokens(extent=tu.cursor.extent)[:10]:
print(f" Token: '{token.spelling}' (kind: {token.kind})")
Debug
Known issues
gotchaShared 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).fixManually 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. affects: All versions
breakingAPI 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.fixConsult 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.
affects: All major version upgrades (e.g., 17.x -> 18.x)
breakingThe `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.fixEnsure you are using Python 3.6 or newer. Older versions might have limited or no compatibility.
affects: Versions 13.0.0 and newer
gotchaPerformance considerations when parsing large codebases. Creating an `Index` and `TranslationUnit` can be resource-intensive, and traversing large ASTs can be slow.fixFor 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.
affects: All versions
Errors
Common errors & fixes
clang.cindex.LibclangError: libclang.dll: cannot open shared object file: No such file or directory
The Python `libclang` bindings cannot locate the underlying `libclang` shared library (`.dll` on Windows, `.so` on Linux, `.dylib` on macOS) on your system path. This often happens if LLVM/Clang is not installed, or its installation path is not configured for `libclang` to find it.
fixEnsure LLVM/Clang is installed on your system. Then, explicitly set the path to the `libclang` shared library using `clang.cindex.Config.set_library_file('/path/to/libclang.dll')` (or `.so`/`.dylib`), or add the directory containing `libclang` to your system's PATH (Windows) or LD_LIBRARY_PATH (Linux/macOS) environment variable. ModuleNotFoundError: No module named 'clang.cindex'
The Python `libclang` package, which provides the `clang.cindex` module, is not installed in your Python environment or is not accessible on your PYTHONPATH.
fixInstall the `libclang` Python package using pip: `pip install libclang`. Note that the package name on PyPI is `libclang`, not `clang`.
clang.cindex.LibclangError: /usr/lib/x86_64-linux-gnu/libclang-X.Y.so.1: undefined symbol: clang_CXXRecord_isAbstract
This error typically indicates a version mismatch between the installed `libclang` Python bindings and the underlying `libclang` shared library. The Python bindings were compiled or expect functions from a different version of `libclang` than what is currently available on your system.
fixEnsure that the version of the `libclang` Python package you have installed is compatible with the version of the LLVM/Clang shared library installed on your system. This might involve updating or downgrading either the Python package (`pip install libclang==X.Y.Z`) or your system's LLVM/Clang installation. For system-wide installations, ensure `libclang-dev` or equivalent packages match your Python binding's expected version.
Upgrade
Version history
18.1.1latest on PyPI · released Jun 30, 2024
Audit
Dependencies
No dependency data recorded yet.