> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Step-by-step guide for building ClickHouse from source on Linux systems

# How to Build ClickHouse on Linux

<Info>
  **This build guide is for contributors modifying ClickHouse itself.**

  If you are not changing ClickHouse source code, you can install pre-built ClickHouse as described in [Quick Start](/get-started/setup/install).
</Info>

ClickHouse can be build on the following platforms:

* x86\_64
* AArch64
* PowerPC 64 LE (experimental)
* s390/x (experimental)
* RISC-V 64 (experimental)

<h2 id="assumptions">
  Assumptions
</h2>

The following tutorial is based on Ubuntu Linux but it should also work on any other Linux distribution with appropriate changes.
The minimum recommended Ubuntu version for development is 24.04 LTS.

The tutorial assumes that you have the ClickHouse repository and all submodules locally checked out.

<h2 id="install-prerequisites">
  Install prerequisites
</h2>

First, see the generic [prerequisites documentation](/resources/develop-contribute/introduction/developer-instruction).

ClickHouse uses CMake and Ninja for building.

You can optionally install ccache to let the build reuse already compiled object files.

```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
```

<h2 id="install-the-clang-compiler">
  Install the Clang compiler
</h2>

To install Clang on Ubuntu/Debian, use LLVM's automatic installation script from [here](https://apt.llvm.org/).

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

For other Linux distributions, check if you can install any of LLVM's [prebuild packages](https://releases.llvm.org/download.html).

As of February 2026, Clang 21 or higher is required.
GCC or other compilers are not supported.

<h2 id="install-the-rust-compiler-optional">
  Install the Rust compiler (optional)
</h2>

<Note>
  Rust is an optional dependency of ClickHouse.
  If Rust is not installed, some features of ClickHouse will be omitted from compilation.
</Note>

First, follow the steps in the official [Rust documentation](https://www.rust-lang.org/tools/install) to install `rustup`.

As with C++ dependencies, ClickHouse uses vendoring to control exactly what's installed and avoid depending on third party services (like the `crates.io` registry).

Although in release mode any rust modern rustup toolchain version should work with these dependencies, if you plan to enable sanitizers you must use a version that matches the exact same `std` as the one used in CI (for which we vendor the crates):

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

<h2 id="build-clickhouse">
  Build ClickHouse
</h2>

We recommend to create a separate directory `build` inside `ClickHouse` which contains all build artifacts:

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

You can have several different directories (e.g. `build_release`, `build_debug`, etc.) for different build types.

Optional: If you have multiple compiler versions installed, you can optionally specify the exact compiler to use.

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

For development purposes, debug builds are recommended.
Compared to release builds, they have a lower compiler optimization level (`-O`) which provides a better debugging experience.
Also, internal exceptions of type `LOGICAL_ERROR` crash immediately instead of failing gracefully.

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

<Note>
  If you wish to use a debugger such as gdb, add `-D DEBUG_O_LEVEL="0"` to the above command to remove all compiler optimizations, which can interfere with gdb's ability to view/access variables.
</Note>

Run ninja to build:

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

If you like to build all the binaries (utilities and tests), run ninja without parameters:

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

You can control the number of parallel build jobs using parameter `-j`:

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

<Note>
  `clickhouse-server`, `clickhouse-client`, and similar binaries are symbolic links in the `programs/` directory that point to the `clickhouse` executable after the build is completed.

  :::tip
  CMake provides shortcuts for above commands:

  ```sh theme={null}
  cmake -S . -B build  # configure build, run from repository top-level directory
  cmake --build build  # compile
  ```
</Note>

<h2 id="running-the-clickhouse-executable">
  Running the ClickHouse Executable
</h2>

After the build completed successfully, you find the executable in `ClickHouse/<build_dir>/programs/`:

The ClickHouse server tries to find a configuration file `config.xml` in the current directory.
You can alternative specify a configuration file on the command-line via `-C`.

To connect to the ClickHouse server with `clickhouse-client`, open another terminal, navigate to `ClickHouse/build/programs/` and run `./clickhouse client`.

If you get `Connection refused` message on macOS or FreeBSD, try specifying host address 127.0.0.1:

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

<h2 id="advanced-options">
  Advanced options
</h2>

<h3 id="minimal-build">
  Minimal Build
</h3>

If you don't need functionality provided by third-party libraries, you can speed the build further up:

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

In case of problems, you are on your own ...

Rust requires an internet connection. To disable Rust support:

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

<h3 id="running-the-clickhouse-executable-1">
  Running the ClickHouse Executable
</h3>

You can replace the production version of ClickHouse binary installed in your system with the compiled ClickHouse binary.
To do that, install ClickHouse on your machine following the instructions from the official website.
Next, run:

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

Note that `clickhouse-client`, `clickhouse-server` and others are symlinks to the commonly shared `clickhouse` binary.

You can also run your custom-built ClickHouse binary with the config file from the ClickHouse package installed on your system:

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

<h3 id="building-on-any-linux">
  Building on Any Linux
</h3>

Install prerequisites on 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
```

Install prerequisites on 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
```

<h3 id="building-in-docker">
  Building in docker
</h3>

You can run any build locally in an environment similar to CI using:

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

where BUILD\_JOB\_NAME is the job name as shown in the CI report, e.g., "Build (arm\_release)", "Build (amd\_debug)"

This command pulls the appropriate Docker image `clickhouse/binary-builder` with all required dependencies,
and runs the build script inside it: `./ci/jobs/build_clickhouse.py`

The build output will be placed in `./ci/tmp/`.

It works on both AMD and ARM architectures and requires no additional dependencies other than Python with `requests` module available and Docker.