How to Install DuckDB (Python) in CI Without Build Failures

The duckdb Python wheel bundles the whole engine, so installs are fast - until a too-new Python or musl image forces a slow C++ source build.

The duckdb Python package ships manylinux wheels with the DuckDB C++ engine bundled, so a correct install just downloads a wheel. The pain is being forced into a source build by a brand-new Python, Alpine/musl, or an unusual arch - compiling DuckDB C++ in CI is slow and toolchain-heavy.

Why it fails in CI

When no wheel matches the interpreter, pip compiles DuckDB from source - a long C++ build needing a modern compiler. Slim and Alpine images lack the toolchain, and even when present the build dominates the pipeline.

• Could not find a version that satisfies the requirement duckdb on a new Python/musl.
• Failed building wheel for duckdb with C++ compile errors.
• A build that runs many minutes - it is compiling the engine, not hung.

Install it reliably

Keep the wheel: use a glibc base image (not Alpine), pin a Python duckdb ships wheels for, and force-binary so a missing wheel fails fast instead of compiling.

# Force the prebuilt wheel - DuckDB engine comes bundled
pip install --only-binary=:all: duckdb

# Pin a supported interpreter
- uses: actions/setup-python@v5
  with:
    python-version: '3.11'

Cache & speed

The wheel is sizeable; cache ~/.cache/pip so it is downloaded once. Avoiding the source build is the dominant speedup.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-duckdb-${{ hashFiles('requirements*.txt') }}

Common errors

Key takeaways

• The duckdb wheel bundles the engine - never compile it in CI.
• Glibc base + a supported Python keeps you on the wheel.
• Force --only-binary; cache the wheel.

Related guides