Getting started

Prerequisites

• A C++17 compiler: GCC 7+, Clang 6+, or MSVC 2019+.
• CMake 3.5 or newer.
• Python 3 (used by build/codegen scripts and the test runner).
• Optional: Ninja (GEN=ninja make) and ccache for faster builds.

Clone and build

git clone https://github.com/duckdb/duckdb.git
cd duckdb

# Default release build (single-threaded link can be slow; see tips below)
make

# Recommended for development - optimized but with debug symbols and extra checks
make reldebug

# Slow but most diagnostic
make debug

# Force assertions and sanitizers on top of an optimized build
FORCE_DEBUG=1 make relassert

Common knobs:

Variable	Effect
GEN=ninja	Use Ninja instead of Make.
CMAKE_BUILD_PARALLEL_LEVEL=$(nproc)	Parallelize the build.
BUILD_ALL_EXT=1	Build all in-tree extensions.
DUCKDB_EXTENSIONS='json;icu'	Build a specific subset of extensions.
BUILD_TPCH=1 BUILD_TPCDS=1	Include TPC-H/TPC-DS data generators.
BUILD_BENCHMARK=1	Build the benchmark runner.

The full list lives in Makefile and CMakeLists.txt.

Run the CLI

build/release/duckdb           # release build
build/reldebug/duckdb          # reldebug build

This drops you into the DuckDB shell (tools/shell/shell.cpp). See tools/cli-shell for shell features.

Run the tests

# Fast unit tests (sqllogictest + C++ tests, ~minutes)
make unit
# or directly:
build/reldebug/test/unittest

# Run a specific test file
build/reldebug/test/unittest test/sql/order/test_limit.test

# Run everything including .test_slow
build/reldebug/test/unittest "*"
make allunit

Test format documentation is at test/README.md and the official site (https://duckdb.org/dev/testing). See how-to-contribute/testing.

Run a benchmark

BUILD_BENCHMARK=1 BUILD_TPCH=1 make
./build/release/benchmark/benchmark_runner

Benchmarks live in benchmark/. The TPC-H/TPC-DS data generators ship as in-tree extensions (extension/tpch/, extension/tpcds/).

Format your changes before committing

make format-fix

This runs clang-format (version 11.0.1 is required for byte-identical output; install via pipx install clang-format==11.0.1) and black over the touched files. The CI rejects unformatted code.

Regenerate generated files

Some files are generated from JSON specs and .gram files. After modifying any generator input, run:

make generate-files

This refreshes the C API headers (src/include/duckdb.h), serialization code, function lists, settings, and enum utilities. The generators live in scripts/generate_*.py and src/include/duckdb/storage/serialization/.

Build with extensions

# Just parquet + json
DUCKDB_EXTENSIONS='parquet;json' make
# Everything in-tree
BUILD_ALL_EXT=1 make

The list of in-tree extensions is in .github/config/in_tree_extensions.cmake. Out-of-tree extensions (HTTP, AWS, postgres scanner, etc.) live in their own repositories and are listed in .github/config/out_of_tree_extensions.cmake. See extensions.

Where to go next

• How a query runs — pipeline overview.
• Patterns and conventions — coding rules.
• Testing — sqllogictest cookbook.
• Debugging — what to do when something breaks.