Skip to content

clang-tools

PyPI ci coverage part of cpp-linter

Install clang-format, clang-tidy and other LLVM tools without building LLVM, as static binaries or Python wheels, using the clang-tools CLI.

Website · Documentation · Get started · Discussions

Quick start

pip install clang-tools
clang-tools install clang-format clang-tidy --version 21

This installs the LLVM 21 static binaries clang-format-21 and clang-tidy-21. Without --version, it installs the newest LLVM version. Without --directory, they go to ~/.local/bin on Linux, and on macOS and Windows to the folder that holds the Python executable (the bin or Scripts folder of a virtual environment). A --directory that doesn't exist is created, but the parent folder(s) must exist.

Tip

It is recommended to use this package in a virtual environment.

python -m venv env-name
source env-name/bin/activate  # Linux and macOS
./env-name/Scripts/activate   # Windows

Usage

clang-tools install installs the static binary of each tool. It falls back to the tool's wheel from PyPI when there is no static binary for that version, tool or platform, or when the download fails; any other error stops the command. Without --version, it installs the newest version. For a full list of CLI options, see the CLI reference.

--version can be a major version (21) or a full one (21.1.8). Either way the binary is named by its major version (clang-format-21). A full version must match exactly: if the static binary of LLVM 21 is another patch release, the wheel of that exact version is installed instead.

Install binaries

# Install the newest version
clang-tools install clang-format

# Install a specific version (binary first, falls back to the wheel)
clang-tools install clang-format --version 21

# Install to a specified directory
clang-tools install clang-format --version 21 --directory .

If the installed directory is in your path:

clang-format-21 --version
# clang-format version 21.1.0

To uninstall, give the tool names and the version:

clang-tools uninstall clang-format --version 21 --directory .
  • Uses SHA512 checksums to verify downloaded binaries.
  • Keeps each downloaded binary in a data directory, one folder per release, and puts a link to it (e.g., clang-format-21) in the install directory. Installing the same version again, in any directory, doesn't download it again.
  • Installs clang's builtin headers (stddef.h, stdarg.h, ...) next to clang-tidy, clang-query, clang-include-cleaner and clang-scan-deps, so they can parse code that includes system headers.
  • Creates unversioned symlinks (e.g., clang-format) alongside versioned binaries (clang-format-21) for convenience.
  • If the versioned binary (e.g., clang-format-21) is already on your PATH, links to it instead of downloading.

The data directory is ~/.local/share/clang-tools on Linux (or $XDG_DATA_HOME/clang-tools), ~/Library/Application Support/clang-tools on macOS and %LOCALAPPDATA%\clang-tools on Windows. Set CLANG_TOOLS_DATA_DIR to use another directory. clang-tools uninstall removes the links, not the data directory; delete it to free the space.

An install directory outside your home directory, such as /usr/local/bin with sudo or in a Docker image, gets a copy of each tool instead of a link, because other users may not be able to read your home directory. The builtin headers then go to <install directory>/../lib/clang (such as /usr/local/lib/clang), where clang looks for them. Setting CLANG_TOOLS_DATA_DIR keeps the links.

A static binary installed by clang-tools is checked against the index each time it is installed again. If the index can't be reached (for example, offline), the installed binary is kept. A wheel of the version asked for is kept as it is, without checking the package index.

Note

To create symbolic links on Windows, you must enable Developer Mode. Without it, the binaries are copied to the install directory. On Windows, clang's builtin headers are also copied to <install directory>\..\lib\clang, because clang (LLVM 12 to 17 at least) looks for them next to the link rather than next to the binary it points to.

Important

This package only manages binary executables (& corresponding symbolic links) that are installed using this package's executable script. It does not intend to change or modify any binary executable installed from other sources (like LLVM releases).

Install wheels

When there is no static binary, clang-tools downloads the tool's wheel from PyPI, checks its SHA256 checksum and installs it like a static binary: a link in the install directory (e.g. clang-format-10) to the executable kept in the data directory. pip is not needed, so this works in environments made by uv, uvx and pipx, and --directory and clang-tools uninstall work the same as for binaries.

# clang-format 10 has no static binary, so its wheel is installed
clang-tools install clang-format --version 10

Wheels are found with the simple repository API of the package index (PEP 691 or PEP 503), so a mirror of PyPI works too. The index is CLANG_TOOLS_PYPI_URL, else the one set with UV_DEFAULT_INDEX, UV_INDEX_URL or PIP_INDEX_URL (default: https://pypi.org/simple). The URL may hold a user name and password, which are only sent to that server (not after a redirect to another URL). Configuration files such as pip.conf and uv.toml are not read, and neither are extra indexes, so an index that doesn't have the tools needs CLANG_TOOLS_PYPI_URL set to https://pypi.org/simple or a mirror of it.

Install the development version

pip install git+https://github.com/cpp-linter/clang-tools-pip.git@main

Supported versions

clang tools binaries

Every LLVM version listed in the index (LLVM 12 to 23 today), for Linux, macOS and Windows on x86-64 and ARM64:

  • clang-format
  • clang-tidy
  • clang-query
  • clang-apply-replacements
  • clang-include-cleaner (LLVM 18 and later)
  • llvm-cov
  • llvm-profdata
  • llvm-symbolizer
  • clang-scan-deps

For more details, visit clang-tools-static-binaries.

clang tools Python wheels

Wheels are used for versions and platforms that have no static binary, such as clang-format 10, 32-bit Windows, or Linux on i686 and ARMv7 (and on ppc64le and s390x for clang-format). Check the respective PyPI pages for available versions and platform support.

Contributing

See the contributing guide and open an issue for bugs and feature requests.

License

This project is licensed under the MIT License.