Skip to main content
Skip to main content
Edit this page

How to Build ClickHouse on Linux

You don't have to build ClickHouse yourself!

You can install pre-built ClickHouse as described in Quick Start.

ClickHouse can be build on the following platforms:

  • x86_64
  • AArch64
  • PowerPC 64 LE (experimental)
  • s390/x (experimental)
  • RISC-V 64 (experimental)

Assumptions​

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.

Install Prerequisites​

ClickHouse uses CMake and Ninja for building.

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

Install the Clang compiler​

To install Clang on Ubuntu/Debian, use LLVM's automatic installation script from here.

For other Linux distributions, check if you can install any of LLVM's prebuild packages.

As of January 2025, Clang 18 or higher is required. GCC or other compilers are not supported.

Install the Rust compiler (optional)​

Note

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

First, follow the steps in the official Rust documentation 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):

Build ClickHouse​

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

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.

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.

Run ninja to build:

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

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

Tip

CMake provides shortcuts for above commands:

Running the ClickHouse Executable​

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:

Advanced Options​

Minimal Build​

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

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

Rust requires an internet connection. To disable Rust support:

Running the ClickHouse Executable​

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:

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:

Building on Any Linux​

Install prerequisites on OpenSUSE Tumbleweed:

Install prerequisites on Fedora Rawhide:

Building in docker​

We use the docker image clickhouse/binary-builder for builds in CI. It contains everything necessary to build the binary and packages. There is a script docker/packager/packager to ease the image usage: