{"id":9709,"library":"duckdb-extensions","title":"DuckDB Extensions","description":"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.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/santosh-d3vpl3x/duckdb_extensions","tags":["duckdb","database","extensions","data science","etl"],"install":[{"cmd":"pip install duckdb-extensions","lang":"bash","label":"Install all extensions (meta-package)"},{"cmd":"pip install duckdb-extension-httpfs","lang":"bash","label":"Install a specific extension"}],"dependencies":[{"reason":"Provides extensions for the DuckDB core library; requires a matching version for compatibility.","package":"duckdb","optional":false}],"imports":[{"note":"duckdb-extensions provides binaries; its functionality is accessed through the 'duckdb' Python library.","symbol":"duckdb","correct":"import duckdb"}],"quickstart":{"code":"import duckdb\nimport os\n\n# Connect to an in-memory DuckDB database\ncon = duckdb.connect(database=':memory:', read_only=False)\n\n# The duckdb-extensions package makes compiled extensions available.\n# You can then install and load them within your DuckDB session via SQL.\n\ntry:\n    # Example: Install and Load the HTTPFS extension\n    # This allows DuckDB to read data directly from HTTP(S) URLs.\n    con.execute(\"INSTALL httpfs;\")\n    con.execute(\"LOAD httpfs;\")\n    print(\"HTTPFS extension loaded successfully.\")\n\n    # Example usage: Query a remote Parquet file (using a placeholder URL)\n    # Replace with a real URL if you want to run this example fully.\n    sample_url = os.environ.get('DUCKDB_SAMPLE_PARQUET_URL', 'https://duckdb.org/data/nyc_taxi_2019-01.parquet')\n    print(f\"Attempting to query data from: {sample_url}\")\n    \n    # Execute a query using the loaded extension\n    result = con.execute(f\"SELECT count(*) FROM '{sample_url}';\").fetchone()\n    print(f\"Count from remote parquet (first row): {result}\")\n\nexcept duckdb.DuckDBPyConnectionException as e:\n    print(f\"Error loading extension or executing query: {e}\")\n    print(\"HINT: Ensure 'duckdb-extensions' is installed and its version matches your 'duckdb' library version.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    con.close()\n    print(\"DuckDB connection closed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.9+ or pin `duckdb-extensions` to `==1.3.2` if Python 3.8 is required.","message":"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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"After installation, use `import duckdb` and interact with extensions through `duckdb.connect().execute(\"INSTALL extension_name;\").execute(\"LOAD extension_name;\")`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Extension 'httpfs' is not installed. Use INSTALL httpfs; to install and LOAD httpfs; to load it."},{"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).","cause":"There is a version mismatch between the installed `duckdb` Python package and the installed `duckdb-extensions` package.","error":"RuntimeError: Incompatible extension version! Extension 'httpfs' was compiled for DuckDB X.Y.Z, but you are running DuckDB A.B.C"},{"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.","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.","error":"ModuleNotFoundError: No module named 'duckdb_extensions'"}]}