fix/duckdb/pip-install-not-working
DuckDB error

pip install duckdb not working

Updated Aug 27, 20265-min read
TL;DR

pip install duckdb fails because pip cannot find a prebuilt wheel that matches your Python version, OS, or CPU architecture, and the fallback source build then fails because the toolchain is missing. In almost every case the fix is a newer pip, a supported Python interpreter, or a platform that DuckDB actually ships a wheel for.

  • ·pip itself is old and does not understand the wheel tag DuckDB publishes
  • ·Python version is too new (pre-release) or too old, so no matching wheel exists
  • ·Alpine Linux, musl, ARM32, PyPy, or another platform with no prebuilt wheel
  • ·Source build fails because there is no C++ compiler (MSVC on Windows, gcc/clang on Linux)
  • ·A corporate proxy or SSL policy is blocking the download from PyPI
CHECK FIRSTRun pip --version and python --version. If pip is under 21, that alone breaks modern wheels. Upgrade with python -m pip install --upgrade pip and retry.

What you're seeing

The exact error depends on why pip cannot install DuckDB. The two most common ones show up when pip cannot find a wheel and refuses to build from source, or when the build starts and then fails for a missing compiler.

text
$ pip install duckdb
ERROR: Could not find a version that satisfies the requirement duckdb (from versions: none)
ERROR: No matching distribution found for duckdb

# Or, when pip falls back to a source build:
ERROR: Could not build wheels for duckdb, which is required to install pyproject.toml-based projects

# Windows source-build variant:
error: Microsoft Visual C++ 14.0 or greater is required. Get it with
"Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/
Also seen as: pip install duckdb not working, could not find a version that satisfies the requirement duckdb, no matching distribution found for duckdb, could not build wheels for duckdb, pip install duckdb failed

What's causing this

Ranked most-likely first.

  1. 1

    pip is too old for DuckDB's wheel tags

    DuckDB publishes manylinux_2_17, macosx_11_0, and win_amd64 wheels tagged with a PEP 600 tag. Old pip (under 21) does not recognize those tags and reports no matching distribution, then either falls back to a source build or gives up. This is the single most common cause on stale system Python installs.

  2. 2

    No wheel exists for your Python version

    DuckDB ships wheels for a specific window of CPython versions, currently 3.9 through the latest stable release. A pre-release interpreter (3.14 alpha, 3.15) or a Python that is past end-of-life (3.7, 3.8) will have no matching wheel on PyPI, so pip tries to build from source and fails.

  3. 3

    No wheel exists for your platform

    Alpine Linux and other musl distributions, ARM32, s390x, ppc64le, and PyPy interpreters do not have DuckDB wheels on every release. pip then tries to build from source and needs a full C++ toolchain plus CMake, which most container base images do not include.

  4. 4

    The source build fails for a missing C++ compiler

    When pip falls back to sdist, it needs a working host toolchain. On Windows that is Microsoft Visual C++ Build Tools, on Linux it is gcc or clang with C++17 support, and on macOS it is the Xcode command line tools. Any of them missing surfaces as a wheel build failure.

  5. 5

    A proxy, mirror, or SSL policy is blocking PyPI

    Corporate networks often route pip through a proxy or an internal mirror that has not synced DuckDB's latest release, or has an SSL man-in-the-middle certificate pip does not trust. The symptom is the same as no matching distribution, or an SSLError deep in the traceback.

  6. 6

    Wrong package name or a pinned version that never existed

    The PyPI package is duckdb. Not duckdb-python, not python-duckdb, not pyduckdb. Pinning a version that was never published, or one that predates wheels for your platform, also produces a no-matching-distribution error.

How to fix it

Step 1: check pip and Python versions

Confirm what pip is actually running against. A stale system pip on macOS or Debian is the usual culprit, and mixed Python installs can send you off chasing the wrong toolchain.

bash
python --version
pip --version

# On systems with multiple Pythons, be explicit:
python3.11 -m pip --version

Step 2: upgrade pip and try again

This alone resolves the majority of no-matching-distribution errors. Modern pip understands DuckDB's wheel tags and will pick up a prebuilt binary instead of trying to compile from source.

bash
python -m pip install --upgrade pip
python -m pip install duckdb

Step 3: install into a fresh virtual environment

System Python installs are often patched by distros in ways that break wheel resolution, and a global site-packages can hide broken pip caches. A clean venv rules both out.

bash
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install duckdb

Step 4: switch to a supported Python version

If you are on a pre-release Python (3.14 alpha) or an end-of-life one (3.7, 3.8), install a supported version. Recent DuckDB releases publish wheels for CPython 3.9 through the latest stable line.

bash
# With pyenv:
pyenv install 3.11.9
pyenv shell 3.11.9
python -m pip install duckdb

# With uv, which manages Pythons directly:
uv python install 3.11
uv pip install duckdb

Step 5: on Alpine or other unsupported platforms, switch base image

Alpine uses musl and does not have official DuckDB wheels on most releases. The easiest fix is a Debian or Ubuntu based image where manylinux wheels install cleanly. If you must stay on Alpine, install a C++ toolchain and let pip build from source.

bash
# Preferred: switch base image
FROM python:3.11-slim
RUN pip install duckdb

# Or, on Alpine, add the toolchain and build:
FROM python:3.11-alpine
RUN apk add --no-cache build-base cmake git
RUN pip install duckdb

Step 6: install a C++ compiler for source builds

If a source build is unavoidable because no wheel matches your platform, install the toolchain first. Once the compiler is on PATH, pip install duckdb will build the extension itself.

bash
# Debian/Ubuntu:
sudo apt-get install -y build-essential cmake

# Fedora/RHEL:
sudo dnf install -y gcc-c++ cmake

# macOS:
xcode-select --install

# Windows: install "Microsoft C++ Build Tools" from
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

Step 7: work around proxies and mirrors

If pip can reach PyPI but a proxy is blocking, point it at the index directly, or trust the internal mirror explicitly. If your org runs Artifactory or Nexus, confirm the DuckDB release you want has actually synced.

bash
# Force the public index:
pip install duckdb --index-url https://pypi.org/simple

# Trust an internal mirror with a self-signed cert:
pip install duckdb \
  --index-url https://pypi.internal/simple \
  --trusted-host pypi.internal

Step 8: confirm the package name and version

The correct PyPI package is duckdb. If you pinned a version, verify it exists for your interpreter. pip index versions duckdb will list every published release.

bash
pip index versions duckdb

# Install a specific released version:
pip install "duckdb==1.1.3"

Prevention

Pin the Python version your project runs on and keep it inside DuckDB's supported window. A .python-version file plus pyenv or uv is enough to stop the pre-release and end-of-life traps.

In Docker, prefer python:3.x-slim over python:3.x-alpine unless you have a hard reason to use musl. The image is a few megabytes larger and every wheeled Python package, DuckDB included, installs without a compiler.

In CI, upgrade pip before installing anything else. Even fresh GitHub Actions runners occasionally ship an older pip than what your requirements need, and the cost of upgrading first is one extra line.

Debug DuckDB faster

1bench is a native GUI for DuckDB. Inspect queries, connections, and settings without leaving the app. See what's happening before you have to Google it.

Open DuckDB in 1bench