Extensions

Before installing an extension, verify the 2.0 CLI from duckdb. Extensions installed by 1.5 are the wrong build for 2.0.

Install and load

INSTALL AND LOAD spatial;
INSTALL AND LOAD h3 FROM community;

In DuckDB 2.0, activate extensions with INSTALL AND LOAD. If the extension binary is already cached, DuckDB skips the download. If the extension is already loaded in the session, DuckDB skips loading.

When autoinstall_known_extensions is true (default), LOAD name installs a known extension before loading. Loading an extension automatically loads all dependencies.

Update

UPDATE EXTENSIONS;
UPDATE EXTENSIONS (spatial, httpfs);

To update repository extensions to their latest builds, run UPDATE EXTENSIONS. Result columns are extension_name, repository, update_result, previous_version, and current_version.

Because UPDATE EXTENSIONS writes new binaries to disk without reloading running in-memory modules, restart the process before depending on updated extensions.

Update rules:

• Only REPOSITORY installs are updated. UPDATE EXTENSIONS skips CUSTOM_PATH installs.
• If an extension has a pinned version, UPDATE EXTENSIONS overwrites it with the repository's latest build. To restore a pinned version after updating, run FORCE INSTALL name VERSION '<version>'.
• Statically linked extensions (autocomplete, core_functions, icu, json, parquet, and shell) ship inside the DuckDB binary and cannot be updated with UPDATE EXTENSIONS.

Inspect

SELECT extension_name, installed, loaded, extension_version, install_mode, installed_from
FROM duckdb_extensions()
ORDER BY extension_name;

Inspection columns in duckdb_extensions():

• install_mode: STATICALLY_LINKED, REPOSITORY, CUSTOM_PATH, NOT_INSTALLED, or UNKNOWN.
• installed_from: repository name for REPOSITORY installs, or source file path for CUSTOM_PATH installs.
• signature_key_fingerprint: SHA-256 public key fingerprint for signed repository builds.

Repositories

Custom repository syntax is experimental (WIP) and subject to change.

SET allow_extension_repositories = 'allowed';

CREATE EXTENSION REPOSITORY my_repo
    WITH PREFIX 'https://extensions.example.org';

INSTALL AND LOAD my_ext FROM my_repo;

SELECT repository_name, prefix, key_fingerprints
FROM duckdb_extension_repositories();

DROP EXTENSION REPOSITORY my_repo;

Repository permission states in allow_extension_repositories:

• undecided (default): blocks adding custom repositories.
• allowed: permits repository registration.
• forbidden: blocks registration and distrusts custom repositories already stored on disk.
• Process rule: while running, the setting only moves undecided to allowed or forbidden, or allowed to forbidden. It cannot move back.

Key management and storage:

• When executing CREATE EXTENSION REPOSITORY, DuckDB fetches 2048-bit RSA public keys from the repository, pins them locally, and prints each SHA-256 fingerprint. Verify this fingerprint against the publisher's out-of-band release.
• To pin keys offline without network requests, specify USING PUBLIC KEY '...'.
• Repository prefix paths support local filesystem paths, https, or s3.
• Repository definitions persist globally under ~/.duckdb/extension_repositories/ across restarts rather than inside database files.
• extension_repository_directory defines the root trust anchor. While signature verification remains enabled, configure this setting at startup only.
• For a one-off mirror, run SET custom_extension_repository = 'https://mirror.example.org'. While core and community fall back to backup mirrors automatically on connection failures, custom repositories do not provide automatic fallback.

Platform and security

Community extensions are third-party contributions not maintained by DuckDB Labs. DuckDB 2.0 does not build community extensions for osx_amd64. Core extensions still build for osx_amd64 in 2.0, while 2.1 drops osx_amd64 entirely.

Security settings default to allow_community_extensions = true and allow_unsigned_extensions = false. Never use -unsigned or SET allow_unsigned_extensions = true in production; use signed repositories with pinned RSA keys.

Binary directories:

• Extensions reside under ~/.duckdb/extensions/<duckdb-version>/<platform>/.
• To configure multiple search paths, pass a list to extension_directories. DuckDB installs into the first directory and loads from all listed directories.
• Avoid the singular extension_directory setting. DuckDB 2.0 deprecates it with a warning.

Troubleshoot

If a repository is unreachable or air-gapped, install from a local file:

FORCE INSTALL '/absolute/path/spatial.duckdb_extension';

File installation rules:

• DuckDB accepts .duckdb_extension.gz and decompresses it automatically during INSTALL. Decompress manually only if the installer rejects the archive.
• To load an extension directly without copying it into extension_directories, run LOAD '/absolute/path/name.duckdb_extension'. DuckDB derives the extension name from the filename basename.
• To uninstall an extension, delete the .duckdb_extension file from disk. DuckDB provides no SQL uninstall command.

Verify

INSTALL AND LOAD httpfs;
SELECT extension_name, loaded, install_mode
FROM duckdb_extensions()
WHERE extension_name = 'httpfs';

Confirm loaded returns true. If INSTALL AND LOAD fails, inspect the error output: DuckDB returns the repository URL and target platform string, differentiating unknown extension names from network or SSL transport failures.

References

• Installing extensions details repository forms, force install, and directory paths.
• LOAD and INSTALL documents statement syntax and options.
• UPDATE EXTENSIONS documents extension updates and result columns.
• Extension repositories details experimental custom repositories and key pinning.
• Community extensions covers community policies and platform architecture rules.
• Securing extensions specifies unsigned extension risks and trust anchors.
• Extension installation workflows adapted from the install-duckdb skill in https://github.com/duckdb/duckdb-skills (MIT).