# error: subprocess-exited-with-error: Cython.Compiler.Errors.CompileError: /path/to/file.pyx:1:0: 'header.h' not found

- **ID:** `pip/error-from-pip-subprocess-to-build-wheel-with-missing-cython-header`
- **Domain:** pip
- **Category:** build_error
- **Error Code:** `error`
- **Verification:** ai_generated
- **Fix Rate:** 82%

## Root Cause

A Cython extension requires a C header file that is missing from the system's include path or the package's source distribution.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| pip 21.3+ | active | — | — |
| Python 3.8-3.12 | active | — | — |
| Cython 0.29.x, 3.0.x | active | — | — |
| setuptools 58+ | active | — | — |

## Workarounds

1. **Install the system development package: sudo apt-get install libfoo-dev  # Debian/Ubuntu, or sudo yum install libfoo-devel  # RHEL/CentOS** (90% success)
   ```
   Install the system development package: sudo apt-get install libfoo-dev  # Debian/Ubuntu, or sudo yum install libfoo-devel  # RHEL/CentOS
   ```
2. **pip install <package> --no-binary :all: --global-option='build_ext' --global-option='-I/path/to/include'** (75% success)
   ```
   pip install <package> --no-binary :all: --global-option='build_ext' --global-option='-I/path/to/include'
   ```
3. **Use a pre-built wheel from an alternative index: pip install <package> --only-binary :all: -i https://download.pytorch.org/whl/cpu  # Example for PyTorch with CPU-only** (80% success)
   ```
   Use a pre-built wheel from an alternative index: pip install <package> --only-binary :all: -i https://download.pytorch.org/whl/cpu  # Example for PyTorch with CPU-only
   ```

## Dead Ends

- **Installing the missing header via pip (e.g., pip install libfoo-dev)** — Header files are usually provided by system packages (e.g., libfoo-dev on Debian/Ubuntu), not Python packages. (85% fail)
- **Using --no-build-isolation to use the host environment's Cython version** — The error is about a missing header, not Cython version mismatch; build isolation does not affect header availability. (90% fail)
- **Setting CFLAGS environment variable to point to a custom include path** — While this can work, many users incorrectly set the path or use wrong syntax; also requires knowing the exact header location. (60% fail)