Skip to content

Run clang-tidy on Bazel C++ targets directly, efficiently, with caching enabled


Notifications You must be signed in to change notification settings


Repository files navigation


Run clang-tidy on Bazel C++ targets directly, without generating a compile commands database, and take advantage of Bazels powerful cache mechanism.



       name = "bazel_clang_tidy",
       commit = "43bef6852a433f3b2a6b001daecc8bc91d791b92",
       remote = "",

You can now compile using the default clang tidy configuration provided using the following command;

bazel build //... \
  --aspects @bazel_clang_tidy//clang_tidy:clang_tidy.bzl%clang_tidy_aspect \

If you would like to override the default clang tidy configuration then you can reconfigure the default target from the command line. To do this you must first make a filegroup target that has the .clang-tidy config file as a data dependency.

# //:BUILD
       name = "clang_tidy_config",
       srcs = [".clang-tidy"],
       visibility = ["//visibility:public"],

Now you can override the default config file in this repository using a command line flag;

bazel build //... \
  --aspects @bazel_clang_tidy//clang_tidy:clang_tidy.bzl%clang_tidy_aspect \
  --output_groups=report \

❗ the config-file will not be forced by adding it to the clang-tidy command line. Therefore it must be in one of the parents of all source files. It is recommended to put it in the root directly besides the WORKSPACE file.

Now if you don't want to type this out every time, it is recommended that you add a config in your .bazelrc that matches this command line;

# Required for bazel_clang_tidy to operate as expected
build:clang-tidy --aspects @bazel_clang_tidy//clang_tidy:clang_tidy.bzl%clang_tidy_aspect
build:clang-tidy --output_groups=report

# Optionally override the .clang-tidy config file target
build:clang-tidy --@bazel_clang_tidy//:clang_tidy_config=//:clang_tidy_config

Now from the command line this is a lot nicer to use;

bazel build //... --config clang-tidy

use a non-system clang-tidy

by default, bazel_clang_tidy uses the system provided clang-tidy. If you have a hermetic build, you can use your own clang-tidy target like this:

build:clang-tidy --@bazel_clang_tidy//:clang_tidy_executable=@local_config_cc//:clangtidy_bin

This aspect is not executed on external targets. To exclude other targets, users may tag a target with no-clang-tidy or noclangtidy.


  • Run clang-tidy on any C++ target
  • Run clang-tidy without also building the target
  • Use Bazel to cache clang-tidy reports: recompute stale reports only


Copy .clang-tidy, BUILD and clang_tidy dir to your workspace. Edit .clang-tidy as needed.


To see the tool in action:

  1. Clone the repository

  2. Run clang-tidy:

    bazel build //example --aspects clang_tidy/clang_tidy.bzl%clang_tidy_aspect --output_groups=report
  3. Check the error:

    lib.cpp:4:43: error: the parameter 'name' is copied for each invocation but only used as a const reference; consider making it a const reference [performance-unnecessary-value-param,-warnings-as-errors] std::string lib_get_greet_for(std::string name)
    Aspect //clang_tidy:clang_tidy.bzl%clang_tidy_aspect of //example:app failed to build
  4. Fix the error by changing lib.cpp only.

  5. Re-run clang-tidy with the same command. Observe that it does not run clang-tidy for app.cpp: the cached report is re-used.


  • Bazel 4.0 or newer (might work with older versions)


Run clang-tidy on Bazel C++ targets directly, efficiently, with caching enabled








No releases published


No packages published