pypa/pip · error · InstallationError

For req: {req_description}. {e.args[0]}

Error message

For req: {req_description}. {e.args[0]}

What it means

This is not a standalone error but the req_error_context() context manager (wheel.py:732-738) that wraps _install_wheel. It catches any InstallationError raised during the install of a wheel and re-raises a new InstallationError prefixed with 'For req: <description>. ', so the user sees which requirement caused the inner failure (e.g. a MissingCallableSuffix, path-traversal, or scheme error).

Source

Thrown at src/pip/_internal/operations/install/wheel.py:738

    )

    # Record details of all files installed
    record_path = os.path.join(dest_info_dir, "RECORD")

    with _generate_file(record_path, **csv_io_kwargs("w")) as record_file:
        # Explicitly cast to typing.IO[str] as a workaround for the mypy error:
        # "writer" has incompatible type "BinaryIO"; expected "_Writer"
        writer = csv.writer(cast("IO[str]", record_file))
        writer.writerows(_normalized_outrows(rows))


@contextlib.contextmanager
def req_error_context(req_description: str) -> Generator[None, None, None]:
    try:
        yield
    except InstallationError as e:
        message = f"For req: {req_description}. {e.args[0]}"
        raise InstallationError(message) from e


def install_wheel(
    name: str,
    wheel_path: str,
    scheme: Scheme,
    req_description: str,
    pycompile: bool = True,
    warn_script_location: bool = True,
    direct_url: DirectUrl | None = None,
    requested: bool = False,
    script_executable: str | None = None,
) -> None:
    with ZipFile(wheel_path, allowZip64=True) as z:
        with req_error_context(req_description):
            _install_wheel(
                name=name,
                wheel_zip=z,

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Read the message after 'For req:' to identify which requirement's wheel failed, then read the inner message (and the chained exception) for the root cause.
2. Apply the fix corresponding to the underlying error (entry point, path traversal, scheme key, .data layout).
3. Rebuild/reinstall that specific requirement in isolation: pip install --force-reinstall --no-deps <that-req>.
4. Pin or upgrade/downgrade the problematic requirement to a version with a valid wheel.

Example fix

# the message reads:
# For req: mypkg. Invalid script entry point: mypkg.cli ...
# fix the entry point in mypkg's build config, then:
pip install --force-reinstall --no-deps ./mypkg-1.0-py3-none-any.whl

from pip._internal.exceptions import InstallationError
try:
    install_wheel(name, wheel_path, scheme, req_description)
except InstallationError as e:
    # e.__cause__ holds the original inner error (MissingCallableSuffix, etc.)
    logger.error("install of %s failed: %s", req_description, e.__cause__)
    raise

When it happens

Trigger: Any InstallationError raised inside _install_wheel (called from install_wheel) is caught and re-tagged with the req_description. The original exception is chained via 'from e'. The visible message is the inner error's args[0] with the requirement name prepended.

Common situations: Any of the wheel-install errors (102-106) occurring during a pip install of a specific requirement; the wrapper surfaces the requirement name so you know which package's wheel is broken.

Related errors

• Invalid script entry point: {entry_point} - A callable suffi
• Unexpected file in {wheel_path}: {record_path!r}. .data dire
• Unknown scheme key used in {wheel_path}: {scheme_key} (for f
• Invalid script entry point name {entry.name!r}: the script w
• The wheel {wheel_path!r} has a file {target_path!r} trying t

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/d057f8b0f4c86c73.json. Report an issue: GitHub.