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.
Failed building wheel forMicrosoft Visual C++ 14.0 or greater is required 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
- Upgrade pip/setuptools/wheel first
- Use a supported Python version with wheels
- Install build deps (build-essential python3-dev + library -dev packages)
- Prefer binary packages (psycopg2-binary)
Detailed fix by platform
Linux
sudo apt install build-essential python3-dev libpq-dev && python -m pip install -U pip wheel setuptools
How to diagnose
- Package — Which package failed?
- Log — First "error:" line in the build output
🔧 Still not fixed?
Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:
Similar errors
Most viewed in Python
Other ways to find it
Where this error sits
Origin: Application & API. Errors that are often confused with or caused by this one (click to open):
🧠 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.
💬 What worked for others
No tips yet — did something else fix this for you?
Share what worked for you
Tips are checked by an editor before they appear. Links are removed.
Report a correction or suggest an improvement
Last updated 13 Oct 2026