# error: legacy-install-failure
× Encountered error while trying to install package.
╰─> numpy

note: This is an issue with the package mentioned above, not pip.

- **ID:** `pip/legacy-install-failure-numpy`
- **Domain:** pip
- **Category:** build_error
- **Error Code:** `error`
- **Verification:** ai_generated
- **Fix Rate:** 88%

## Root Cause

The package (e.g., numpy) requires a legacy build system (setup.py) that fails due to missing build dependencies or compiler issues, often because the package does not provide pre-built wheels for the platform.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| pip 21.0 | active | — | — |
| pip 23.0 | active | — | — |
| pip 24.0 | active | — | — |

## Workarounds

1. **Install a pre-built wheel if available: `pip install numpy --only-binary :all:` or use `pip install numpy==1.24.3` (a version with wheels for most platforms).** (90% success)
   ```
   Install a pre-built wheel if available: `pip install numpy --only-binary :all:` or use `pip install numpy==1.24.3` (a version with wheels for most platforms).
   ```
2. **Install system build dependencies: on Ubuntu, run `sudo apt-get install python3-dev build-essential`; on macOS, `xcode-select --install`.** (85% success)
   ```
   Install system build dependencies: on Ubuntu, run `sudo apt-get install python3-dev build-essential`; on macOS, `xcode-select --install`.
   ```
3. **Use conda as an alternative: `conda install numpy` which provides pre-compiled binaries.** (95% success)
   ```
   Use conda as an alternative: `conda install numpy` which provides pre-compiled binaries.
   ```

## Dead Ends

- **Reinstall pip and retry, assuming pip itself is broken.** — The error is from the package's build system, not pip's installation. (90% fail)
- **Use `pip install --no-build-isolation numpy` without fixing the underlying build tools.** — This may expose more errors but doesn't fix missing compilers or libraries. (70% fail)
- **Install numpy from a different index without verifying the version.** — The same build failure will occur if no pre-built wheel exists. (80% fail)