Getting started

This page is for engineers who want to build, run, and modify ClickHouse from source. SQL users should start with the official user docs instead.

Prerequisites

• A 64-bit Linux (x86_64 or aarch64) or macOS host. Windows is not supported.
• A modern clang (the project pins a specific LLVM version per release; check cmake/tools.cmake).
• cmake ≥ 3.20, ninja, git, python3, and at least 16 GB of free RAM (more for parallel builds).
• Submodules: ClickHouse vendors 250+ libraries under contrib/. They must be checked out before building.

The official setup walkthrough is Developer prerequisites. The build matrix (amd64/aarch64/riscv64/loongarch64/musl/freebsd) is exercised in CI under ci/jobs/.

Clone

git clone --recursive https://github.com/ClickHouse/ClickHouse.git
cd ClickHouse
# If you forgot --recursive:
git submodule update --init --recursive

The repo is large (≈300k commits, ≈8000 source files in src/, hundreds of submodules) — expect a few GB on disk.

Build

The canonical build is documented in docs/en/development/build.md. The short form:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ ..
ninja clickhouse                  # the universal binary

Per AGENTS.md, do not pass -j to ninja — it picks an appropriate parallelism on its own. Build outputs land in programs/clickhouse inside the build directory.

Common variants:

Build type	Cmake flag	Notes
Debug	-DCMAKE_BUILD_TYPE=Debug	Slowest binary, fastest build, asserts enabled
RelWithDebInfo	-DCMAKE_BUILD_TYPE=RelWithDebInfo	Good for profiling
ASan	-DSANITIZE=address	Memory bug catcher; stays performant enough for tests
TSan	-DSANITIZE=thread	Race condition detector
MSan	-DSANITIZE=memory	Uninitialized read detector (requires instrumented stdlib)
UBSan	-DSANITIZE=undefined	Undefined-behaviour detector
Coverage	-DCMAKE_BUILD_TYPE=RelWithDebInfo -DSANITIZE_COVERAGE=1	LLVM source-based coverage

Multiple build directories are normal — build, build_debug, build_asan, build_tsan, etc. live side-by-side.

Running locally

# Run the embedded engine on the spot, without configuration:
build/programs/clickhouse local --query "SELECT version()"

# Run the server in the foreground from the source tree:
build/programs/clickhouse server --config-file=programs/server/config.xml

# Connect with the native client:
build/programs/clickhouse client

clickhouse-server is the long-running database. clickhouse-local is the same engine packaged as a single-process tool that can read files directly. clickhouse-client is the interactive terminal.

Tests

ClickHouse has many test layers. They are described in detail in Testing. Quick reference:

Layer	Location	Runner
Stateless SQL tests	tests/queries/0_stateless/	tests/clickhouse-test
Stateful SQL tests	tests/queries/1_stateful/	tests/clickhouse-test (needs preloaded data)
Integration	tests/integration/	python -m ci.praktika run "integration"
Unit	src/**/tests/gtest_*.cpp	ctest / unit_tests_dbms
Performance	tests/performance/	tests/performance/scripts/
Fuzzing	tests/fuzz/, programs/server/fuzzers/, src/**/fuzzers/	libFuzzer
SQL logic	tests/sqllogic/	tests/sqllogic/runner.py
Jepsen	tests/jepsen.clickhouse/	Clojure

For a focused stateless run:

build/programs/clickhouse-test 00001_select_1

Linting and style

C++ uses clang-format (config in .clang-format) and clang-tidy (config in .clang-tidy). Allman braces are enforced in CI.

Python tooling configuration is in pyproject.toml (ruff/black). YAML is checked via .yamllint.

The CI workflow definitions live in ci/ (the in-house "Praktika" workflow runner) and .github/workflows/ (the GitHub-hosted entry points).

Where to go next

• Development workflow — branches, PR template, CI gating.
• Patterns and conventions — Allman braces, error handling, no-sleep rule, ASan vs ASAN, etc.
• Tooling — c++expr, analyze-assembly.py, perf-report, CI report fetcher.
• Debugging — sanitizers, fuzzers, stack-trace symbolisation.