pypa/pip · error · ImportError

No module named

Error message

No module named {module!r}

What it means

Raised by pip's import-audit hook during an install, not by normal user invocation. _prevent_import_hook (install.py:92) is installed via sys.addaudithook during _prevent_further_imports; it blocks re-import of modules recorded in _MISSING_MODULES — modules pip tried to eagerly import (_EAGER_IMPORTS) but that raised ImportError. If something then triggers import of such a module after install began, the hook raises ImportError('No module named {module!r}'). This is a safety mechanism to keep the install process from pulling in unexpected code from a freshly-installed distribution.

Solutions

1. Reinstall/repair pip itself: `python -m ensurepip --upgrade` or `python -m pip install --upgrade --force-reinstall pip`.
2. Inspect the full traceback to see what triggered the import after install started.
3. If a specific package's wheel triggers it, report the package interaction to pip's issue tracker.
4. Avoid installing packages that import pip internals at build/install time.

# Health-check that pip's eager-importable modules exist
import importlib.util

def pip_internals_intact():
    mods = [
        "pip._internal.operations.install.wheel",
    ]
    missing = [m for m in mods if importlib.util.find_spec(m) is None]
    if missing:
        raise ImportError("pip internals missing: %s — repair pip" % missing)
    return True

When it happens

Trigger: A module in _EAGER_IMPORTS (e.g. pip._internal.operations.install.wheel or pip._vendor.rich._windows_renderer) failed to import eagerly and was added to _MISSING_MODULES, then later code (possibly from a wheel being installed) attempts to import it, tripping the audit hook at install.py:96-97.

Common situations: A corrupt or partial pip installation where expected internal modules are missing; a wheel whose setup/build code triggers an import that collides with pip's internal modules; unusual packaging that imports pip internals during install.

Related errors

• Cannot determine archive format of
• Cannot set --home and --prefix together
• Cannot set --user and --prefix together
• Could not install locked package
• could not read file

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

Appendix: 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 f399c37189)