Which PIP versions are affected by pip:BUILD_TOOLCHAIN_MISSING?

All pip versions (this is a system dependency issue).

How can I manually validate pip:BUILD_TOOLCHAIN_MISSING?

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.

How do I prevent pip:BUILD_TOOLCHAIN_MISSING in CI?

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.

RepoFlow | Build toolchain missing (gcc / Python.h / MSVC / Rust)

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.

Common CLI 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.

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