clangd-tidy

What it is and what it does

clangd-tidy is a Python wrapper around clangd that performs static analysis on C++ code faster than the standalone clang-tidy tool. It acts as a drop-in replacement, accepting similar command-line arguments and integrating with existing build systems and CI pipelines. The speed improvement comes from clangd's architecture: it builds abstract syntax trees only from the files being checked, rather than processing all included headers as clang-tidy does.

The package depends on attrs, cattrs, and typing-extensions for its Python runtime, and requires clangd to be installed separately on the system. It supports features like code formatting checks via clang-format integration, `.clangd` configuration files for advanced diagnostics (such as include checks), line-based filtering of results, and output formatting for GitHub Actions. Some clang-tidy features like the `--fix` option are not supported, and a small number of checks are silently disabled because clangd does not implement them.

Use it for:

• Speed up C++ static analysis in CI/CD pipelines where clang-tidy execution time is a bottleneck.
• Check header files individually without requiring them to be in the compilation database.
• Combine static analysis and code formatting checks in a single tool to reduce separate tool invocations.
• Leverage clangd's `.clangd` configuration for advanced diagnostics like unused-include and missing-include checks.
• Integrate with GitHub Actions workflows to report diagnostics with hyperlinked check names in supported terminals.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

clangd-tidy wraps clangd to provide faster static analysis of C++ code as a drop-in replacement for clang-tidy, leveraging clangd's speed while maintaining compatibility with existing build systems and CI scripts.

Yes, with conditions. Install if you have a C++ codebase where clang-tidy runtime is a CI bottleneck and you can accept that some clang-tidy features (like `--fix`) and a small set of checks are unavailable. Requires clangd to be pre-installed on your system. No security vulnerabilities are known, maintenance is active, and the permissive license poses no restrictions.

Install

clangd-tidy on PyPI

pip install clangd-tidy

uv add clangd-tidy

poetry add clangd-tidy

Installing clangd-tidy

Before you install

Low install friction: pure Python wheel with only three lightweight runtime dependencies (attrs, cattrs, typing-extensions). Actively maintained with recent releases; however, requires clangd to be installed separately on the system.

License in practice

Licensed under permissive terms (MIT), placing no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

pip install clangd-tidy

clangd-tidy -p build file.cpp
# or with formatting check:
clangd-tidy -f -p build file.cpp

clangd must be installed and available on the system PATH; Python 3.8 or later required.

Verify before relying

• Whether clangd-tidy's 'over 10x' speed claim is reproducible on typical codebases and hardware.
• Scope and impact of the several checks that clangd silently disables compared to standalone clang-tidy.
• Practical differences in diagnostic output aesthetics and whether they affect CI/CD workflows.
• Whether the optional tqdm dependency is automatically installed or must be added manually for progress bars.

Package facts

Evidence: clangd_tidy-1.1.1-py3-none-any.whl

Keywords: clang-tidy, clangd, static-analysis, cpp

Tags

More Quality Assurance packages