Skip to main content
If you like Apache Cloudberry (Incubating), give it a star on GitHub!
Version: 2.x

Configure Apache Cloudberry Build

Pre-stage the Python packages for --with-pythonsrc-ext​

note

This step is only required starting from Apache Cloudberry 2.2.

The Python source packages used by --with-pythonsrc-ext are not bundled in the repository. They have been removed since Apache Cloudberry 2.0 to comply with the Apache release policy, and used to be downloaded on the fly during the build. Starting from Apache Cloudberry 2.2, they are downloaded ahead of the build instead, so pre-stage them before you run configure.

Building PyYAML requires Cython earlier than 3.0. On Ubuntu, install the matching distribution package first:

# For Ubuntu 22.04, cython3 is 0.29.x
sudo apt install -y cython3

# For Ubuntu 24.04, cython3 is 3.x and cannot build PyYAML, so use cython3-legacy instead
sudo apt install -y cython3-legacy

On Rocky Linux 8 and 9, python3-Cython has already been installed in Install required packages. On Rocky Linux 10, the distribution only ships Cython 3.x, so the following command installs a compatible version through pip3 for you.

Then download the packages:

cd ~/cloudberry
make -C gpMgmt/bin download-python-deps

Configure the build process​

Prepare environment​

The build process requires the necessary libraries (e.g., Xerces-C) to be available at the expected locations for configuration and runtime. Prepare the environment using the following commands:

sudo rm -rf /usr/local/cloudberry-db
sudo chmod a+w /usr/local
mkdir -p /usr/local/cloudberry-db/lib
sudo cp -v /usr/local/xerces-c/lib/libxerces-c.so \
           /usr/local/xerces-c/lib/libxerces-c-3.*.so \
           /usr/local/cloudberry-db/lib
sudo chown -R gpadmin:gpadmin /usr/local/cloudberry-db

Run configure​

The configure command sets up the build environment for Apache Cloudberry. This configuration includes several development features and extensions.

note

Starting from Apache Cloudberry 2.2, new extensions are available, including diskquota, gp_stats_collector, and yezzey. Use the corresponding configure options to enable them.

cd ~/cloudberry
export LD_LIBRARY_PATH=/usr/local/cloudberry-db/lib:${LD_LIBRARY_PATH:-""}
./configure --prefix=/usr/local/cloudberry-db \
            --disable-external-fts \
            --enable-gpcloud \
            --enable-ic-proxy \
            --enable-mapreduce \
            --enable-orafce \
            --enable-orca \
            --enable-pax \
            --disable-pxf \
            --enable-tap-tests \
            --with-diskquota \
            --with-gp-stats-collector \
            --with-gssapi \
            --with-ldap \
            --with-libxml \
            --with-lz4 \
            --with-pam \
            --with-perl \
            --with-pgport=5432 \
            --with-python \
            --with-pythonsrc-ext \
            --with-ssl=openssl \
            --with-uuid=e2fs \
            --with-yezzey \
            --with-includes=/usr/local/xerces-c/include \
            --with-libraries=/usr/local/cloudberry-db/lib

configure options​

The configure script is used to prepare the build environment for Apache Cloudberry. It checks for required libraries and sets up the necessary configuration options.

You can run ./configure --help to see a full list of options available for configuring Apache Cloudberry. Below is a list of commonly used options with their descriptions and notes.

note

The build dependencies vary based on which features you enable or disable during configuration. While we've listed the basic required packages in the previous section, you may need additional packages depending on your configuration choices. When you run the ./configure command, it will check and report any missing dependencies that you'll need to install before proceeding with the build.

Also, some packages names vary between different Linux distributions.

OptionDescriptionNotes
--prefix=PREFIXInstallation directory. /usr/local/cbdb is the default value. make install will install all the files in /usr/local/cbdb/bin, /usr/local/cbdb/lib etc.You can specify an installation prefix other than /usr/local/cbdb using --prefix. In this guide, we use /usr/local/cloudberry-db as the installation directory.
--disable-gpfdistDo not use gpfdistEnable gpfdist by default. This requires apr lib and libevent to be installed.
--disable-pxfDo not build PXF.Enable PXF by default. PXF is a query federation engine that accesses data residing in external systems such as Hadoop, Hive, HBase, relational databases, S3, Google Cloud Storage, among other external systems. Now the cloudberry-pxf will be kept as the latest version of pxf_fdw.
--enable-orafceBuild with Oracle compatibility functions.
--enable-debugBuild all programs and libraries with debugging symbols.This means that you can run the programs in a debugger to analyze problems. This enlarges the size of the installed executables considerably, and on non-GCC compilers it usually also disables compiler optimization, causing slowdowns. However, having the symbols available is extremely helpful for dealing with any problems that might arise. Currently, this option is recommended for production installations only if you use GCC. But you should always have it on if you are doing development work or running a beta version.
--enable-profilingBuild with profiling enabled.This option is for use only with GCC and when doing development work.
--enable-tap-testsEnable tests using the Perl TAP tools.This requires Perl and Perl module IPC::Run to be installed.
--enable-cassertEnable assertion checks (for debugging)Enables assertion checks in the server, which test for many “cannot happen” conditions. This is invaluable for code development purposes, but the tests can slow down the server significantly. This option is not recommended for production use, but you should have it on for development work or when running a beta version.
--disable-orcaDisable ORCA optimizerORCA is enabled by default. ORCA requires xerces-c library to be installed.
--enable-mapreduceEnable Cloudberry Mapreduce supportThis requires libyaml to be installed.
--enable-gpcloudEnable gpcloud support
--enable-external-ftsEnable external fts support
--enable-ic-proxyEnable interconnect proxy modeThis requires libuv library to be installed.
--enable-paxEnable PAX supportgcc/gcc-c++ 11+, cmake3, protobuf and ZSTD are required, see details here.
--with-includes=DIRSLook for additional header files in DIRSThe Xerces-C is required to build with ORCA.
--with-libraries=DIRSLook for additional libraries in DIRSThe library xerces-c is required to build with ORCA
--with-pgport=PORTNUMSet default port number [5432]--with-pgport=5432 is used in this guide.
--with-llvmBuild with LLVM based JIT supportThis requires the LLVM library to be installed.
--with-icuBuild with ICU supportThis requires the ICU4C package to be installed.
--with-perlBuild Perl modules (PL/Perl)This requires Perl devel packages to be installed.
--with-pythonBuild Python modules (PL/Python)This requires Python3 devel packages to be installed.
--with-pythonsrc-extBuild Python modules for gpMgmtRecommended options. It's used for gpMgmt tools. This option requires curl, python3, and python3-pip to be installed; curl is used for downloading the needed Python3 packages, and python3-pip is used for installing the Python packages for building PyYaml. If you don't build with this option, after installing Cloudberry you will need to install the specific Python packages from the Linux distros: psutil, pygresql, pyyaml, or run the command at the top directory pip3 install -r python-dependencies.txt.
--with-gssapiBuild with GSSAPI supportThe GSSAPI system is usually a part of the Kerberos installation, so this requires the krb5 package to be installed.
--with-pamBuild with PAM (Pluggable Authentication Modules) support.This requires the PAM package to be installed.
--with-ldapBuild with LDAP support for authentication and connection parameter lookup.This requires the OpenLDAP package to be installed.
--with-uuid=LIBBuild contrib/uuid-ossp module using LIB (bsd,e2fs,ossp).
  • bsd to use the UUID functions found in FreeBSD and some other BSD-derived systems
  • e2fs to use the UUID library created by the e2fsprogs project; this library is present in most Linux systems and in macOS, and can be obtained for other platforms as well
  • ossp to use the OSSP UUID library
So we use --with-uuid=e2fs in the build under Linux/macOS - this requires the uuid library to be installed.
--with-libxmlBuild with libxml2, enabling SQL/XML support.This requires libxml2 to be installed.
--with-lz4Build with LZ4 compression supportThis allows the use of LZ4 for compression of table data and lz4 library is required to be installed.
--with-ssl=LIBBuild with support for SSL (encrypted) connections.The only LIBRARY supported is openssl, so --with-ssl=openssl is used in this guide. This requires the OpenSSL package to be installed.
--with-diskquotaBuild with diskquota extension.Diskquota is an extension that provides disk usage enforcement for database objects in Apache Cloudberry. Since Cloudberry 2.2
--with-gp-stats-collectorBuild with stats collector extension.An extension for collecting query execution metrics and reporting them to an external agent. Since Cloudberry 2.2
--with-yezzeyBuild with Yezzey extension.Yezzey is an extension for offloading data from Cloudberry to S3-compatible external storage. This option builds the extension only. You do not need a proxy if there are only a few requests to S3, but many parallel data exchange streams can exhaust CPU and network on the cluster host. For better performance under heavy traffic, additionally deploy YProxy, which pools connections to S3 and schedules the requests. Since Cloudberry 2.2
Support
GitHub Issues
GitHub Discussions
Slack
Discord
Twitter
Youtube
Security
Resources
Download
Documentation
Events
Brand Guidelines
Powered By
Contribution
Working with Git & GitHub
Contribution Overview
Code Contribution
Doc Contribution

Apache Cloudberry is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

Copyright © 2026 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.

Apache®, the names of Apache projects, and the feather logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.