error: subprocess-exited-with-error

What This Error Means

pip delegated part of the install to an external build step (PEP 517 backend or legacy setup.py) and that subprocess failed.

How to Fix It

1. Upgrade build tooling in the environment: python -m pip install -U pip setuptools wheel.
2. Install the OS-level build dependencies required by the package (compiler + development headers).
3. If possible, use a Python version and platform combination that has prebuilt wheels for the package.
4. Retry with --no-cache-dir -v to rule out corrupted cached downloads.
5. If the log shows a missing system library, install that library and retry.

Why It Happens

• A required system dependency or header is missing (common: Python headers, OpenSSL headers, libffi, etc.).
• A compiler/toolchain is missing (gcc/clang on Linux/macOS, MSVC Build Tools on Windows, Rust for some packages).
• The package doesn't support your Python version yet (so only source builds exist and they fail).
• The build backend (pyproject.toml build system) has a bug or missing build requirements.

How to Verify

1. Re-run python -m pip install <package> and confirm the build step completes without error.
2. Run python -c 'import <module>' (or run the package's self-test) to confirm installation is functional.

Manual build failure triage

1. Re-run with verbosity: python -m pip install -v <package> and scroll to the first compilation/build error above the summary.
2. Check whether a wheel should exist for your environment (Python version, OS, architecture).
3. Confirm build tools are present (compiler, headers, language toolchains like Rust if required).

Common CLI Output

error: subprocess-exited-with-error

note: This error originates from a subprocess, and is likely not a problem with pip.

error: metadata-generation-failed

Why pip runs subprocesses during installs

1. If a package doesn't have a compatible prebuilt wheel for your platform/Python, pip falls back to building from source.
2. For modern packages, this uses a PEP 517 build backend (run in a subprocess). For older packages, it may run setup.py.
3. pip reports a high-level error, but the real cause is usually earlier in the log (compiler errors, missing headers, missing build dependencies, or incompatible Python).

Prevention Tips

• Prefer wheels in CI by using supported Python versions and platforms.
• Document required OS dependencies for your project and install them in dev/CI images.
• Use an internal wheelhouse or cache to reduce variability in builds.

Where This Can Be Triggered

class InstallationSubprocessError(DiagnosticPipError, InstallationError):
    """A subprocess call failed."""

    reference = "subprocess-exited-with-error"

    def __init__(
        self,
        *,
        command_description: str,
        exit_code: int,
        output_lines: list[str] | None,
    ) -> None:
        if output_lines is None:
            output_prompt = Text("No available output.")
        else:
            output_prompt = (
                Text.from_markup(f"[red][{len(output_lines)} lines of output][/]\n")
                + Text("".join(output_lines))
                + Text.from_markup(R"[red]\\[end of output][/]")
            )

        super().__init__(
            message=(
                f"[green]{escape(command_description)}[/] did not run successfully.\n"
                f"exit code: {exit_code}"
            ),
            context=output_prompt,
            hint_stmt=None,
            note_stmt=(
                "This error originates from a subprocess, and is likely not a "
                "problem with pip."
            ),
        )

        self.command_description = command_description
        self.exit_code = exit_code

    def __str__(self) -> str:
        return f"{self.command_description} exited with {self.exit_code}"


class MetadataGenerationFailed(DiagnosticPipError, InstallationError):
    reference = "metadata-generation-failed"

    def __init__(
        self,
        *,
        package_details: str,
    ) -> None:
        super().__init__(
            message="Encountered error while generating package metadata.",
            context=escape(package_details),
            hint_stmt="See above for details.",
            note_stmt="This is an issue with the package mentioned above, not pip.",
        )