Environment:ClickHouse ClickHouse Linux Build Environment

Knowledge Sources	ClickHouse CMakeLists.txt cmake/tools.cmake
Domains	Infrastructure, Build_System
Last Updated	2026-02-08 18:00 GMT

Overview

Linux build environment requiring Clang 21+, CMake 3.25+, Ninja, and LLVM LLD linker for compiling ClickHouse from source on x86_64 or AArch64.

Description

This environment provides the complete toolchain needed to build ClickHouse from source on Linux. ClickHouse exclusively supports the Clang compiler (no GCC) with a minimum version of 21, and requires the LLVM LLD linker. The build system is CMake 3.25+ with Ninja as the preferred generator. The project compiles as C++23 with C11 for C components. Supported architectures include AMD64 (x86_64), AArch64, PowerPC 64LE, S390X, RISC-V 64, and LoongArch 64, though AMD64 and AArch64 are the primary targets.

Usage

Use this environment for any Building From Source workflow. It is the mandatory prerequisite for compiling the ClickHouse binary, running unit tests locally, and building debug or sanitizer variants. All other environment pages (CI, test, deployment) depend on artifacts produced by this environment.

System Requirements

Category	Requirement	Notes
OS	Linux (64-bit)	Also supports macOS, FreeBSD, SunOS with limitations
Architecture	AMD64, AArch64 (primary)	PPC64LE, S390X, RISC-V64, LoongArch64 also supported; 32-bit explicitly unsupported
RAM	8GB+ recommended	Below 8GB disables `-pipe` flag; linker needs 5000MB per job; compiler needs 2500MB per job
Disk	50GB+ SSD	Source tree with submodules is large; build artifacts can be 10-30GB depending on build type
CPU (AMD64)	SSSE3, SSE4.1, SSE4.2, PCLMULQDQ, POPCNT	Minimum CPU features enabled by default; older CPUs require `NO_SSE3_OR_HIGHER=1`
CPU (AArch64)	ARMv8.2-a with SIMD, crypto, dotprod	Older ARMv8.0 supported via `NO_ARMV81_OR_HIGHER=1`

Dependencies

System Packages

`clang` >= 21 (only Clang is supported; GCC is not)
`lld` (LLVM LLD linker; gold linker explicitly prohibited)
`cmake` >= 3.25
`ninja-build` (Ninja build system)
`llvm-ar`, `llvm-ranlib`, `llvm-objcopy`, `llvm-strip` (matched to Clang version)
`git` (for submodule initialization)
`python3` (for build scripts and CI tooling)

macOS Additional Packages

GNU `find` (install via `brew install findutils`)
GNU `grep` (install via `brew install grep`)

Language Standards

C++ Standard: C++23 (`CMAKE_CXX_STANDARD 23`)
C Standard: C11 with extensions (`CMAKE_C_STANDARD 11`, `CMAKE_C_EXTENSIONS ON`)

Credentials

No credentials required for building from source. Git submodules use public HTTPS URLs.

Quick Install

# Ubuntu/Debian - Install Clang 21 and build tools
apt-get install -y git cmake ninja-build
# Install Clang 21 from LLVM apt repository
bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)" -- 21

# Clone and initialize submodules
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
cd ClickHouse
git submodule update --init

# Configure and build
cmake -S . -B build -G Ninja -DCMAKE_C_COMPILER=clang-21 -DCMAKE_CXX_COMPILER=clang++-21
ninja -C build clickhouse

Code Evidence

CMake minimum version from `CMakeLists.txt:1`:

cmake_minimum_required(VERSION 3.25)

Clang-only enforcement from `cmake/tools.cmake:3-16`:

# Only Clang compiler is accepted
set (CLANG_MINIMUM_VERSION 21)

C++23 requirement from `CMakeLists.txt:271-273`:

set (CMAKE_CXX_STANDARD 23)
set (CMAKE_CXX_EXTENSIONS OFF)
set (CMAKE_CXX_STANDARD_REQUIRED ON)

Submodule check from `CMakeLists.txt:58-60`:

if (NOT EXISTS "${ClickHouse_SOURCE_DIR}/contrib/sysroot/README.md")
    message (FATAL_ERROR "Submodules are not initialized. Run\n\tgit submodule update --init")
endif ()

Memory-based parallelism from `CMakeLists.txt:369-373`:

if(COMPILER_PIPE)
    set(MAX_COMPILER_MEMORY 2500)
else()
    set(MAX_COMPILER_MEMORY 1500)
endif()
set(MAX_LINKER_MEMORY 5000)

Common Errors

Error Message	Cause	Solution
`Submodules are not initialized`	Git submodules not fetched	Run `git submodule update --init`
`Only Clang compiler is accepted`	Using GCC or other compiler	Install Clang 21+ and set `CMAKE_C_COMPILER=clang-21 CMAKE_CXX_COMPILER=clang++-21`
`Disabling compiler -pipe option (have only X mb of memory)`	System has less than 8GB RAM	Build will work but use more `/tmp` disk I/O; consider adding swap
`Non default allocator is disabled`	jemalloc not enabled	Add `-DENABLE_JEMALLOC=ON` (default ON); required for production builds
Linker OOM / killed	Insufficient memory for linking	ThinLTO linking needs ~5GB per link job; reduce parallelism or add RAM

Compatibility Notes

macOS: Supported but with limitations. Query Profiler, XRay, and glibc compatibility are unavailable. GNU find and grep must be installed via Homebrew.
FreeBSD/SunOS: Supported with reduced feature set. NuRaft (Keeper) may not be available.
Musl libc: Supported via `USE_MUSL=ON`. Stack size increased to 2MB for recursive-descent parser. Some harmful function traps disabled due to symbol conflicts.
Cross-compilation: Supported for multiple targets. RISC-V and LoongArch have the most feature restrictions (no gRPC, HDFS, MySQL, Rust, etc.).
32-bit platforms: Explicitly unsupported and will fail during CMake configuration.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment