clang-tidier

A simple clang-tidy runner for C and C++ projects.

Installation

clang-tidier requires Python 3.9 or higher, as well as some version of clang-tidy visible on the system PATH.

pip3 install clang-tidier

Usage

clang-tidier is a command-line application

usage: clang-tidier [-h] [--version] [--include <regex> [<regex> ...]] [--exclude <regex> [<regex> ...]] [--werror]
                    [--threads <num>] [--batch num/denom] [--session | --no-session]
                    [--relative-paths | --no-relative-paths] [--external | --no-external] [--pch | --no-pch]
                    [--fix | --no-fix] [--plugins <path...> [<path...> ...]]
                    [compile_db_path]

clang-tidy runner for C and C++ projects.

positional arguments:
  compile_db_path       path to compile_commands.json, or a directory containing it (default: discover automatically)

options:
  -h, --help            show this help message and exit
  --version             print the version and exit
  --include <regex> [<regex> ...]
                        regular expression to select source files.
  --exclude <regex> [<regex> ...]
                        regular expression to exclude source files.
  --werror              stop on the first file that emits warnings
  --threads <num>       number of threads to use.
  --batch num/denom     batch subdivisions.
  --session, --no-session
                        saves run information so subsequent re-runs may avoid re-scanning files.
  --relative-paths, --no-relative-paths
                        show paths as relative to CWD where possible.
  --external, --no-external
                        include sources from external/system locations.
  --pch, --no-pch       include build-system-generated precompiled header sources.
  --fix, --no-fix       attempt to apply clang-tidy fixes where possible.
  --plugins <path...> [<path...> ...]
                        one or more plugins to load.

v0.11.2 - github.com/marzer/clang-tidier

Clang-tidy plugins

Clang tidy plugins can be specified in two ways:

• directly using the argument --plugins (--load also works for compatibility with clang-tidy)
• indirectly using either environment variables CLANG_TIDY_PLUGINS or CLANG_TIDIER_PLUGINS

Specifying multiple plugins via environment variable requires delimiting with semicolons. Regular unix-style colon delimiters are also supported on Unix.

Plugins specified on the command-line must exist; the program will exit with an error if they do not. Plugins specified via environment variable will be ignored with a warning if they are not found.

Exit codes

A bad --batch value and a missing compilation database or plugin are fatal errors.

Contributing

See CONTRIBUTING.md for the development setup, the tests and how releases are made.

Changelog

v0.12.0 - 2026-10-15

• fixed clang-tidier failing on Windows, macOS and Python 3.14, where worker processes are not forked
• fixed --labels-only dropping the first label of each file, so a file with one warning printed nothing
• fixed clang-tidy's output being post-processed twice when it wrote to both stdout and stderr
• fixed a worker process crash being reported twice
• fixed a crash when the session file was deleted or emptied during a run
• fixed a crash when the CPU count could not be determined
• fixed the error for a non-array compilation database naming clang-tidy instead of compile_commands.json
• fixed compilation database discovery picking an arbitrary subdirectory when several had one
• fixed .gitignore rules being ignored in git worktrees and other checkouts where .git is a file
• dropped support for Python 3.8

v0.11.2 - 2026-02-26

• Fixed various minor issues introduced by clang-tidy 22

v0.11.1 - 2025-10-22

• Fixed f-string SyntaxError exception on some python versions

v0.11.0 - 2025-10-21

• Added --pch, --no-pch

v0.10.2 - 2025-10-21

• Fixed --allow-no-checks being passed to clang-tidy < 19.0
• Fixed plugin information being emitted in --labels-only mode
• Fixed minor output formatting issues

v0.10.1 - 2025-04-12

• Fixed all errors being disabled being treated as an error

v0.10.0 - 2025-04-04

• Added --external, --no-external

v0.9.1 - 2025-03-20

• Fixed issues with plugin symlink resolution

v0.9.0 - 2025-03-19

• Added support for reading plugins from environment
• Added diagnostics if a specified plugin does not exist
• Fixed plugin changes not trigging session restarts in some circumstances

v0.8.0 - 2025-03-16

• Added --plugins

v0.7.2 - 2025-03-11

• Fixed some additional compiler flag-related breakages

v0.7.1 - 2025-02-26

• Fixed some additional compiler flag-related breakages

v0.7.0 - 2025-02-12

• Added --fix
• Fixed clang's -ftime-trace causing failures in some cases

v0.6.0 - 2025-02-10

• Added --relative-paths to enable relative paths in output
• Fixed paths in output always being relative by default

v0.5.2 - 2025-01-30

• Fixed compiler argument slicing regression introduced in v0.5.1

v0.5.1 - 2025-01-29

• Fixed sanitizer and GCC flags breaking clang-tidy in some common cases

v0.5.0 - 2025-01-27

• Added --batch x/y to enable distributed parallelism
• Minor internal fixes

v0.4.1 - 2024-11-19

• Fixed precompiled headers breaking runs in some circumstances
• Improved wording of session restart message

v0.4.0 - 2024-09-07

• Fixed sessions not restarting if .clang-tidy is modified
• Added --labels-only
• Minor performance improvements

v0.3.0 - 2024-08-04

• Added --no-session
• Added use of sessions by default

v0.2.0 - 2024-08-03

• Added --session

v0.1.2 - 2024-06-06

• Fixed build-generated translation causing 'did not exist or was not a file' errors
• Improved performance of TU enumeration step

v0.1.1 - 2024-05-16

• Fixed issues with older clang-tidy versions trying to use --use-color

v0.1.0 - 2024-05-09

• First public release 🎉