Implementation:Duckdb Duckdb Duckdb Extension Load

Field	Value
source	DuckDB Repository
domains	Build_System, Modularity
last_updated	2026-02-07

Overview

Concrete tool for registering and configuring DuckDB extensions in the CMake build system.

Description

The duckdb_extension_load() CMake function is the primary mechanism for registering extensions within the DuckDB build system. It is defined in extension/extension_build_tools.cmake and serves as the central entry point through which all DuckDB extensions are declared, configured, and integrated into the build.

When invoked, the function registers an extension by name, optionally fetches its source code from a remote Git repository, configures its build targets, and wires it into the broader DuckDB CMake build graph. Extensions can be built as statically linked components (compiled directly into the DuckDB binary) or as loadable extensions (separate shared libraries loaded at runtime).

The function is typically called from two configuration files:

• extension/extension_config.cmake -- The default extension configuration shipped with DuckDB. This file lists the core extensions that are always included (e.g., core_functions, parquet) and conditionally included extensions (e.g., jemalloc on Linux).
• extension/extension_config_local.cmake -- An optional local override file that developers can create to add or modify extensions for their personal builds. This file is not checked into version control.

Code Reference

Source location: extension/extension_build_tools.cmake:L414-503

Function signature:

function(duckdb_extension_load NAME)
    set(options DONT_LINK DONT_BUILD LOAD_TESTS APPLY_PATCHES)
    set(oneValueArgs SOURCE_DIR INCLUDE_DIR TEST_DIR GIT_URL GIT_TAG SUBMODULES EXTENSION_VERSION LINKED_LIBS)
    cmake_parse_arguments(duckdb_extension_load "${options}" "${oneValueArgs}" "" ${ARGN})

Parameters:

Parameter	Type	Required	Description
NAME	string	Yes	The name of the extension to register. This becomes the build target name and is added to the global DUCKDB_EXTENSION_NAMES list.
DONT_LINK	flag	No	When set, the extension is not linked into the main DuckDB binary. Instead, it is built only as a loadable extension (.duckdb_extension file).
DONT_BUILD	flag	No	When set, the extension is registered but not built. Useful for declaring extensions that are built externally or conditionally.
LOAD_TESTS	flag	No	When set, the extension's test directory is included in the build, enabling its tests to be run as part of the DuckDB test suite.
APPLY_PATCHES	flag	No	When set, patches from .github/patches/extensions/{NAME}/ are applied to the extension source after checkout.
SOURCE_DIR	path	No	Path to a local directory containing the extension source code. Mutually exclusive with GIT_URL.
INCLUDE_DIR	path	No	Custom include directory for the extension. Overrides the default include path derived from the source directory.
TEST_DIR	path	No	Custom test directory for the extension. Overrides the default test path. Only relevant when LOAD_TESTS is set.
GIT_URL	string	No	URL of a remote Git repository containing the extension source code. When specified, the build system clones this repository during configuration.
GIT_TAG	string	No	Git ref (branch, tag, or commit hash) to check out from the remote repository. Only relevant when GIT_URL is set.
SUBMODULES	string	No	Git submodules to initialize within the extension repository after cloning.
EXTENSION_VERSION	string	No	Explicit version string for the extension. Overrides automatic version detection.
LINKED_LIBS	string	No	Additional libraries to link against when building the extension. Used for extensions that depend on external system libraries.

I/O Contract

Direction	Description
Inputs	The function reads extension declarations from extension/extension_config.cmake (the default configuration) and optionally from extension/extension_config_local.cmake (a local override file). Each invocation receives the extension name and its configuration parameters as arguments.
Outputs	The function populates the CMake variable DUCKDB_EXTENSION_NAMES with the registered extension name and creates per-extension build targets. For extensions with GIT_URL set, it triggers a Git clone/checkout during the CMake configure step. The resulting build targets produce either statically linked object code or loadable .duckdb_extension shared libraries depending on the DONT_LINK flag.

Default extensions declared in extension_config.cmake:

Extension	Condition	Linking
core_functions	Always included	Statically linked
parquet	Always included	Statically linked
jemalloc	Linux only (NOT APPLE AND NOT WIN32)	Statically linked

Usage Examples

Example 1: Loading a local extension from a source directory

# In extension/extension_config_local.cmake
# Load the spatial extension from a local checkout
duckdb_extension_load(spatial
    SOURCE_DIR /home/developer/duckdb-spatial
    INCLUDE_DIR /home/developer/duckdb-spatial/include
    LOAD_TESTS
)

This registers the spatial extension, pointing at a local source directory. The LOAD_TESTS flag ensures the extension's tests are included in the build. Because DONT_LINK is not set, the extension will be statically linked into the DuckDB binary.

Example 2: Loading a remote extension from a Git repository

# In extension/extension_config_local.cmake
# Load the httpfs extension from the official repository
duckdb_extension_load(httpfs
    GIT_URL https://github.com/duckdb/duckdb-httpfs.git
    GIT_TAG v0.10.0
    LOAD_TESTS
    APPLY_PATCHES
)

This fetches the httpfs extension from its Git repository at the specified tag, applies any patches found in .github/patches/extensions/httpfs/, and includes its tests in the build.

Example 3: Loading an extension as a loadable-only module

# Build the extension as a loadable .duckdb_extension file
# without linking it into the main binary
duckdb_extension_load(my_custom_extension
    SOURCE_DIR ${CMAKE_SOURCE_DIR}/../my-custom-ext
    DONT_LINK
    LINKED_LIBS "libcustom;libhelper"
    EXTENSION_VERSION "1.2.3"
)

This builds my_custom_extension as a standalone loadable extension. The DONT_LINK flag prevents it from being statically linked into the DuckDB binary. Two additional libraries (libcustom and libhelper) are linked against the extension shared library.

Example 4: The default extension configuration file

# Contents of extension/extension_config.cmake (simplified)
duckdb_extension_load(core_functions)
duckdb_extension_load(parquet)

if(NOT APPLE AND NOT WIN32)
    duckdb_extension_load(jemalloc)
endif()

This shows the default configuration that ships with DuckDB: core_functions and parquet are always included, while jemalloc is included only on Linux systems.

Related Pages

• Principle:Duckdb_Duckdb_Extension_Configuration