Registry / devops / clang
library21.1.7pypypi✓ verified 27d ago

The `clang` package provides Python bindings for libclang, enabling programmatic interaction with Clang's C/C++/Objective-C abstract syntax trees (ASTs), parsing source code, and accessing compiler information. It is maintained as part of the broader LLVM project and typically releases in sync with major LLVM versions. The current version is 21.1.7.

pip install clang
INSTALL
IMPORT
SIG · CLANG
C
clang
devopspythonv21.1.7
Install
1.6s avg
Import
52ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v21.1.7 · 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
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.050s · 18.1MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.054s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Index
✓ from clang.cindex import Index
Config
✓ from clang.cindex import Config
Cursor
✓ from clang.cindex import Cursor
TranslationUnit
✓ from clang.cindex import TranslationUnit

This quickstart demonstrates how to parse C code from a string, check for diagnostics, and traverse the Abstract Syntax Tree (AST) using `clang.cindex`. The most critical step is ensuring that the underlying `libclang` shared library is installed on your system and discoverable by the Python bindings.

import os from clang.cindex import Index, Config, TranslationUnit # type: ignore # CRITICAL: Ensure libclang (the C++ library) is installed and discoverable. # The 'clang' pip package only provides Python wrappers. # # On macOS (with Homebrew LLVM): # Config.set_library_path('/usr/local/opt/llvm/lib') # On Linux (e.g., Ubuntu/Debian LLVM-18): # Config.set_library_path('/usr/lib/llvm-18/lib') # On Windows, ensure 'libclang.dll' is in your PATH or set its full path. # Alternatively, set the CLANG_LIBRARY_PATH environment variable. source_code = """ #include <stdio.h> int add(int a, int b) { return a + b; } int main() { printf("Hello from Clang AST!"); int result = add(5, 7); return 0; } """ try: index = Index.create() # Parse the source code from a string. 'main.c' is a dummy name. # args can include compiler flags, e.g., ['-std=c99', '-I/path/to/includes'] tu = index.parse('main.c', unsaved_files=[('main.c', source_code)], args=['-x', 'c']) # Check for diagnostics (errors, warnings) during parsing if tu.diagnostics: for diag in tu.diagnostics: if diag.severity >= 3: # Error or Fatal print(f"Diagnostic (Error): {diag.spelling} at {diag.location}") # Walk the AST and print top-level declarations print("\nTop-level declarations:") for cursor in tu.cursor.get_children(): if cursor.location.file and cursor.location.file.name == 'main.c': print(f"- {cursor.kind.name}: {cursor.spelling} at Line {cursor.location.line}") # Example: Finding the 'main' function and its call to 'add' for cursor in tu.cursor.walk_preorder(): if cursor.kind.is_function() and cursor.spelling == 'main': print(f"\nFound 'main' function at Line {cursor.location.line}") for child in cursor.get_children(): if child.kind.is_call_expr() and child.spelling == 'add': print(f" -> 'main' calls 'add' at Line {child.location.line}") break except Exception as e: print(f"An error occurred: {e}") print("Hint: Make sure libclang is installed on your system and its path is correctly configured.")
Debug
Known issues
gotchaThe `clang` PyPI package provides Python bindings ONLY. It does NOT include the `libclang` C++ shared library, which is a fundamental dependency. You must install `libclang` separately on your operating system.
fix
Install `libclang` via your system's package manager (e.g., `apt install libclang-dev` on Debian/Ubuntu, `brew install llvm` on macOS, or LLVM installer on Windows) before running Python code.
affects: All versions
gotchaAfter installing `libclang`, the Python bindings might not find it automatically. You may need to explicitly tell the bindings where to find `libclang.so` (Linux), `libclang.dylib` (macOS), or `libclang.dll` (Windows).
fix
Set the `CLANG_LIBRARY_PATH` environment variable to the directory containing `libclang` before running your Python script, or call `clang.cindex.Config.set_library_path('/path/to/libclang/directory')` in your code.
affects: All versions
gotchaThere can be compatibility issues if the version of the `clang` Python package does not match the version of the system `libclang` installed. Mismatches can lead to crashes, incorrect parsing, or unexpected behavior.
fix
Try to keep the Python `clang` package version in sync with your system's `libclang` version. For example, `pip install 'clang==18.*'` if you have LLVM 18 installed. Downgrade/upgrade `libclang` or the Python bindings if problems persist.
affects: All versions
breakingThe `clang.cindex` API, being a binding to a C++ library, can have subtle breaking changes between major LLVM versions (e.g., how AST nodes are iterated, new cursor kinds, or changes in diagnostic information structure).
fix
Always refer to the official LLVM `libclang` Python binding documentation or examples corresponding to your LLVM version when upgrading. Test thoroughly after upgrading major versions.
affects: Major version bumps (e.g., 17.x to 18.x)
gotchaCorrectly configuring compiler arguments (e.g., include paths, language standard, preprocessor definitions) is crucial for accurate parsing of C/C++ source code, especially for complex projects.
fix
Pass all necessary compiler flags (e.g., `-I`, `-D`, `-std=c++17`, `-x c++`) as a list of strings to the `args` parameter of `index.parse()`.
affects: All versions
Errors
Common errors & fixes
LibclangError: libclang.so: cannot open shared object file: No such file or directory.
The Python `clang` bindings cannot locate the `libclang` shared library, which is a core dependency. This can be due to `libclang` not being installed, not being in the system's dynamic library path (LD_LIBRARY_PATH on Linux, PATH on Windows, DYLD_LIBRARY_PATH on macOS), or an architectural mismatch (32-bit vs. 64-bit) between Python and libclang. (The error might also show as 'Could not find module 'libclang.dll'' on Windows or '.dylib' on macOS).
fix
Ensure the LLVM/Clang development packages are installed (e.g., `apt-get install libclang-dev` on Debian/Ubuntu, `brew install llvm` on macOS). Explicitly set the path to the library in your Python script: `from clang.cindex import Config; Config.set_library_file('/path/to/libclang.so')` (or `.dll`/`.dylib` as appropriate). If you installed `libclang` via pip, verify its installation and check the package documentation for specific setup instructions if the automatic discovery fails.
ModuleNotFoundError: No module named 'clang.cindex'
The `clang` Python package or its `cindex` submodule is not found by the Python interpreter. This typically indicates that the package was not installed correctly or installed into a Python environment that is not currently active.
fix
Install the `clang` package using pip: `pip install clang`. If you are using a virtual environment, ensure it is activated. Verify that the Python interpreter you are running is the one where the package was installed.
AttributeError: 'Cursor' object has no attribute 'get_children'
This error occurs when attempting to access `get_children` in a way that is inconsistent with the `clang` Python bindings' API, or when the `Cursor` object does not have children (e.g., for certain kinds of AST nodes or due to parsing issues with complex C++ constructs like template instantiations). The Python bindings typically provide children via iteration, not direct method calls for 'get_children' as a function. It can also sometimes be related to Python 2 vs. Python 3 compatibility in older versions of the bindings.
fix
Access children by iterating over the `Cursor` object itself, or by calling `get_children()` as an iterator. For example: `for child in cursor.get_children():`. Ensure you are using a Python 3 compatible version of the `clang` bindings, as some older versions had compatibility issues.
Upgrade
Version history
21.1.7latest on PyPI · released Dec 18, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
40 hits · last 30 days
node
36
Anthropic
1
OpenAI (training)
1
Resources