Install & Compatibility
Where this runs
tested against v23.1.0 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.016s · 25.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.016s · 22MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
clang_format
✓ from clang_format import clang_format
✗ import subprocess; subprocess.run(['clang-format', ...])
get_executable
✓ from clang_format import get_executable
Demonstrates how to use the `clang-format` executable provided by the package to format a C++ code string. This is the most common usage pattern.
import subprocess
import os
import tempfile
# Create a dummy C++ file
cpp_code_unformatted = """
#include <iostream>
int main() {
std::cout << "Hello, World!" << std::endl;
return 0;
}
"""
# Use a temporary file to demonstrate formatting a real file
with tempfile.NamedTemporaryFile(mode='w', suffix='.cpp', delete=False) as temp_file:
temp_file.write(cpp_code_unformatted)
temp_file_path = temp_file.name
try:
# Run clang-format on the temporary file
# The 'clang-format' command is made available in PATH by the pip installation
result = subprocess.run(
["clang-format", "-style=LLVM", temp_file_path],
capture_output=True,
text=True, # Decode stdout/stderr as text
check=True # Raise an exception for non-zero exit codes
)
formatted_code = result.stdout
print("Original code:\n", cpp_code_unformatted)
print("\nFormatted code:\n", formatted_code)
except FileNotFoundError:
print("Error: 'clang-format' executable not found. Make sure it's installed and in your system's PATH.")
except subprocess.CalledProcessError as e:
print(f"Error formatting file: {e.returncode}")
print(f"Stderr: {e.stderr}")
finally:
# Clean up the temporary file
os.remove(temp_file_path)
clang-format --version
Debug
Known issues
breakingThe `-sort-includes` option (or `SortIncludes: true` in `.clang-format` config) can reorder `#include` directives. This might break code that relies on specific include order, especially if headers have order-dependent definitions.fixReview formatted code carefully for include reordering issues. Place blank lines between groups of headers to prevent reordering if order is critical. Consider setting `SortIncludes: false` if this is a consistent problem.
affects: All versions where `SortIncludes` is enabled (default in some styles).
gotchaWhile primarily a whitespace formatter, `clang-format` includes features that can make non-whitespace changes (e.g., namespace commenting, certain lambda formatting with `AlignArrayOfStructures`). Unexpected non-whitespace changes can potentially alter code semantics or introduce bugs.fixBe aware of configuration options that enable non-whitespace changes. Use `// clang-format off` and `// clang-format on` to exempt specific code sections from formatting. Visually inspect significant changes or use diff tools.
affects: All versions.
gotchaIncorrect language detection or explicit language configuration in `.clang-format` files can lead to formatting errors. For example, formatting a `.c` file with `Language: Cpp` might fail or produce unexpected results in newer versions of clang-format if `Language: C` is not also specified or implicitly handled.fixEnsure your `.clang-format` file correctly specifies `Language` for different file types or relies on filename auto-detection where appropriate. Use the `-assume-filename` option for `stdin` input or files with ambiguous extensions.
affects: Particularly versions 20.1.0 and newer for C/Cpp language detection.
gotchaUsing a `.clang-format` configuration file that contains options unsupported by the installed `clang-format` version (e.g., options from a newer clang-format version) can lead to silent failures where files are not formatted, or errors.fixEnsure the `clang-format` executable version matches the version for which your `.clang-format` configuration was designed. If issues arise, try running `clang-format` manually from the command line on a test file to see if it reports any errors about unsupported options.
affects: All versions.
Upgrade
Version history
23.1.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
No dependency data recorded yet.