What Broke in the Build
pip is building a package from source, but your system is missing a required toolchain (C/C++ compiler, Python headers, MSVC Build Tools, or Rust).
Find the first real build failure
Work from the first concrete compiler or missing-library error upward. Once the local build prerequisites are in place, the higher-level package error usually disappears on its own.
Linux:install a build toolchain and Python dev headers (package names vary by distro).
macOS:install Xcode Command Line Tools (xcode-select --install) and retry.
Windows:install "Microsoft C++ Build Tools" / Visual Studio Build Tools, then retry.
If Rust is required, install Rust (commonly via rustup), then retry the pip install.
After installing toolchains, retry with python -m pip install --no-cache-dir -v <package>.
Find the first real build error
Run the install with -v and find the earliest compiler/toolchain error.
Check whether a wheel exists for your Python version/OS, if yes, upgrading pip may help it select the wheel.
If building from source is unavoidable, ensure your OS has compilers and Python dev headers installed.
Why the Build Fails
Usually this comes down to the package has no wheel for your Python/OS combination (so pip falls back to building), a minimal OS/container image is missing build tools (gcc, make, etc.), python development headers are missing (Python.h), or the package requires Rust to build from source.
Prove the Build Path Is Clean
Re-run the install and confirm compilation proceeds and finishes, and confirm the installed module imports successfully.
Typical Output
unable to execute 'gcc': No such file or directory
fatal error: Python.h: No such file or directory
Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools"
This package requires Rust >=1.41.0.Where the real build failure usually starts
Many Python packages include native extensions (C/C++/Rust) that must be compiled if no compatible wheel is available. pip invokes build backends that call system compilers and linkers. Missing toolchains/headers typically show up as compiler-not-found errors, missing Python.h, or requests to install MSVC/Rust.
Keep Build Prerequisites Consistent
To prevent this, use supported Python versions to maximize availability of prebuilt wheels, in CI, use base images that include build toolchains when needed, and prefer wheels (and consider an internal wheel cache) to reduce repeated source builds.
Docs and source code
github.com/pypa/pip/blob/25.3/src/pip/_internal/utils/subprocess.py
The specific toolchain errors (e.g. gcc not found, missing Python.h, missing MSVC/Rust) are emitted by the build subprocess, pip streams that output and then raises InstallationSubprocessError when the command returns non-zero. - GitHub
proc_had_error = proc.returncode and proc.returncode not in extra_ok_returncodes
if use_spinner:
assert spinner
if proc_had_error:
spinner.finish("error")
else:
spinner.finish("done")
if proc_had_error:
if on_returncode == "raise":
error = InstallationSubprocessError(
command_description=command_desc,
exit_code=proc.returncode,
output_lines=all_output if not showing_subprocess else None,
)
if log_failed_cmd:
subprocess_logger.error("%s", error, extra={"rich": True})
subprocess_logger.verbose(
"[bold magenta]full command[/]: [blue]%s[/]",
escape(format_command_args(cmd)),
extra={"markup": True},
)
raise error