Registry / database / duckdb-extensions

duckdb-extensions

JSON →
library1.5.3pypypi✓ verified 86d ago

duckdb-extensions provides a comprehensive set of pip-installable DuckDB extensions, acting as a meta-package or individual `duckdb-extension-*` packages. It allows users to easily add capabilities like HTTPFS, Parquet, JSON, and Spatial functions to their DuckDB installations. The current version is 1.5.1, and releases closely track new DuckDB versions, offering frequent updates to maintain compatibility and leverage the latest features.

pip install duckdb-extensions
INSTALL
IMPORT
SIG · DUCKDB-EXTENSIONS
D
duckdb-extensions
databasepythonv1.5.3
Install
2.6s avg
Import
138ms
Disk
74MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.5.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.6s · import 0.138s · 77MB
74MB installed
● package 74MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

duckdb
import duckdb
duckdb-extensions provides binaries; its functionality is accessed through the 'duckdb' Python library.

This quickstart demonstrates how to install `duckdb-extensions` (which makes the binaries available), and then use the `duckdb` Python library to connect to DuckDB and load an extension (e.g., `httpfs`) via SQL commands within the session. It then provides a simple example of using the loaded extension to query a remote Parquet file.

import duckdb import os # Connect to an in-memory DuckDB database con = duckdb.connect(database=':memory:', read_only=False) # The duckdb-extensions package makes compiled extensions available. # You can then install and load them within your DuckDB session via SQL. try: # Example: Install and Load the HTTPFS extension # This allows DuckDB to read data directly from HTTP(S) URLs. con.execute("INSTALL httpfs;") con.execute("LOAD httpfs;") print("HTTPFS extension loaded successfully.") # Example usage: Query a remote Parquet file (using a placeholder URL) # Replace with a real URL if you want to run this example fully. sample_url = os.environ.get('DUCKDB_SAMPLE_PARQUET_URL', 'https://duckdb.org/data/nyc_taxi_2019-01.parquet') print(f"Attempting to query data from: {sample_url}") # Execute a query using the loaded extension result = con.execute(f"SELECT count(*) FROM '{sample_url}';").fetchone() print(f"Count from remote parquet (first row): {result}") except duckdb.DuckDBPyConnectionException as e: print(f"Error loading extension or executing query: {e}") print("HINT: Ensure 'duckdb-extensions' is installed and its version matches your 'duckdb' library version.") except Exception as e: print(f"An unexpected error occurred: {e}") finally: con.close() print("DuckDB connection closed.")
Debug
Known issues
breakingPython 3.8 support was removed in `duckdb-extensions` v1.4.0. Users on Python 3.8 must use `duckdb-extensions` v1.3.2 or older.
fix
Upgrade to Python 3.9+ or pin `duckdb-extensions` to `==1.3.2` if Python 3.8 is required.
affects: >=1.4.0
gotchaThe version of `duckdb-extensions` (or individual `duckdb-extension-*` packages) *must* precisely match the version of your `duckdb` Python package for extensions to load correctly.
fix
Ensure `pip install duckdb==X.Y.Z` and `pip install duckdb-extensions==X.Y.Z` (or specific extensions) use the same `X.Y.Z` version number.
affects: All versions
gotchaduckdb-extensions does not expose Python functions or classes for direct import (e.g., `import duckdb_extensions`). It provides compiled binaries that are discovered and loaded by the `duckdb` library itself, typically via SQL `INSTALL` and `LOAD` commands.
fix
After installation, use `import duckdb` and interact with extensions through `duckdb.connect().execute("INSTALL extension_name;").execute("LOAD extension_name;")`.
affects: All versions
Errors
Common errors & fixes
Error: Extension 'httpfs' is not installed. Use INSTALL httpfs; to install and LOAD httpfs; to load it.
The `duckdb-extensions` package or the specific extension (e.g., `duckdb-extension-httpfs`) was not installed, or its version does not match the `duckdb` library version.
fix
Ensure `pip install duckdb-extensions==X.Y.Z` (or `pip install duckdb-extension-httpfs==X.Y.Z`) where `X.Y.Z` matches your `duckdb` version, then retry `INSTALL` and `LOAD` in your DuckDB session.
RuntimeError: Incompatible extension version! Extension 'httpfs' was compiled for DuckDB X.Y.Z, but you are running DuckDB A.B.C
There is a version mismatch between the installed `duckdb` Python package and the installed `duckdb-extensions` package.
fix
Uninstall both `duckdb` and `duckdb-extensions` (or specific extensions) and reinstall them with matching versions: `pip uninstall duckdb duckdb-extensions && pip install duckdb==1.5.1 duckdb-extensions==1.5.1` (using current versions as an example).
ModuleNotFoundError: No module named 'duckdb_extensions'
Attempting to `import duckdb_extensions` as if it were a standard Python module exposing functions. The `duckdb-extensions` package provides C/C++ binaries for DuckDB, not Python APIs for direct import.
fix
Do not `import duckdb_extensions`. Instead, `import duckdb` and manage extensions within the DuckDB session using SQL commands like `INSTALL` and `LOAD` after `duckdb-extensions` is pip-installed.
Upgrade
Version history
1.5.3latest on PyPI · released May 29, 2026
Audit
Dependencies
duckdbrequiredProvides extensions for the DuckDB core library; requires a matching version for compatibility.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources