# pip ERROR: Could not build wheels for pyproject.toml-based projects after python upgrade

TL;DR: The new Python cannot build the package's wheel - usually an outdated pip/setuptools, a missing build backend, or missing system compilers. Upgrade pip, setuptools, and wheel first and retry; that alone resolves most cases. If it persists, the full build log above the ERROR line names the real missing piece.

```text
pip ERROR: Could not build wheels for pyproject.toml-based projects after python upgrade
```

## Steps

1. Upgrade the build toolchain in the environment: `pip install --upgrade pip setuptools wheel`.
   Expected: the command prints current versions for all three.
2. Check the package's `pyproject.toml` under `[build-system]` `requires`, and install any missing backend it names (for example the hatchling, flit-core, or poetry-core package it lists).
   Expected: the named build backend is installed.
3. Retry the original install.
   Expected: the wheel builds and installs cleanly.
4. If it still fails, scroll up in the full build log past the ERROR line - it names the actual cause (missing C compiler, missing headers, a Rust toolchain for maturin-based builds, and so on). Install what is named and retry.
   Expected: the named missing piece resolves the build.
5. Last resort for a known-good backend: install its build requirements manually, then `pip install --no-build-isolation [package-name]`.
   Expected: the build runs against your installed backends and succeeds.

## Use this when

- pip reports `Could not build wheels` naming a pyproject.toml-based project right after a Python upgrade.
- The package installed fine on the old Python.
- The environment was carried over or recreated with old pinned build tools.

## Not for this skill when

- The failing package has no pyproject.toml (legacy setup.py path) - different build flow, different fixes.
- The failure is a network or download error rather than a build error.
- You passed `--only-binary` and no wheel exists for the new Python - that is availability, not a build failure.

## Variant phrasings

- pip failed building wheel after python upgrade
- pyproject.toml build fails on new python version
- ERROR could not build wheels setuptools

## Why it happens

A new Python needs current build backends and compiler/ABI support for that interpreter. Old pinned setuptools/wheel versions in the environment predate the new Python and cannot produce a valid wheel for it, so the PEP 517 build fails.

## Edge cases

- `--no-build-isolation` uses your environment's backends, which can mask version skew - prefer fixing the isolated build first.
- On a brand-new Python major, some packages have no compatible release yet - check the package changelog before fighting the build.
- In Docker, the compilers and headers must be in the build stage - having them on your laptop does not help the image build.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PbdRGL6SbsvS8fLCc6RWNA