pypa/pip · critical · BackendUnavailable

Cannot import {mod_path!r}

Error message

Cannot import {mod_path!r}

What it means

Inside the in-process subprocess, _build_backend() raises BackendUnavailable('Cannot import {mod_path!r}') when import_module(mod_path) fails with ImportError and no backend-path finder is in play. mod_path is the module portion of the build-backend spec (before any ':'). The full traceback is captured and propagated back to the parent process.

Source

Thrown at src/pip/_vendor/pyproject_hooks/_in_process/_in_process.py:73

        self.hook_name = hook_name


def _build_backend():
    """Find and load the build backend"""
    backend_path = os.environ.get("_PYPROJECT_HOOKS_BACKEND_PATH")
    ep = os.environ["_PYPROJECT_HOOKS_BUILD_BACKEND"]
    mod_path, _, obj_path = ep.partition(":")

    if backend_path:
        # Ensure in-tree backend directories have the highest priority when importing.
        extra_pathitems = backend_path.split(os.pathsep)
        sys.meta_path.insert(0, _BackendPathFinder(extra_pathitems, mod_path))

    try:
        obj = import_module(mod_path)
    except ImportError:
        msg = f"Cannot import {mod_path!r}"
        raise BackendUnavailable(msg, traceback.format_exc())

    if obj_path:
        for path_part in obj_path.split("."):
            obj = getattr(obj, path_part)
    return obj


class _BackendPathFinder:
    """Implements the MetaPathFinder interface to locate modules in ``backend-path``.

    Since the environment provided by the frontend can contain all sorts of
    MetaPathFinders, the only way to ensure the backend is loaded from the
    right place is to prepend our own.
    """

    def __init__(self, backend_path, backend_module):
        self.backend_path = backend_path
        self.backend_module = backend_module

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Add the backend package to [build-system] requires in pyproject.toml.
2. Correct any typo in the build-backend module path.
3. Install the backend and its dependencies into the build environment (or use --no-build-isolation and pip install them first).
4. Read the captured traceback to find the precise ImportError and fix the named missing module.

Example fix

# before
build-backend = "flit_core.buildapi"
requires = ["wheel"]

# after
build-backend = "flit_core.buildapi"
requires = ["flit_core>=3.2", "wheel"]

import importlib.util
mod = build_backend.split(':')[0]
if importlib.util.find_spec(mod) is None:
    raise RuntimeError(f'backend module {mod} is not installed')

try:
    backend = _build_backend()
except BackendUnavailable as e:
    log.error('cannot import backend %s: %s', e.message, e.traceback)
    raise

When it happens

Trigger: The build-backend module name (e.g. 'flit_core.buildapi') cannot be imported in the build environment: the package is absent, or one of its imports fails. This is the subprocess-side cause that surfaces in the parent as BackendUnavailable.

Common situations: Backend package not in build-system.requires; backend installed but a transitive dependency missing; Python version mismatch breaking an import; a typo in the module portion of build-backend.

Related errors

• Error while importing backend
• Cannot find module {self.backend_module!r} in {self.backend_
• Some build dependencies for {requirement} conflict with {con
• Some build dependencies for {requirement} are missing: {miss
• paths must be relative

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