pypa/pip · error · ImportError

No module named {module!r}

Error message

No module named {module!r}

What it means

Raised by the audit hook _prevent_import_hook (install.py:92-97), installed via _prevent_further_imports during pip install. pip eagerly imports known lazy modules first; any that fail are recorded in _MISSING_MODULES. The hook then raises ImportError for any later 'import' audit event whose target is in that set, so that a freshly installed distribution cannot trigger an import pip already knows is broken. End users normally never see it; it surfaces when pip's own vendored/required modules are missing or corrupted and something triggers their import mid-install.

Source

Thrown at src/pip/_internal/commands/install.py:97

    "pip._internal.operations.install.wheel",
    # Used by rich when emitting output to a legacy Windows console.
    "pip._vendor.rich._windows_renderer",
)


# Imports of standard library modules are always safe: they cannot be
# shadowed by a distribution pip has just installed.
_STDLIB_MODULE_NAMES: frozenset[str] = frozenset(sys.stdlib_module_names) | frozenset(
    sys.builtin_module_names
)


def _prevent_import_hook(name: str, args: tuple[Any, ...]) -> None:
    if name != "import":
        return
    module = args[0]
    if module in _MISSING_MODULES:
        raise ImportError(f"No module named {module!r}")
    if module.partition(".")[0] in _STDLIB_MODULE_NAMES:
        return
    deprecated(
        reason=f"Unexpected import of {module!r} after pip install started.",
        replacement=None,
        gone_in="26.3",
        issue=13842,
        include_source=True,
        stacklevel=3,
    )


def _eagerly_import_modules() -> None:
    """Import modules pip uses lazily so the audit hook ignores them later."""
    for module in _EAGER_IMPORTS:
        try:
            __import__(module)
        except ImportError:

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Reinstall/repair pip itself: python -m ensurepip --upgrade or download get-pip.py and run it.
2. Run pip with -vv to see which module is reported missing in the traceback, then restore that file from a fresh pip wheel.
3. Avoid running a partially deleted pip tree; install pip into a clean virtualenv: python -m venv /tmp/pipfix && /tmp/pipfix/bin/pip install --upgrade pip.
4. If you maintain a forked/vendored pip, ensure the modules in _EAGER_IMPORTS are importable.

Example fix

// before
# pip tree is corrupted: pip/_vendor/rich/_windows_renderer.py deleted
pip install requests  # raises ImportError: No module named 'pip._vendor.rich._windows_renderer'
// after
curl -sS https://bootstrap.pypa.io/get-pip.py | python
tpip install requests

# Sanity-check pip's vendored tree is intact before relying on pip install
import importlib.util, sys
for mod in ("pip._internal.operations.install.wheel",):
    if importlib.util.find_spec(mod) is None:
        raise SystemExit(f"pip install is corrupted: {mod} missing; reinstall pip via get-pip.py")

# In a wrapper, catch ImportError from pip and prompt a self-repair
try:
    run_pip(["install", pkg])
except ImportError as e:
    if "No module named" in str(e):
        print("pip appears corrupted; run: python -m ensurepip --upgrade", file=sys.stderr)
        raise

When it happens

Trigger: During a pip install, after sys.addaudithook is registered, any code path (including a wheel's setup or an import inside pip) that does importlib.import_module / __import__ of a module recorded in _MISSING_MODULES. The set is populated by _eagerly_import_modules failing to import one of the _EAGER_IMPORTS (e.g. pip._internal.operations.install.wheel or pip._vendor.rich._windows_renderer).

Common situations: A corrupted/truncated pip installation where a vendored module (e.g. rich._windows_renderer) is missing; partial uninstall of pip; a broken filesystem; running a monkeypatched/forked pip; a wheel post-install hook that imports a module pip flagged missing.

Related errors

• Internal Error.
• Can not combine '--user' and '--target'
• Target path exists but is not a directory, will not continue
• failed-wheel-build-for-install
• Can not combine '--user' and '--prefix' as they imply differ

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