# error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

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

## Root Cause

pip's PEP 517 isolated build could not generate metadata because the package's setup.py/build backend raised an exception (commonly a missing dependency, a syntax error in setup.py, or an unimportable package).

## Version Compatibility

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

## Workarounds

1. **** (85% success)
   ```
   Re-run with verbose output to see the real exception: `pip install -v <pkg>`. The actual error (e.g. `ModuleNotFoundError` inside setup.py) appears a few lines above.
   ```
2. **** (70% success)
   ```
   Install the build backend's runtime deps manually, or use legacy build: `pip install --no-build-isolation <pkg>` after `pip install setuptools wheel`.
   ```

## Dead Ends

- **** — The failure happens during metadata generation, not from a corrupted cache. (90% fail)
- **** — The same source distribution is fetched and fails identically. (70% fail)