What This Error Means
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).
How to Fix It
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>.
Why It Happens
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).
The package requires Rust to build from source.
How to Verify
Re-run the install and confirm compilation proceeds and finishes.
Confirm the installed module imports successfully.
Manual toolchain checks
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.
Examples
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.Why pip needs compilers and headers
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.
Prevention Tips
Use supported Python versions to maximize availability of prebuilt wheels.
In CI, use base images that include build toolchains when needed.
Prefer wheels (and consider an internal wheel cache) to reduce repeated source builds.
Where This Can Be Triggered
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