---
id: pyclang
version: "0.7.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pyclang — A python clang-tidy runner

License: permissive · Maintenance: active · Downloads: 489.6K/mo

## What it is and what it does

Pyclang is a Python wrapper around clang-tidy, the LLVM static analysis tool for C and C++. It provides a chainable API to orchestrate clang-tidy runs across directories, allowing you to compose analysis workflows programmatically—configure the build environment, filter files, run the analysis, and normalize results—without writing shell scripts. The package includes a built-in command-line script (idf_clang_tidy) for ESP-IDF projects that chains common steps automatically.

The core design centers on the Runner class: you instantiate it with a list of directories, chain method calls to define your analysis pipeline, then invoke the instance to execute all steps. You can also subclass Runner and use the @chain decorator to add custom analysis steps. It depends on esp-pylib for environment handling and rich for terminal output formatting.

Use it for:

- Automate clang-tidy analysis in CI/CD pipelines for C/C++ projects without writing shell wrappers
- Run static analysis on ESP-IDF projects using the predefined idf_clang_tidy script with standard workflow steps
- Build custom analysis workflows by chaining Runner methods to configure, filter, and normalize code quality checks
- Integrate clang-tidy into Python-based build systems or project management tools that need programmatic control

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Pyclang wraps clang-tidy to run static analysis checks on C/C++ code directories, with chainable methods for configuring analysis steps and a command-line interface for common workflows.

Yes, if you need to run clang-tidy from Python or automate it in a build pipeline. Low install friction, permissive license, no known vulnerabilities, and active maintenance make it a safe choice. Verify that clang-tidy itself is available on your system and that esp-pylib meets your environment requirements.

## Install

pip install pyclang
uv add pyclang
poetry add pyclang

## Installing pyclang

Before you install: Low install friction; pure Python wheel with only two runtime dependencies (esp-pylib and rich). Active maintenance with a release 32 days ago.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute this package freely provided you include the license notice.

Quickstart:

pip install pyclang

import os
from pyclang import Runner

runner = Runner(['/path/to/code'])
runner.idf_reconfigure().normalize()
runner()

Requires clang-tidy to be installed and available on the system PATH; typically part of LLVM/Clang toolchain.

Verify before relying:

- Whether clang-tidy version compatibility is documented or constrained
- Whether esp-pylib and rich are optional or always required at runtime
- Performance characteristics when analyzing large codebases

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 489.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

clang-tidy runner python, c++ static analysis automation, code quality checking wrapper, clang-tidy cli tool, idf project analysis, static-analysis, clang-tidy, build-automation

[View on SkillFed](https://skillfed.io/packages/pyclang) · [View on PyPI](https://pypi.org/project/pyclang/)