Linux에서 ClickHouse를 빌드하는 방법

이 빌드 가이드는 ClickHouse 자체를 수정하는 기여자를 위한 안내서입니다.ClickHouse 소스 코드를 변경하지 않는다면 Quick Start에 설명된 대로 사전 구축된 ClickHouse를 설치할 수 있습니다.

ClickHouse는 다음 플랫폼에서 빌드할 수 있습니다.

x86_64
AArch64
PowerPC 64 LE (실험적)
s390/x (실험적)
RISC-V 64 (실험적)

전제 조건

다음 튜토리얼은 Ubuntu Linux를 기준으로 작성되었지만, 필요한 부분을 적절히 변경하면 다른 Linux 배포판에서도 사용할 수 있습니다. 개발에 권장되는 최소 Ubuntu 버전은 24.04 LTS입니다. 이 튜토리얼은 ClickHouse 리포지토리와 모든 서브모듈을 로컬에 체크아웃해 두었다고 가정합니다.

필수 구성 요소 설치

먼저, 일반 필수 구성 요소 문서를 확인하십시오. ClickHouse는 빌드에 CMake와 Ninja를 사용합니다. 선택 사항으로, 이미 컴파일된 객체 파일을 빌드에 재사용할 수 있도록 ccache를 설치할 수 있습니다.

sudo apt-get update
sudo apt-get install build-essential git cmake ccache python3 ninja-build nasm yasm gawk lsb-release wget software-properties-common gnupg

Clang 컴파일러 설치

Ubuntu/Debian에 Clang을 설치하려면 여기에서 제공하는 LLVM의 자동 설치 스크립트를 사용하십시오.

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21

다른 Linux 배포판에서는 LLVM의 미리 빌드된 패키지를 설치할 수 있는지 확인하세요. 2026년 2월 기준으로 Clang 21 이상이 필요합니다. GCC 및 기타 컴파일러는 지원되지 않습니다.

Rust 컴파일러 설치(선택 사항)

Rust는 ClickHouse의 선택적 의존성입니다. Rust가 설치되어 있지 않으면 ClickHouse의 일부 기능은 컴파일에 포함되지 않습니다.

먼저 공식 Rust 문서의 안내에 따라 rustup을 설치합니다. C++ 의존성과 마찬가지로 ClickHouse는 정확히 어떤 항목이 설치되는지 제어하고, crates.io registry와 같은 타사 서비스에 의존하지 않기 위해 벤더링을 사용합니다. 릴리스 모드에서는 일반적으로 최신 rustup 툴체인 버전이면 이러한 의존성과 함께 동작하지만, 새니타이저를 활성화할 계획이라면 CI에서 사용하는 것과 정확히 동일한 std에 맞는 버전을 사용해야 합니다(이 경우 크레이트를 벤더링함):

rustup toolchain install nightly-2026-03-22
rustup default nightly-2026-03-22
rustup component add rust-src

ClickHouse 빌드

모든 빌드 아티팩트를 포함하는 별도의 디렉터리 build를 ClickHouse 내부에 생성하는 것을 권장합니다:

mkdir build
cd build

서로 다른 빌드 유형에 따라 여러 디렉터리(예: build_release, build_debug 등)를 둘 수 있습니다. 선택 사항: 여러 컴파일러 버전이 설치되어 있다면 사용할 컴파일러를 정확히 지정할 수 있습니다.

export CC=clang-21
export CXX=clang++-21

개발용으로는 디버그 빌드를 권장합니다. 릴리스 빌드와 비교하면 컴파일러 최적화 수준(-O)이 더 낮아 디버깅이 더 수월합니다. 또한 LOGICAL_ERROR 유형의 내부 예외는 정상적으로 처리되지 않고 즉시 크래시가 발생합니다.

cmake -D CMAKE_BUILD_TYPE=Debug ..

gdb와 같은 디버거를 사용하려면 위 명령에 -D DEBUG_O_LEVEL="0"를 추가해 모든 컴파일러 최적화를 비활성화하십시오. 이러한 최적화는 gdb가 변수를 확인하거나 접근하는 데 방해가 될 수 있습니다.

빌드하려면 ninja를 실행하십시오:

ninja clickhouse

모든 바이너리(유틸리티 및 테스트 포함)를 빌드하려면 매개변수 없이 ninja를 실행하세요:

ninja

매개변수 -j를 사용해 병렬 빌드 작업 수를 조절할 수 있습니다:

ninja -j 1 clickhouse

clickhouse-server, clickhouse-client 및 이와 유사한 바이너리는 빌드 완료 후 clickhouse 실행 파일을 가리키는 programs/ 디렉터리의 심볼릭 링크입니다.:::tip CMake는 위 명령어에 대한 단축 구문을 제공합니다.

cmake -S . -B build  # 빌드 구성, 리포지토리 최상위 디렉터리에서 실행
cmake --build build  # 컴파일

ClickHouse 실행 파일 실행하기

빌드가 성공적으로 완료되면 실행 파일은 ClickHouse/<build_dir>/programs/에서 찾을 수 있습니다: ClickHouse 서버는 현재 디렉터리에서 설정 파일 config.xml을 찾습니다. 또는 명령줄에서 -C를 사용해 설정 파일을 지정할 수 있습니다. clickhouse-client로 ClickHouse 서버에 연결하려면 다른 터미널을 열고 ClickHouse/build/programs/로 이동한 다음 ./clickhouse client를 실행하세요. macOS 또는 FreeBSD에서 Connection refused 메시지가 표시되면 호스트 주소 127.0.0.1을 지정해 보세요:

clickhouse client --host 127.0.0.1

고급 옵션

최소 빌드

타사 라이브러리에서 제공하는 기능이 필요하지 않다면 빌드 속도를 더 높일 수 있습니다.

cmake -DENABLE_LIBRARIES=OFF

문제가 발생하면 직접 해결해야 합니다 … Rust는 인터넷 연결이 필요합니다. Rust 지원을 비활성화하려면:

cmake -DENABLE_RUST=OFF

ClickHouse 실행 파일 실행하기

시스템에 설치된 운영 환경용 ClickHouse 바이너리를 컴파일한 ClickHouse 바이너리로 교체할 수 있습니다. 이렇게 하려면 공식 웹사이트의 안내에 따라 시스템에 ClickHouse를 설치하십시오. 그런 다음, 다음을 실행하십시오:

sudo service clickhouse-server stop
sudo cp ClickHouse/build/programs/clickhouse /usr/bin/
sudo service clickhouse-server start

clickhouse-client, clickhouse-server 등은 공용 clickhouse 실행 파일에 대한 심볼릭 링크라는 점에 유의하십시오. 시스템에 설치된 ClickHouse 패키지의 구성 파일을 사용해 사용자 지정으로 빌드한 ClickHouse 실행 파일을 실행할 수도 있습니다:

sudo service clickhouse-server stop
sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml

모든 Linux에서 빌드하기

OpenSUSE Tumbleweed에 필요한 패키지를 설치합니다:

sudo zypper install git cmake ninja clang-c++ python lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build

Fedora Rawhide에서 필수 구성 요소를 설치합니다:

sudo yum update
sudo yum --nogpg install git cmake make clang python3 ccache lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build

Docker에서 빌드하기

다음을 사용하면 CI와 유사한 환경에서 로컬에서 원하는 빌드를 실행할 수 있습니다:

python -m ci.praktika run "BUILD_JOB_NAME"

여기서 BUILD_JOB_NAME은 CI 보고서에 표시된 job 이름입니다. 예: “Build (arm_release)”, “Build (amd_debug)” 이 명령은 필요한 모든 종속성이 포함된 적절한 Docker image clickhouse/binary-builder를 pull한 다음, 그 안에서 빌드 스크립트 ./ci/jobs/build_clickhouse.py를 실행합니다. 빌드 출력은 ./ci/tmp/에 생성됩니다. 이 방식은 AMD 및 ARM 아키텍처 모두에서 작동하며, requests 모듈을 사용할 수 있는 Python과 Docker 외에는 추가 종속성이 필요하지 않습니다.

Introduction

Building

Native protocol

Contributing

Integration development

Roadmap

Linux에서 ClickHouse를 빌드하는 방법

전제 조건

필수 구성 요소 설치

Clang 컴파일러 설치

Rust 컴파일러 설치(선택 사항)

ClickHouse 빌드

ClickHouse 실행 파일 실행하기

고급 옵션

최소 빌드

ClickHouse 실행 파일 실행하기

모든 Linux에서 빌드하기

Docker에서 빌드하기

​전제 조건

​필수 구성 요소 설치

​Clang 컴파일러 설치

​Rust 컴파일러 설치(선택 사항)

​ClickHouse 빌드

​ClickHouse 실행 파일 실행하기

​고급 옵션

​최소 빌드

​ClickHouse 실행 파일 실행하기

​모든 Linux에서 빌드하기

​Docker에서 빌드하기

전제 조건

필수 구성 요소 설치

Clang 컴파일러 설치

Rust 컴파일러 설치(선택 사항)

ClickHouse 빌드

ClickHouse 실행 파일 실행하기

고급 옵션

최소 빌드

ClickHouse 실행 파일 실행하기

모든 Linux에서 빌드하기

Docker에서 빌드하기