How to Install DuckDB for Node in CI Without Build Failures

DuckDB for Node bundles a large C++ engine. Its prebuilt binaries make CI fast; a forced source build is a long, toolchain-heavy compile you want to avoid.

The DuckDB node bindings (the modern @duckdb/node-api / @duckdb/node-bindings, or the older duckdb package) ship prebuilt binaries for common platforms. Alpine/musl, a new Node ABI, or an unusual arch can force a source build of the DuckDB C++ engine - slow and rarely worth it in CI.

Why it fails in CI

Alpine/musl has no prebuilt → a long DuckDB C++ source build needs python3 + a modern g++.
The runner Node ABI differs from the prebuilt → NODE_MODULE_VERSION mismatch.
The big C++ compile can OOM a small runner (exit 137).

Install it reliably

Stay on the prebuilt binary: use a glibc base image and a Node version with a published prebuilt. Prefer the maintained @duckdb/node-api package. Avoid the source build unless you truly must.

Terminal

# prebuilt bindings on common Linux (no compile)
npm install @duckdb/node-api

# if a source build is unavoidable (Debian/Ubuntu): heavy C++ compile
apt-get update && apt-get install -y python3 make g++ build-essential
npm install duckdb --build-from-source

Cache & speed

Cache ~/.npm keyed on lockfile + Node version so the prebuilt binary is reused. If you are forced to compile, size the runner for the C++ build and bake the toolchain into the image.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-node${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}

Common errors

No prebuilt binaries found → pin a supported Node/platform, or build from source with the toolchain.
NODE_MODULE_VERSION mismatch → reinstall/rebuild on the target Node.
Killed / exit 137 during a source compile → OOM; use a bigger runner or stay on the prebuilt.

Key takeaways

DuckDB for Node ships prebuilt binaries - keep that path with glibc + a supported Node.
Prefer @duckdb/node-api; avoid the slow C++ source build in CI.
A source compile can OOM a small runner; size it or stay prebuilt.