Install & Compatibility
Where this runs
tested against v22.1.0.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.920 runs
installs and imports cleanly · install 0.0s · import 0.016s · 172.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.6s · import 0.015s · 153MB
161MB installed
● package 161MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
No direct Python API
✓ import subprocess
# Or use: python -m clang_tidy
This library primarily provides the `clang-tidy` executable. It does not expose a Python API for programmatic access to clang-tidy's analysis functionality within Python code. Usage is via `subprocess` or by executing it as a Python module.
This quickstart demonstrates how to execute the `clang-tidy` command-line tool after installing the Python package. Since there's no direct Python API, you interact with `clang-tidy` using `subprocess` or by running it as a Python module. A common use case is to check its version or to run analysis on C++ code, which usually requires a `compile_commands.json` file generated by a build system like CMake.
import subprocess
import os
def run_clang_tidy(args):
try:
# Option 1: Using subprocess directly with the executable
# Requires 'clang-tidy' to be in PATH or specified with full path
# For this package, 'clang-tidy' should be in PATH after install
result = subprocess.run(['clang-tidy'] + args, capture_output=True, text=True, check=True)
print(f"Stdout:\n{result.stdout}")
if result.stderr:
print(f"Stderr:\n{result.stderr}")
return result.returncode
except FileNotFoundError:
print("Error: 'clang-tidy' command not found. Ensure the package is installed and accessible.")
return 1
except subprocess.CalledProcessError as e:
print(f"Error running clang-tidy: {e.returncode}")
print(f"Stdout:\n{e.stdout}")
print(f"Stderr:\n{e.stderr}")
return e.returncode
# Example 1: Check clang-tidy version
print("\n--- Running clang-tidy --version ---")
run_clang_tidy(['--version'])
# Example 2: Run clang-tidy as a Python module (alternative)
# This is often more reliable in environments where PATH might be tricky
def run_clang_tidy_module(args):
try:
# Ensure the script running this has access to the python executable
# that installed clang-tidy.
result = subprocess.run(['python', '-m', 'clang_tidy'] + args, capture_output=True, text=True, check=True)
print(f"Stdout:\n{result.stdout}")
if result.stderr:
print(f"Stderr:\n{result.stderr}")
return result.returncode
except FileNotFoundError:
print("Error: 'python' command not found, or module path issue.")
return 1
except subprocess.CalledProcessError as e:
print(f"Error running clang-tidy via module: {e.returncode}")
print(f"Stdout:\n{e.stdout}")
print(f"Stderr:\n{e.stderr}")
return e.returncode
print("\n--- Running clang-tidy via 'python -m clang_tidy --version' ---")
run_clang_tidy_module(['--version'])
# To run actual analysis, you typically need a 'compile_commands.json'
# This example is illustrative and won't work without a compiled C++ project.
# For example:
# if os.path.exists('compile_commands.json'):
# print("\n--- Running clang-tidy on a C++ file (illustrative) ---")
# run_clang_tidy(['my_source.cpp', '-p', '.'])
# else:
# print("\nSkipping C++ file analysis: 'compile_commands.json' not found.")
clang-tidy --version
Errors
Common errors & fixes
clang-tidy: command not found
The `clang-tidy` executable is not in your system's PATH, or the pip installation failed to link it correctly.
fixEnsure `pip install clang-tidy` completed successfully. If using a virtual environment, ensure it's activated. Alternatively, invoke the tool using `python -m clang_tidy` which directly calls the installed Python module.
Error: no input files
You ran `clang-tidy` without specifying any C++ source files to analyze.
fixProvide one or more C++ source files as arguments (e.g., `clang-tidy my_file.cpp`). For a whole project, use a compilation database and target files: `clang-tidy path/to/source.cpp -p path/to/build_dir`.
No compilation database found in directory [directory path]
Clang-tidy requires a `compile_commands.json` file to understand how to build and analyze your C++ project, and it couldn't find one in the current directory or the specified path.
fixGenerate `compile_commands.json` using your build system (e.g., CMake, Meson, etc.). Place it in your project's build directory or root, and then call `clang-tidy -p <path_to_directory_containing_compile_commands.json>`.
Upgrade
Version history
22.1.0.1latest on PyPI · released Mar 30, 2026
Audit
Dependencies
No dependency data recorded yet.