{"id":2431,"library":"clang-format","title":"clang-format","description":"clang-format is a Python package that distributes the official LLVM-based code formatting utility for C, C++, C#, Java, JavaScript, JSON, Objective-C, and Protobuf. It allows users to easily install and use a specific version of the `clang-format` executable via pip. The project aims to release a new PyPI package for each major and minor release of upstream clang-format, currently at version 22.1.3.","status":"active","version":"22.1.3","language":"en","source_language":"en","source_url":"https://github.com/ssciwr/clang-format-wheel","tags":["code formatting","c++","c","llvm","development tool","static analysis"],"install":[{"cmd":"pip install clang-format","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The primary way to use this package is via its provided command-line executable. Direct programmatic imports for the main formatting logic are not typically exposed for general use, though internal entry points exist.","symbol":"clang-format (executable)","correct":"import subprocess; subprocess.run(['clang-format', ...])"},{"note":"This refers to the Python function that acts as the entry point for the `clang-format` console script, suitable for advanced programmatic invocation, though direct `subprocess` calls are more common for user-facing formatting.","symbol":"clang_format","correct":"from clang_format import clang_format"}],"quickstart":{"code":"import subprocess\nimport os\nimport tempfile\n\n# Create a dummy C++ file\ncpp_code_unformatted = \"\"\"\n#include <iostream>\n\nint main() {\n    std::cout << \"Hello, World!\" << std::endl;\n        return 0;\n}\n\"\"\"\n\n# Use a temporary file to demonstrate formatting a real file\nwith tempfile.NamedTemporaryFile(mode='w', suffix='.cpp', delete=False) as temp_file:\n    temp_file.write(cpp_code_unformatted)\n    temp_file_path = temp_file.name\n\ntry:\n    # Run clang-format on the temporary file\n    # The 'clang-format' command is made available in PATH by the pip installation\n    result = subprocess.run(\n        [\"clang-format\", \"-style=LLVM\", temp_file_path],\n        capture_output=True,\n        text=True, # Decode stdout/stderr as text\n        check=True # Raise an exception for non-zero exit codes\n    )\n\n    formatted_code = result.stdout\n    print(\"Original code:\\n\", cpp_code_unformatted)\n    print(\"\\nFormatted code:\\n\", formatted_code)\n\nexcept FileNotFoundError:\n    print(\"Error: 'clang-format' executable not found. Make sure it's installed and in your system's PATH.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error formatting file: {e.returncode}\")\n    print(f\"Stderr: {e.stderr}\")\nfinally:\n    # Clean up the temporary file\n    os.remove(temp_file_path)\n","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"The `-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.","severity":"breaking","affected_versions":"All versions where `SortIncludes` is enabled (default in some styles)."},{"fix":"Be 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.","message":"While 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.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Ensure 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.","message":"Incorrect 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.","severity":"gotcha","affected_versions":"Particularly versions 20.1.0 and newer for C/Cpp language detection."},{"fix":"Ensure 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.","message":"Using 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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}