DuckDB Extensions

Common errors

• Error: Extension 'httpfs' is not installed. Use INSTALL httpfs; to install and LOAD httpfs; to load it.

  cause 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

  cause 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'

  cause 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.

Warnings

• breaking Python 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.
• gotcha The 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.
• gotcha duckdb-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;")`.

Install

• pip install duckdb-extensions Install all extensions (meta-package)
• pip install duckdb-extension-httpfs Install a specific extension

Imports

• duckdb

  import duckdb

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

Quickstart

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.")