⌘K ctrl+k
Search Shortcut cmd + k | ctrl + k

Extensions as Python Packages

The DuckDB command line client and every core extension are available as Python packages on PyPI. Installing an extension this way puts its binary into the Python environment, so DuckDB loads it without downloading from the extension repository. This serves environments without network access, environments behind a mirror that proxies only PyPI, and projects that pin their dependencies in a lockfile.

Installing the CLI and Extensions with pip

The package duckdb-cli installs the duckdb command. Each core extension is a package duckdb-core-ext-name, and duckdb-cli declares one extra per extension, so an extension is one more name in the install command:

pip install "duckdb-cli[httpfs,spatial]==2.0.0"
duckdb -c "LOAD httpfs; LOAD spatial;"

The extension packages carry the DuckDB version they are built for, and the extras pin them to the same version as the CLI. An extension built for one DuckDB version does not load in another, so keep the versions equal when you install packages one by one:

pip install "duckdb-cli==2.0.0" "duckdb-core-ext-httpfs==2.0.0"

The extras use the extension names, with a few aliases: s3, http and https install httpfs; postgres, mysql and sqlite install the scanner of that name; md installs motherduck. The extensions compiled into the CLI (autocomplete, core_functions, icu, json, parquet) have no package. The status page lists which extension packages exist for which DuckDB version and platform.

Both the CLI and the extension wheels are tagged py3-none-platform: they contain no Python code that depends on the interpreter version, and pip picks the wheel for the operating system and architecture it runs on. Wheels exist for Linux on x86-64 and arm64 (glibc and musl), macOS on x86-64 and arm64, and Windows on x86-64 and arm64.

What the Packages Install

An extension package installs its binary at

site-packages/.duckdb_extensions/vDuckDB version/platform/name.duckdb_extension

This is the layout DuckDB uses for its own extension directory, by default ~/.duckdb/extensions. The duckdb command from duckdb-cli adds site-packages/.duckdb_extensions to the extension_directories setting when that directory exists, after the directories DuckDB already searches. LOAD searches every listed directory, so LOAD httpfs finds the pip-installed file and loads it without a download.

Each package also installs a small Python module, duckdb_core_ext_name, with two functions: get_extensions_dir() returns the .duckdb_extensions directory, and get_extension_load_path() returns the path of the binary.

Limitations

  • DuckDB's automatic installation of a missing extension checks only the first directory of extension_directories before downloading. A query that needs an extension that was not loaded with LOAD may therefore download it again into ~/.duckdb/extensions, and without network access that automatic load fails. An explicit LOAD always works. This changes once DuckDB treats an extension present in any configured directory as installed.
  • The duckdb Python module does not search site-packages/.duckdb_extensions yet. In Python, pass the directory yourself:

    import duckdb
    import duckdb_core_ext_httpfs
    
    con = duckdb.connect(config={"extension_directories": [duckdb_core_ext_httpfs.get_extensions_dir()]})
    con.execute("LOAD httpfs")
    
  • Nothing in a wheel tells pip which DuckDB the user runs. A wheel installed for another DuckDB version than the one in use is not found by LOAD, or refused.

Signatures

A wheel changes nothing about DuckDB's signature check: DuckDB loads an extension from the pip directory under the same rules as from anywhere else. An extension signed with a core key, which is every binary on extensions.duckdb.org, loads as is. A community extension loads when the install information file described below is beside it. An extension that nobody signed, for example one you built yourself and did not submit to the community repository, loads only when the user allows unsigned extensions, with duckdb -unsigned or SET allow_unsigned_extensions = true; the package installs either way, the engine refuses the load. See Extension Signing.

Packaging Your Own Extension

The tool that builds the core extension packages is published as duckdb-extension-wheel for any extension author. It reads the platform, the DuckDB version and the ABI type from the extension binary's metadata footer and takes from you what the binary cannot say: the project name, the wheel version, and the dependencies.

pip install duckdb-extension-wheel
duckdb-extension-wheel build --name acme-duckdb-geo --version 0.3.1 \
    --requires "duckdb-cli==2.0.0" \
    build/release/extension/geo/geo.duckdb_extension
duckdb-extension-wheel check dist/acme_duckdb_geo-0.3.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

build writes one wheel per binary you pass, so run it with the binaries of every platform you build for, or once per platform in your CI. Versioning and dependencies are yours: the wheel version is any version you choose, and a dependency on duckdb-cli is optional. check installs a wheel into a fresh virtual environment, downloads the DuckDB command line of the binary's version, and loads the extension from the environment's directory; run it on each platform.

Two things the tool needs to know for some binaries:

  • A community extension, or any extension not signed with a core key, needs the install information file DuckDB writes beside an installed extension, name.duckdb_extension.info: DuckDB 2.0 reads it to decide which signing keys to trust. Install the extension once per platform with INSTALL name FROM community and copy the file from ~/.duckdb/extensions/vversion/platform/ next to the binary, where the tool picks it up, or name it with --info. A binary signed with a core key needs none; say --core-extension.
  • An extension built against the stable C API carries no DuckDB version in its footer; give it with --duckdb-version. Such a wheel still holds one DuckDB version, since the binary lands in that version's directory.

The full contract a wheel follows, with everything the tool decides and everything it leaves to you, is the protocol document in the repository that publishes the core extension packages. DuckDB before 1.5.0 has no extension_directories setting, so the tool refuses binaries built for older versions.

© 2026 DuckDB Foundation, Amsterdam NL
DuckDB Home Code of Conduct Trademark Use Blog