> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Как собрать ClickHouse на Linux

> Пошаговое руководство по сборке ClickHouse из исходного кода на системах Linux

> [!NOTE]
>
> **Это руководство по сборке предназначено для разработчиков, вносящих изменения в сам ClickHouse.**
>
> Если вы не изменяете исходный код ClickHouse, вы можете установить готовую сборку ClickHouse, как описано в разделе [Быстрый старт](https://clickhouse.com/docs/ru/get-started/setup/install.md).

ClickHouse можно собрать на следующих платформах:

* x86\_64
* AArch64
* PowerPC 64 LE (экспериментальная)
* s390/x (экспериментальная)
* RISC-V 64 (экспериментальная)

## Предварительные условия

Следующее руководство основано на Ubuntu Linux, но при соответствующих изменениях оно должно работать и в любом другом дистрибутиве Linux.
Минимальная рекомендуемая версия Ubuntu для разработки — 24.04 LTS.

В этом руководстве предполагается, что у вас локально клонированы репозиторий ClickHouse и все подмодули.

## Установите необходимые предварительные требования

Сначала ознакомьтесь с общей [документацией по предварительным требованиям](https://clickhouse.com/docs/ru/resources/develop-contribute/introduction/developer-instruction.md).

ClickHouse использует CMake и Ninja для сборки.

При желании можно установить ccache, чтобы сборка повторно использовала уже скомпилированные объектные файлы.

```bash theme={null}
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

Чтобы установить Clang на Ubuntu/Debian, используйте автоматический скрипт установки LLVM, доступный [здесь](https://apt.llvm.org/).

```bash theme={null}
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 22
```

Для других дистрибутивов Linux проверьте, можно ли установить один из [предварительно собранных пакетов LLVM](https://releases.llvm.org/download.html).

По состоянию на февраль 2026 года требуется Clang 21 или выше.
GCC и другие компиляторы не поддерживаются.

## Установите компилятор Rust (необязательно)

> [!NOTE]
>
> Rust — необязательная зависимость ClickHouse.
> Если Rust не установлен, некоторые возможности ClickHouse не будут включены в сборку.

Сначала выполните шаги из официальной [документации Rust](https://www.rust-lang.org/tools/install), чтобы установить `rustup`.

Как и в случае с зависимостями C++, ClickHouse использует вендоринг, чтобы точно контролировать состав устанавливаемых компонентов и не зависеть от сторонних сервисов (таких как реестр `crates.io`).

Хотя в режиме релизной сборки с этими зависимостями должна работать любая современная версия toolchain из rustup, если вы планируете включить санитайзеры, необходимо использовать версию, которая в точности соответствует той же `std`, что и версия, используемая в CI (для которой мы вендорим крейты):

```bash theme={null}
rustup toolchain install nightly-2026-03-22
rustup default nightly-2026-03-22
rustup component add rust-src
```

## Сборка ClickHouse

Мы рекомендуем создать внутри `ClickHouse` отдельный каталог `build`, в котором будут находиться все артефакты сборки:

```sh theme={null}
mkdir build
cd build
```

У вас может быть несколько разных каталогов (например, `build_release`, `build_debug` и т. д.) для разных типов сборки.

Необязательно: если у вас установлено несколько версий компилятора, при необходимости можно указать, какой именно компилятор использовать.

```sh theme={null}
export CC=clang-22
export CXX=clang++-22
```

Для разработки рекомендуется использовать отладочные сборки.
По сравнению с релизными сборками у них ниже уровень оптимизации компилятора (`-O`), что упрощает отладку.
Кроме того, внутренние исключения типа `LOGICAL_ERROR` приводят к немедленному аварийному завершению вместо корректной обработки ошибки.

```sh theme={null}
cmake -D CMAKE_BUILD_TYPE=Debug ..
```

> [!NOTE]
>
> Если вы хотите использовать отладчик, например gdb, добавьте `-D DEBUG_O_LEVEL="0"` к приведённой выше команде, чтобы отключить все оптимизации компилятора, которые могут мешать gdb просматривать переменные и обращаться к ним.

Запустите ninja для сборки:

```sh theme={null}
ninja clickhouse
```

Если вы хотите собрать все бинарные файлы (утилиты и тесты), запустите ninja без параметров:

```sh theme={null}
ninja
```

Вы можете управлять количеством параллельных задач сборки с помощью параметра `-j`:

```sh theme={null}
ninja -j 1 clickhouse
```

> [!NOTE]
>
> `clickhouse-server`, `clickhouse-client` и другие подобные бинарные файлы представляют собой символические ссылки в каталоге `programs/`, указывающие на исполняемый файл `clickhouse` после завершения сборки.

> [!TIP]
>
> CMake предоставляет сокращённые варианты приведённых выше команд:
>
> ```sh theme={null}
> cmake -S . -B build  # настроить сборку, запускать из корневого каталога репозитория
> cmake --build build  # скомпилировать
> ```

## исполняемый файл ClickHouse

После успешного завершения сборки исполняемый файл находится в `ClickHouse/<build_dir>/programs/`:

Сервер ClickHouse пытается найти файл конфигурации `config.xml` в текущем каталоге.
При необходимости вы также можете указать файл конфигурации в командной строке с помощью `-C`.

Чтобы подключиться к серверу ClickHouse с помощью `clickhouse-client`, откройте другой терминал, перейдите в `ClickHouse/build/programs/` и выполните `./clickhouse client`.

Если в macOS или FreeBSD вы получаете сообщение `Connection refused`, попробуйте указать адрес хоста 127.0.0.1:

```bash theme={null}
clickhouse client --host 127.0.0.1
```

## Дополнительные параметры

### Минимальная сборка

Если вам не нужны возможности, предоставляемые сторонними библиотеками, вы можете ускорить сборку ещё сильнее:

```sh theme={null}
cmake -DENABLE_LIBRARIES=OFF
```

Если возникнут проблемы, вам придется разбираться с ними самостоятельно ...

Для работы Rust требуется подключение к интернету. Чтобы отключить поддержку Rust:

```sh theme={null}
cmake -DENABLE_RUST=OFF
```

### Исполняемый файл ClickHouse

Вы можете заменить установленный в системе продакшн-бинарный файл ClickHouse на скомпилированный бинарный файл ClickHouse.
Для этого установите ClickHouse на свой компьютер, следуя инструкциям на официальном сайте.
Далее выполните:

```bash theme={null}
sudo service clickhouse-server stop
sudo cp ClickHouse/build/programs/clickhouse /usr/bin/
sudo service clickhouse-server start
```

Обратите внимание, что `clickhouse-client`, `clickhouse-server` и другие — это символические ссылки на общий бинарный файл `clickhouse`.

Вы также можете запустить собственноручно собранный бинарный файл ClickHouse с файлом config из установленного в системе пакета ClickHouse:

```bash theme={null}
sudo service clickhouse-server stop
sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml
```

### Сборка в любом дистрибутиве Linux

Установите необходимые зависимости в OpenSUSE Tumbleweed:

```bash theme={null}
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:

```bash theme={null}
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, с помощью:

```bash theme={null}
python -m ci.praktika run "BUILD_JOB_NAME"
```

где BUILD\_JOB\_NAME — это имя задачи, указанное в отчёте CI, например: "Build (arm\_release)", "Build (amd\_debug)"

Эта команда загружает соответствующий Docker-образ `clickhouse/binary-builder` со всеми необходимыми зависимостями
и запускает внутри него скрипт сборки: `./ci/jobs/build_clickhouse.py`

Результат сборки будет помещён в `./ci/tmp/`.

Команда работает на архитектурах AMD и ARM и не требует никаких дополнительных зависимостей, кроме Python с доступным модулем `requests` и Docker.
