Failed building wheel 🐍 Python

error: subprocess-exited-with-error / Failed building wheel for x

pip had to compile a package from source and the build failed — missing compiler, headers or system libraries.

Seen on: Python

Meaning

When no prebuilt wheel exists for your Python/OS, pip builds from source. That needs a C compiler and library headers (e.g. libpq-dev for psycopg2, Microsoft C++ Build Tools on Windows).

Common causes

  • No prebuilt wheel for a brand-new Python version
  • Missing build tools (gcc, MSVC)
  • Missing system headers (libpq-dev, libffi-dev, python3-dev)
  • Old pip unable to use modern wheels

⚡ Quick fix

  1. Upgrade pip/setuptools/wheel first
  2. Use a supported Python version with wheels
  3. Install build deps (build-essential python3-dev + library -dev packages)
  4. Prefer binary packages (psycopg2-binary)

Detailed fix by platform

Linux

  1. sudo apt install build-essential python3-dev libpq-dev && python -m pip install -U pip wheel setuptools

How to diagnose

  1. Package — Which package failed?
  2. Log — First "error:" line in the build output

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.