Skip to main content
Este guia de compilação é destinado a colaboradores que modificam o próprio ClickHouse.Se você não estiver alterando o código-fonte do ClickHouse, poderá instalar o ClickHouse pré-compilado conforme descrito no Quick Start.
O ClickHouse pode ser compilado nas seguintes plataformas:
  • x86_64
  • AArch64
  • PowerPC 64 LE (experimental)
  • s390/x (experimental)
  • RISC-V 64 (experimental)

​
Premissas

O tutorial a seguir é baseado no Ubuntu Linux, mas também deve funcionar em qualquer outra distribuição Linux, com os ajustes apropriados. A versão mínima recomendada do Ubuntu para desenvolvimento é a 24.04 LTS. O tutorial pressupõe que você já tenha o repositório do ClickHouse e todos os submódulos clonados localmente.

​
Instale os pré-requisitos

Primeiro, consulte a documentação geral de pré-requisitos. O ClickHouse usa CMake e Ninja para compilação. Opcionalmente, você pode instalar o ccache para que a compilação reutilize arquivos-objeto já compilados.

​
Instale o compilador Clang

Para instalar o Clang no Ubuntu/Debian, use o script de instalação automática do LLVM disponível aqui.
Para outras distribuições Linux, verifique se é possível instalar algum dos pacotes pré-compilados do LLVM. A partir de fevereiro de 2026, é necessário usar o Clang 21 ou superior. GCC e outros compiladores não têm suporte.

​
Instale o compilador Rust (opcional)

Rust é uma dependência opcional do ClickHouse. Se o Rust não estiver instalado, alguns recursos do ClickHouse serão omitidos da compilação.
Primeiro, siga as instruções da documentação oficial do Rust para instalar o rustup. Assim como acontece com as dependências de C++, o ClickHouse usa vendoring para controlar exatamente o que é instalado e evitar depender de serviços de terceiros (como o registry crates.io). Embora, no modo release, qualquer versão moderna da toolchain do rustup deva funcionar com essas dependências, se você pretende habilitar sanitizers, deverá usar uma versão que corresponda exatamente ao mesmo std usado na CI (para a qual incluímos os crates via vendoring):

​
Compilação do ClickHouse

Recomendamos criar um diretório build separado dentro de ClickHouse, que contenha todos os artefatos da compilação:
Você pode ter vários diretórios diferentes (por exemplo, build_release, build_debug etc.) para diferentes tipos de compilação. Opcional: se você tiver várias versões de compilador instaladas, poderá especificar exatamente qual compilador usar.
Para desenvolvimento, recomenda-se o uso de compilações de depuração. Em comparação com as compilações de lançamento, elas têm um nível de otimização do compilador (-O) mais baixo, o que proporciona uma experiência de depuração melhor. Além disso, exceções internas do tipo LOGICAL_ERROR fazem o processo encerrar imediatamente, em vez de falhar de forma controlada.
Se quiser usar um depurador como o gdb, adicione -D DEBUG_O_LEVEL="0" ao comando acima para remover todas as otimizações do compilador, o que pode interferir na capacidade do gdb de visualizar/acessar variáveis.
Execute ninja para compilar:
Se quiser compilar todos os binários (utilitários e testes), execute ninja sem parâmetros:
Você pode controlar o número de jobs de compilação paralelos usando o parâmetro -j:
clickhouse-server, clickhouse-client e binários semelhantes são links simbólicos no diretório programs/ que apontam para o executável clickhouse após a conclusão da compilação.
O CMake fornece atalhos para os comandos acima:

​
Executando o executável do ClickHouse

Após a compilação ser concluída com sucesso, o executável estará em ClickHouse/<build_dir>/programs/: O servidor ClickHouse tenta localizar um arquivo de configuração config.xml no diretório atual. Como alternativa, você pode especificar um arquivo de configuração na linha de comando com -C. Para se conectar ao servidor ClickHouse com clickhouse-client, abra outro terminal, vá até ClickHouse/build/programs/ e execute ./clickhouse client. Se aparecer a mensagem Connection refused no macOS ou FreeBSD, tente especificar o endereço de host 127.0.0.1:

​
Opções avançadas

​
Compilação mínima

Se você não precisa da funcionalidade oferecida por bibliotecas de terceiros, pode acelerar ainda mais a compilação:
Em caso de problemas, você estará por conta própria … O Rust requer uma conexão com a internet. Para desativar o suporte ao Rust:

​
Executando o executável do ClickHouse

Você pode substituir a versão do ClickHouse em produção instalada no seu sistema pelo binário compilado do ClickHouse. Para fazer isso, instale o ClickHouse na sua máquina seguindo as instruções do site oficial. Em seguida, execute:
Observe que clickhouse-client, clickhouse-server e outros são links simbólicos para o binário compartilhado clickhouse. Você também pode executar sua versão personalizada do binário do ClickHouse com o arquivo de config do pacote ClickHouse instalado no seu sistema:

​
Compilação em qualquer distribuição Linux

Instale os pré-requisitos no OpenSUSE Tumbleweed:
Instale os pré-requisitos no Fedora Rawhide:

​
Compilação com Docker

Você pode executar qualquer compilação localmente em um ambiente semelhante ao de CI usando:
em que BUILD_JOB_NAME é o nome do job, conforme exibido no relatório de CI, por exemplo, “Build (arm_release)”, “Build (amd_debug)” Este comando baixa a imagem Docker adequada clickhouse/binary-builder com todas as dependências necessárias e executa o script de compilação dentro dela: ./ci/jobs/build_clickhouse.py A saída da compilação será gerada em ./ci/tmp/. Funciona em arquiteturas AMD e ARM e não requer dependências adicionais além de Python com o módulo requests disponível e Docker.
Última modificação em 23 de julho de 2026