Environment:Duckdb Duckdb CMake Build Toolchain

Knowledge Sources	DuckDB CMake Documentation
Domains	Infrastructure, Build_System
Last Updated	2026-02-07 12:00 GMT

Overview

Linux/macOS/Windows build environment with CMake 3.5+, C++11 compiler (GCC 8+ or Clang 9+), Python 3, and optional ccache/sccache for compilation caching.

Description

This environment defines the core build toolchain required to compile DuckDB from source. It is centered on the CMake build system with a minimum version of 3.5 (up to policy 3.29). The project requires a C++11-compliant compiler with position-independent code support. The build system auto-detects and uses ccache or sccache if available, supports unity builds by default, and handles cross-platform compilation for Linux, macOS, Windows, and WebAssembly targets. Supported architectures include amd64, arm64 (aarch64), and i386 (via FORCE_32_BIT).

Usage

Use this environment for all DuckDB compilation workflows: building from source, running unit tests, building benchmarks, and compiling extensions. This is the mandatory prerequisite for every Implementation page in the Building_From_Source workflow.

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 18.04+), macOS 11.0+, or Windows	BSD unofficially supported (see comment: "sorry BSD" in CMakeLists.txt:164)
Hardware	x86_64 (amd64) or ARM64 (aarch64) CPU	32-bit via FORCE_32_BIT flag; universal binaries on macOS
Disk	2GB+ free space	Unity builds require less disk I/O; debug builds need more
Threads	POSIX threads (pthread)	`find_package(Threads REQUIRED)` in CMakeLists.txt:25

Dependencies

System Packages

`cmake` >= 3.5 (policies up to 3.29 supported)
`make` or `ninja` (Ninja recommended for parallel builds)
C++ compiler: GCC >= 8.0 or Clang >= 9.0
`git` (for version detection; fallback to dummy v0.0.1 if unavailable)
`ccache` or `sccache` (optional, auto-detected for faster rebuilds)

Language Runtime

C++11 standard (enforced via `CMAKE_CXX_STANDARD_REQUIRED ON`)
Python 3 (required for code generation scripts and extension repository builds)

Credentials

No credentials are required for basic compilation. The build system uses only local tools.

Quick Install

# Ubuntu/Debian
sudo apt-get install -y build-essential cmake git python3 ninja-build ccache

# macOS
brew install cmake ninja ccache python3

# Build DuckDB
make                    # release build
GEN=ninja make          # faster parallel build with Ninja
make debug              # debug build with sanitizers

Code Evidence

CMake minimum version from `CMakeLists.txt:1`:

cmake_minimum_required(VERSION 3.5...3.29)

C++11 standard enforcement from `CMakeLists.txt:31-34`:

set(CMAKE_CXX_STANDARD "11" CACHE STRING "C++ standard to enforce")

set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

Automatic compiler launcher detection from `CMakeLists.txt:41-59`:

if(NOT DEFINED CMAKE_C_COMPILER_LAUNCHER)
    find_program(COMPILER_LAUNCHER NAMES ccache sccache)
    if(COMPILER_LAUNCHER)
        message(STATUS "Using ${COMPILER_LAUNCHER} as C compiler launcher")
        set(CMAKE_C_COMPILER_LAUNCHER
                "${COMPILER_LAUNCHER}"
                CACHE STRING "" FORCE)
    endif()
endif()

Platform and architecture detection from `CMakeLists.txt:149-167`:

set(OS_NAME "unknown")
set(OS_ARCH "amd64")

string(REGEX MATCH "(arm64|aarch64)" IS_ARM "${CMAKE_SYSTEM_PROCESSOR}")
if(IS_ARM)
  set(OS_ARCH "arm64")
elseif(FORCE_32_BIT)
  set(OS_ARCH "i386")
endif()

if(APPLE)
  set(OS_NAME "osx")
elseif(WIN32)
  set(OS_NAME "windows")
elseif(UNIX)
  set(OS_NAME "linux") # sorry BSD
endif()

Common Errors

Error Message	Cause	Solution
`CMake Error: CMake minimum required is 3.5`	CMake version too old	Upgrade CMake: `pip install cmake` or download from cmake.org
`git has failed to execute 'describe --tags --long'`	Shallow git clone without tags	Run `git fetch --tags` or provide `OVERRIDE_GIT_DESCRIBE=vX.Y.Z`
`Git NOT FOUND`	Git not installed	Install git, or set `OVERRIDE_GIT_DESCRIBE` explicitly
System lockup during build	Too many parallel jobs for available RAM	Set `CMAKE_BUILD_PARALLEL_LEVEL=4 GEN=ninja make`

Compatibility Notes

macOS Universal Builds: Set `OSX_BUILD_UNIVERSAL=1` to build fat binaries (x86_64 + arm64). Requires macOS 11.0+ deployment target.
Windows: Uses MSVC runtime (`MultiThreaded` / `MultiThreadedDebug`). Jemalloc extension not supported on Windows.
MUSL (Alpine Linux): Set `DUCKDB_PLATFORM=linux_amd64_musl` environment variable to enable MUSL-specific compilation flags.
WebAssembly: Enable with `WASM_EXTENSIONS` environment variable. Thread support via `USE_WASM_THREADS` option.
SunOS (Solaris): Adds `-mimpure-text` flag automatically when detected.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment