# error: metadata-generation-failed
× Encountered error while generating package metadata.
╰─> See above for output.

- **ID:** `python/pip-install-metadata-generation-failed`
- **Domain:** python
- **Category:** install_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

pip uses PEP 517 build isolation to build wheel metadata in an isolated environment. If the build backend (setuptools, hatchling, poetry-core) is missing or a build dependency is not declared in pyproject.toml, metadata generation fails before the actual install.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 3.8 | active | — | — |
| 3.9 | active | — | — |
| 3.10 | active | — | — |
| 3.11 | active | — | — |
| 3.12 | active | — | — |

## Workarounds

1. **** (85% success)
   ```
   pip install setuptools wheel
pip install --no-build-isolation ./mypackage
   ```
2. **** (90% success)
   ```
   [build-system]
requires = ["setuptools>=64", "wheel", "cython"]
build-backend = "setuptools.build_meta"
   ```
3. **** (80% success)
   ```
   pip install -v ./mypackage 2>&1 | grep -A5 'Error'
   ```

## Dead Ends

- **** — Disables isolation but the missing build dependency is still not present in the current environment, so the backend import fails anyway. (55% fail)
- **** — The failure is in the build backend invocation, not a corrupted download; clearing cache does not add missing build deps. (70% fail)
- **** — Newer pip still respects pyproject.toml build-system requirements; the missing dependency is unchanged. (60% fail)