---
id: clangd-tidy
version: "1.1.1"
license: unclear
license_treatment: permissive
maintenance: active
---

# clangd-tidy — A faster alternative to clang-tidy

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

## 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 above — 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

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

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

## Tags

fast c++ static analysis, clang-tidy alternative, clangd wrapper, c++ code linting, faster static analysis, clang diagnostics, c++ quality checks, c++-tooling, static-analysis, ci-cd

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