Environment:Duckdb Duckdb Code Formatting Tools

Knowledge Sources	DuckDB clang-format Black
Domains	Infrastructure, Code_Quality
Last Updated	2026-02-07 12:00 GMT

Overview

Code formatting environment requiring clang-format 11.0.1 (exact version), Black >= 24, and cmake-format for enforcing DuckDB's source code style.

Description

This environment provides the formatting tools required to pass DuckDB's CI formatting checks. The project enforces strict version requirements: clang-format must be exactly version 11.0.1 (different versions produce different output), Black must be version 24 or higher, and cmake-format must be installed for CMake file formatting. The `make format-fix` command runs all formatters. Version checks can be bypassed by setting the `DUCKDB_FORMAT_SKIP_VERSION_CHECKS` environment variable.

Usage

Use this environment before submitting any pull request. Run `make format-fix` to auto-format all source files. The formatting check is enforced in CI and PRs will fail if code is not properly formatted.

System Requirements

Category	Requirement	Notes
OS	Linux, macOS, or Windows	Cross-platform Python packages
Hardware	Any	No special hardware requirements
Python	Python 3.6+	Required for pip-installed tools

Dependencies

Python Packages

• `clang-format` == 11.0.1 (exact version required)
• `black` >= 24
• `cmake-format` (any version)

Credentials

No credentials required.

Quick Install

# Install all formatting tools
pip install clang-format==11.0.1 "black>=24" cmake-format

# Format all files
make format-fix

# Check formatting without modifying files
make format-check

Code Evidence

clang-format version check from `scripts/format.py:33-41`:

try:
    ver = subprocess.check_output(('clang-format', '--version'), text=True)
    if '11.' not in ver:
        print('you need to run `pip install clang_format==11.0.1 - `', ver)
        if 'DUCKDB_FORMAT_SKIP_VERSION_CHECKS' not in os.environ:
            exit(-1)
except Exception as e:
    print('you need to run `pip install clang_format==11.0.1 - `', e)
    exit(-1)

Black version check from `scripts/format.py:23-31`:

try:
    ver = subprocess.check_output(('black', '--version'), text=True)
    if int(ver.split(' ')[1].split('.')[0]) < 24:
        print('you need to run `pip install "black>=24"`', ver)
        if 'DUCKDB_FORMAT_SKIP_VERSION_CHECKS' not in os.environ:
            exit(-1)
except Exception as e:
    print('you need to run `pip install "black>=24"`', e)
    exit(-1)

cmake-format check from `scripts/format.py:46-50`:

try:
    subprocess.check_output(('cmake-format', '--version'), text=True)
except Exception as e:
    print('you need to run `pip install cmake-format`', e)
    exit(-1)

Common Errors

Error Message	Cause	Solution
`you need to run pip install clang_format==11.0.1`	Wrong clang-format version installed	`pip install clang-format==11.0.1`
`you need to run pip install "black>=24"`	Black version too old or not installed	`pip install "black>=24"`
`you need to run pip install cmake-format`	cmake-format not installed	`pip install cmake-format`
CI format check failing	Code not formatted before commit	Run `make format-fix` before committing

Compatibility Notes

• Version strictness: clang-format version 11.0.1 is strictly required. Different versions produce different output, causing CI failures.
• Version bypass: Set `DUCKDB_FORMAT_SKIP_VERSION_CHECKS` environment variable to skip version validation (not recommended for CI).
• Style rules: Tabs for indentation, spaces for alignment. Lines must not exceed 120 columns.
• EditorConfig: The project includes an `.editorconfig` file that enforces formatting rules in supported editors.

Related Pages

• Implementation:Duckdb_Duckdb_Setup_Ubuntu_Build_Env