pypa/pip · critical · BackendUnavailable

Error while importing backend

Error message

Error while importing backend

What it means

pyproject_hooks raises BackendUnavailable with this default message when the build backend, invoked in a subprocess, signals 'no_backend' - meaning the backend module named in [build-system] build-backend could not be imported. The actual ImportError traceback is attached as .traceback and a more specific message (if any) overrides this default.

Source

Thrown at src/pip/_vendor/pyproject_hooks/_impl.py:402

        with tempfile.TemporaryDirectory() as td:
            hook_input = {"kwargs": kwargs}
            write_json(hook_input, pjoin(td, "input.json"), indent=2)

            # Run the hook in a subprocess
            with _in_proc_script_path() as script:
                python = self.python_executable
                self._subprocess_runner(
                    [python, abspath(str(script)), hook_name, td],
                    cwd=self.source_dir,
                    extra_environ=extra_environ,
                )

            data = read_json(pjoin(td, "output.json"))
            if data.get("unsupported"):
                raise UnsupportedOperation(data.get("traceback", ""))
            if data.get("no_backend"):
                raise BackendUnavailable(
                    data.get("traceback", ""),
                    message=data.get("backend_error", ""),
                    backend_name=self.build_backend,
                    backend_path=self.backend_path,
                )
            if data.get("hook_missing"):
                raise HookMissing(data.get("missing_hook_name") or hook_name)
            return data["return_val"]

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Ensure [build-system] requires lists the backend package (e.g. requires = ['setuptools>=61']).
2. Verify the build-backend string matches an installed module path exactly.
3. Inspect the attached .traceback to find the underlying ImportError and install the missing dependency.
4. If build isolation is the problem, retry with --no-build-isolation after installing build deps manually.

Example fix

# before
[build-system]
requires = ["wheel"]
build-backend = "setuptools.build_meta"

# after
[build-system]
requires = ["setuptools>=61", "wheel"]
build-backend = "setuptools.build_meta"

import importlib
mod = build_backend.split(':')[0]
try:
    importlib.import_module(mod)
except ImportError as e:
    raise RuntimeError(f'backend {mod} not importable: {e}') from e

from pip._vendor.pyproject_hooks._impl import BackendUnavailable
try:
    requires = hook.get_requires_for_build_wheel()
except BackendUnavailable as e:
    print('Backend import failed:', e.backend_name)
    print(e.traceback)
    raise

When it happens

Trigger: BuildBackendHookCaller._call_hook runs the in-process script; if importing the backend fails (missing module, missing dependency of the backend, syntax error), the subprocess writes no_backend=true and the parent re-raises BackendUnavailable. Common when pip/build try to build a package whose declared backend (e.g. setuptools.build_meta, flit_core, hatchling) is not installed in the build environment.

Common situations: The build backend package is not installed in the isolated build env; build-system.requires in pyproject.toml omits the backend; a typo in build-backend (e.g. 'setuptools.build_meta:__legacy__' vs a misspelled module); network failure preventing the backend wheel from installing during build isolation.

Related errors

• Cannot import {mod_path!r}
• 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/a93d6db8d2ca6662.json. Report an issue: GitHub.