Overview

This page collects common issues encountered when using the DuckDB Rust client, together with their workarounds. If you run into a problem that is not covered here, search the client's issue tracker on GitHub.

Linking against a System Library

The bundled feature compiles DuckDB from the source shipped with the crate, so nothing else is needed to build, and it is the simplest choice for most applications. Without bundled, the underlying libduckdb-sys crate links against a DuckDB library already on the system, which it locates through pkg-config or, on the MSVC ABI, Vcpkg. If no library is found, the build fails. There are three ways to build without bundled.

Point at a Library You Already Have

Set DUCKDB_LIB_DIR to the directory containing the library, and DUCKDB_INCLUDE_DIR to the directory containing duckdb.h if it is elsewhere. For example, using a prebuilt library from a DuckDB release:

wget https://github.com/duckdb/duckdb/releases/download/v1.5.5/libduckdb-osx-universal.zip
unzip libduckdb-osx-universal.zip -d libduckdb

export DUCKDB_LIB_DIR=$PWD/libduckdb
export DUCKDB_INCLUDE_DIR=$DUCKDB_LIB_DIR
export DYLD_FALLBACK_LIBRARY_PATH=$DUCKDB_LIB_DIR   # LD_LIBRARY_PATH on Linux
cargo build

On Linux, use the matching libduckdb-linux-amd64.zip or libduckdb-linux-arm64.zip archive and set LD_LIBRARY_PATH instead.

Let the Build Download a Library

Set DUCKDB_DOWNLOAD_LIB=1 and the build script downloads the prebuilt DuckDB library matching the crate's version from GitHub Releases, caches it under target/, and adds it to the linker search path. Leave DUCKDB_STATIC unset, because the downloaded archives contain only the dynamic library:

DUCKDB_DOWNLOAD_LIB=1 cargo build

Use a Package Manager

If DuckDB is installed through pkg-config or Vcpkg, the build finds it automatically. vcpkg uses static libraries by default; set VCPKGRS_DYNAMIC=1 to link dynamically instead.

ICU Extension Is Excluded from the Bundled Build

Because crates.io imposes a 10 MB package-size limit, the bundled source excludes the ICU extension. As a result, some collation and time-zone-aware date/time operations fail out of the box. Install and load ICU at runtime to restore them:

conn.execute_batch("INSTALL icu; LOAD icu;")?;

Alternatively, statically link ICU by enabling the crate's icu feature, which pulls it into the build.

open_in_memory Panics in an Extension Build

The loadable-extension feature builds a DuckDB extension rather than a client application. When it is enabled, entry points such as Connection::open_in_memory() panic if they are called outside an extension context, because there is no host DuckDB instance to attach to.

Do not enable loadable-extension for a client application. Use it only when building an extension. See Write User Defined Functions for how loadable extensions are built and packaged.

Cross-Compiling with bundled

Cross-compiling with the bundled feature compiles DuckDB's C++ source for the target, so it requires a working C++ cross-compiler for that target and is supported only on a best-effort basis. When cross-compilation is difficult to set up, link against a prebuilt library for the target with DUCKDB_LIB_DIR instead, as described in Linking against a System Library.

Further Reading

• Rust Client — installation, the bundled feature, and the full list of Cargo feature flags.
• Connect — opening connections, whose failures are often build or linking problems.
• Write User Defined Functions — the loadable-extension feature and how to package an extension correctly.