Loading Extensions

Installing and loading DuckDB extensions at runtime

Extension Loading Commands

DuckDB provides two primary commands for working with extensions at runtime:

• INSTALL extension_name - Downloads and installs an extension
• LOAD extension_name - Loads an installed extension into the current session

Installing Extensions

Basic Installation

To install an extension from the DuckDB extension repository:

INSTALL parquet;
INSTALL json;
INSTALL icu;

This downloads the extension binary for your platform and stores it locally.

Force Reinstall

If you need to reinstall an extension (e.g., after corruption or to get a newer version):

FORCE INSTALL extension_name;

Use FORCE INSTALL if you encounter errors about corrupted or mismatched extension files.

Loading Extensions

After installing an extension, you need to load it to use its functionality:

LOAD parquet;
LOAD json;

Install and Load Pattern

A common pattern is to install and load together:

INSTALL sqlite_scanner;
LOAD sqlite_scanner;

-- Now you can use the extension
SELECT * FROM sqlite_scan('database.db', 'table_name');

Autoloading Extensions

DuckDB can automatically load certain known extensions when they’re needed.

Autoinstall Known Extensions

To enable automatic installation of known extensions:

SET autoinstall_known_extensions = true;
SET autoload_known_extensions = true;

With these settings enabled, DuckDB will automatically install and load extensions when you use features that require them:

-- This will auto-install and load the parquet extension if needed
SELECT * FROM 'data.parquet';

-- This will auto-install and load the json extension if needed
SELECT * FROM 'data.json';

Autoinstall is disabled by default for security reasons. Only enable it if you trust the DuckDB extension repository.

Extension Repository

Default Repository

Extensions are served from URLs following this pattern:

http://extensions.duckdb.org/v0.8.1/windows_arm64/name.duckdb_extension.gz

The URL components are:

• Repository: http://extensions.duckdb.org/
• Version: v0.8.1 (DuckDB version identifier)
• Platform: windows_arm64 (your platform)
• Extension name: name
• File extension: .duckdb_extension.gz (gzipped extension binary)

Custom Repository

You can configure a custom extension repository:

SET custom_extension_repository = 'http://some.url.org/subfolder1/subfolder2/';

This is useful for:

• Hosting internal/proprietary extensions
• Using a local mirror for air-gapped environments
• Testing extensions in development

Autoinstall Repository

For autoinstall operations, you can set a separate repository:

SET autoinstall_extension_repository = 'http://your-repo.com/extensions/';

Local Extension Storage

Installed extensions are stored locally at:

~/.duckdb/extensions/v0.8.1/osx_arm64/name.duckdb_extension

Path components:

• Config folder: ~/.duckdb/
• Extensions subfolder: extensions/
• Version: v0.8.1
• Platform: osx_arm64
• Extension file: name.duckdb_extension

Custom Home Directory

You can override the configuration folder location:

SET home_directory = '/some/folder';

Loading from Custom Paths

You can load an extension from an explicit file path:

LOAD '/path/to/my_extension.duckdb_extension';

This is useful for:

• Loading locally built extensions
• Using extensions not in the repository
• Testing development versions

Extension Status

Check which extensions are installed and loaded:

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

Install Modes

Extensions can have different install modes:

• STATICALLY_LINKED - Compiled into the DuckDB binary
• NOT_INSTALLED - Available but not installed
• INSTALLED - Downloaded and available locally

Common Workflows

First Time Setup

1. Install the extension

   INSTALL postgres_scanner;
   

   Downloads the extension binary to your local extensions folder.

2. Load the extension

   LOAD postgres_scanner;
   

   Loads the extension into your current DuckDB session.

3. Use the extension

   SELECT * FROM postgres_scan('host=localhost', 'public', 'users');
   

   The extension’s functions are now available.

Enable Autoloading

1. Set configuration

   SET autoinstall_known_extensions = true;
   SET autoload_known_extensions = true;
   
2. Use extension features directly

   -- DuckDB will auto-install and load the extension
   SELECT * FROM 'data.parquet';
   

Using a Custom Repository

1. Configure repository

   SET custom_extension_repository = 'http://internal-repo.company.com/duckdb/';
   
2. Install from custom repository

   INSTALL my_custom_extension;
   
3. Load and use

   LOAD my_custom_extension;
   

Troubleshooting

Extension Not Found

If you get an error that an extension is not found:

1. Check if the extension exists for your platform
2. Verify your DuckDB version is compatible
3. Try reinstalling: FORCE INSTALL extension_name;

Signature Verification Failed

If signature verification fails:

FORCE INSTALL extension_name;

Or manually remove the corrupted file from ~/.duckdb/extensions/

Autoload Not Working

Ensure both settings are enabled:

SET autoinstall_known_extensions = true;
SET autoload_known_extensions = true;

Next Steps

Core Extensions

Learn about the extensions available in DuckDB

Building Extensions

Build your own custom extensions