{"id":"a93d6db8d2ca6662","repo":"pypa/pip","slug":"error-while-importing-backend","errorCode":null,"errorMessage":"Error while importing backend","messagePattern":"Error while importing backend","errorType":"exception","errorClass":"BackendUnavailable","httpStatus":null,"severity":"critical","filePath":"src/pip/_vendor/pyproject_hooks/_impl.py","lineNumber":402,"sourceCode":"\n        with tempfile.TemporaryDirectory() as td:\n            hook_input = {\"kwargs\": kwargs}\n            write_json(hook_input, pjoin(td, \"input.json\"), indent=2)\n\n            # Run the hook in a subprocess\n            with _in_proc_script_path() as script:\n                python = self.python_executable\n                self._subprocess_runner(\n                    [python, abspath(str(script)), hook_name, td],\n                    cwd=self.source_dir,\n                    extra_environ=extra_environ,\n                )\n\n            data = read_json(pjoin(td, \"output.json\"))\n            if data.get(\"unsupported\"):\n                raise UnsupportedOperation(data.get(\"traceback\", \"\"))\n            if data.get(\"no_backend\"):\n                raise BackendUnavailable(\n                    data.get(\"traceback\", \"\"),\n                    message=data.get(\"backend_error\", \"\"),\n                    backend_name=self.build_backend,\n                    backend_path=self.backend_path,\n                )\n            if data.get(\"hook_missing\"):\n                raise HookMissing(data.get(\"missing_hook_name\") or hook_name)\n            return data[\"return_val\"]\n","sourceCodeStart":384,"sourceCodeEnd":411,"githubUrl":"https://github.com/pypa/pip/blob/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_vendor/pyproject_hooks/_impl.py#L384-L411","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure [build-system] requires lists the backend package (e.g. requires = ['setuptools>=61']).","Verify the build-backend string matches an installed module path exactly.","Inspect the attached .traceback to find the underlying ImportError and install the missing dependency.","If build isolation is the problem, retry with --no-build-isolation after installing build deps manually."],"exampleFix":"# before\n[build-system]\nrequires = [\"wheel\"]\nbuild-backend = \"setuptools.build_meta\"\n\n# after\n[build-system]\nrequires = [\"setuptools>=61\", \"wheel\"]\nbuild-backend = \"setuptools.build_meta\"","handlingStrategy":"try-catch","validationCode":"import importlib\nmod = build_backend.split(':')[0]\ntry:\n    importlib.import_module(mod)\nexcept ImportError as e:\n    raise RuntimeError(f'backend {mod} not importable: {e}') from e","typeGuard":null,"tryCatchPattern":"from pip._vendor.pyproject_hooks._impl import BackendUnavailable\ntry:\n    requires = hook.get_requires_for_build_wheel()\nexcept BackendUnavailable as e:\n    print('Backend import failed:', e.backend_name)\n    print(e.traceback)\n    raise","preventionTips":["Always list the backend in [build-system] requires.","Pre-import the backend module in a smoke test before building.","Inspect e.traceback to find the root ImportError."],"tags":["pyproject-hooks","pep517","build","dependencies","import"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}