Building Extensions

How to build DuckDB extensions from source

Overview

All DuckDB extensions, whether in-tree or out-of-tree, are built using the same underlying mechanism:

1. DuckDB’s root CMakeLists.txt serves as the root CMake file
2. Extensions to build are passed as parameters
3. Each extension can be configured for different build modes (loadable binary, statically linked, etc.)

Build Methods

There are several ways to specify which extensions to build when compiling DuckDB.

Using Makefile Variables

The simplest method uses the DUCKDB_EXTENSIONS variable with a semicolon-separated list:

DUCKDB_EXTENSIONS='json;icu' make

Using CMake Directly

You can also pass extensions directly to CMake:

cmake -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_EXTENSIONS='parquet;icu;tpch;tpcds;fts;json'
make

Using Build Variables

For convenience, you can use individual build variables:

BUILD_JSON=1 make
BUILD_ICU=1 BUILD_PARQUET=1 make

These variables are defined in the root Makefile and are syntactic sugar around the DUCKDB_EXTENSIONS variable.

Extension Configuration Files

For more control over how extensions are built, use extension configuration files. These are CMake files that control extension loading.

Configuration File Locations

DuckDB searches for configuration files in this order (later files override earlier ones):

1. Base configuration

   extension/extension_config.cmake

   Extensions specified here are built every time DuckDB is built. This configuration is always loaded.

2. Client-specific configuration (optional)

   tools/*/duckdb_extension_config.cmake

   Specifies which extensions are built and linked into each client (CLI, Python, etc.).

3. Local configuration (optional)

   extension/extension_config_local.cmake

   Your personal configuration for custom/dev builds. This file is gitignored and should be created by you.

4. Additional configs (optional)

   Passed via DUCKDB_EXTENSION_CONFIGS

   Additional configuration files can be specified to point to configs anywhere on your machine.

Configuration Priority

DuckDB loads these files in reverse order, ignoring subsequent attempts to load an extension with the same name. This allows you to override the base configuration with local settings.

The duckdb_extension_load Function

The duckdb_extension_load() function is used in configuration files to specify how extensions should be loaded.

Automatic Loading

The simplest form automatically locates and loads an extension:

duckdb_extension_load(json)

This searches the ./extension and ./extension_external directories for the extension.

Don’t Link Option

To build the loadable extension binary without statically linking it:

duckdb_extension_load(json DONT_LINK)

Custom Path

Specify a custom location for the extension:

duckdb_extension_load(my_extension
    SOURCE_DIR /absolute/path/to/extension/root
    INCLUDE_DIR /absolute/path/to/extension/header
    DONT_LINK
)

The INCLUDE_DIR parameter is optional.

Load from GitHub

Directly install and build an extension from a GitHub repository:

duckdb_extension_load(postgres_scanner
    GIT_URL https://github.com/duckdb/postgres_scanner
    GIT_TAG cd043b49cdc9e0d3752535b8333c9433e1007a48
    DONT_LINK
)

This downloads the extension to the CMake build directory and builds it from there.

Explicitly Disable Extensions

To override and disable an extension enabled in another config:

duckdb_extension_load(parquet DONT_BUILD)

You can also disable extensions from the Makefile:

DUCKDB_EXTENSIONS='tpch;json' SKIP_EXTENSIONS=parquet make

Example Workflows

Override Default Extension Configuration

By default, the parquet extension is statically linked because of this line in extension/extension_config.cmake:

duckdb_extension_load(parquet)

To build DuckDB with a custom parquet extension that’s only a loadable binary (not statically linked):

1. Create local configuration

   Create extension/extension_config_local.cmake:

   duckdb_extension_load(parquet
       DONT_LINK
       SOURCE_DIR /path/to/my/custom/parquet
   )
   
2. Build DuckDB

   make
   

   CMake will output:

   -- Building extension 'parquet' from '/path/to/my/custom/parquet'
   -- Extensions built but not linked: parquet
   

Build Multiple Extensions

1. Set extensions to build

   cmake -DCMAKE_BUILD_TYPE=Release \
     -DBUILD_EXTENSIONS='parquet;json;icu;httpfs'
   
2. Compile

   make -j4
   
3. Find built extensions

   Loadable extensions will be in the build directory:

   ls build/release/extension/*/*.duckdb_extension
   

Build Out-of-Tree Extension

To build an out-of-tree extension based on the extension-template:

1. Place extension in extension_external

   Clone or copy the extension to extension_external/:

   cd duckdb
   mkdir -p extension_external
   git clone https://github.com/yourname/your_extension extension_external/your_extension
   
2. Configure build

   Create extension/extension_config_local.cmake:

   duckdb_extension_load(your_extension)
   
3. Build

   make
   

   Extensions in extension_external/ are automatically discovered when using automatic loading.

Build Extension from GitHub

1. Configure to load from GitHub

   Create extension/extension_config_local.cmake:

   duckdb_extension_load(spatial
       GIT_URL https://github.com/duckdb/duckdb_spatial
       GIT_TAG main
   )
   
2. Build DuckDB

   make
   

   The extension will be downloaded and built automatically.

VCPKG Dependency Management

DuckDB extensions can use VCPKG to manage their dependencies. See the Extension Template for setup examples.

Building Multiple Extensions with VCPKG

When building DuckDB with multiple extensions that use VCPKG, you need to merge their dependency manifests:

1. Configure extensions

   Add extensions to extension/extension_config_local.cmake:

   duckdb_extension_load(extension_1
       GIT_URL https://github.com/example/extension_1
       GIT_TAG some_git_hash
   )
   duckdb_extension_load(extension_2
       GIT_URL https://github.com/example/extension_2
       GIT_TAG some_git_hash
   )
   
2. Merge VCPKG manifests

   make extension_configuration
   

   This creates a merged manifest in ./build/extension_configuration/vcpkg.json.

3. Build with merged manifest

   USE_MERGED_VCPKG_MANIFEST=1 \
     VCPKG_TOOLCHAIN_PATH="/path/to/vcpkg" \
     make
   

   This installs all dependencies, builds both extensions, and links them into DuckDB.

Build Output

After building, you’ll see output indicating which extensions were built:

-- Building extension 'tpch' from '/Users/sam/Development/duckdb/extension'
-- Building extension 'json' from '/Users/sam/Development/duckdb/extension'
-- Extensions linked into DuckDB: tpch, json
-- Extensions built but not linked: parquet

Testing Your Extension

After building a loadable extension:

-- Load from build directory
LOAD './build/release/extension/my_extension/my_extension.duckdb_extension';

-- Verify it loaded
SELECT * FROM duckdb_extensions() WHERE extension_name = 'my_extension';

Next Steps

Extension Template

Start building your own extension using the official template

Core Extensions

Study the source code of built-in extensions

Loading Extensions

Learn how to load your built extension