{"record":{"id":"c405a72ad64f5f81","repo":"opendatalab/MinerU","slug":"npu-is-selected-as-device-but-torch-npu-is-not-av","errorCode":null,"errorMessage":"NPU is selected as device, but torch_npu is not available. Please ensure that the torch_npu package is installed correctly.","messagePattern":"NPU is selected as device, but torch_npu is not available\\. Please ensure that the torch_npu package is installed correctly\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"mineru/backend/pipeline/model_init.py","lineNumber":354,"sourceCode":"            lang=None,\n            formula_enable=True,\n    ):\n        if device is not None:\n            self.device = device\n        else:\n            self.device = get_device()\n\n        self.lang = lang\n\n        self.enable_ocr_det_batch = ocr_det_batch_setting()\n\n        if str(self.device).startswith('npu'):\n            try:\n                import torch_npu\n                if torch_npu.npu.is_available():\n                    torch_npu.npu.set_compile_mode(jit_compile=False)\n            except Exception as e:\n                raise RuntimeError(\n                    \"NPU is selected as device, but torch_npu is not available. \"\n                    \"Please ensure that the torch_npu package is installed correctly.\"\n                ) from e\n\n        self.atom_model_manager = AtomModelSingleton()\n\n        # 初始化OCR模型\n        self.ocr_model = self.atom_model_manager.get_atom_model(\n            atom_model_name=AtomicModel.OCR,\n            lang=self.lang\n        )\n\n        # 初始化layout模型，用于提供行内公式检测框和Hybrid标题拆分\n        self.layout_model = self.atom_model_manager.get_atom_model(\n            atom_model_name=AtomicModel.Layout,\n            pp_doclayout_v2_weights=str(\n                os.path.join(\n                    auto_download_and_get_model_root_path(ModelPath.pp_doclayout_v2),","sourceCodeStart":336,"sourceCodeEnd":372,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/backend/pipeline/model_init.py#L336-L372","documentation":"Raised by the pipeline ModelSingleton when the selected device starts with 'npu' but torch_npu cannot be imported or initialized. The code imports torch_npu and calls npu.is_available(); any exception (missing package, broken Ascend drivers, malformed install) is chained into this RuntimeError. Its purpose is to give an actionable message instead of a bare ImportError deep in model loading.","triggerScenarios":"MINERU_DEVICE_MODEL=device=npu or auto-detected NPU with torch_npu not installed, an incompatible torch_npu/torch version pair, or Ascend CANN toolkit/runtime not properly configured so npu.is_available() throws.","commonSituations":"Ascend 910/310 environments where torch_npu was built against a different torch version; missing or mismatched CANN toolkit; setting device=npu on a machine without Ascend hardware.","solutions":["pip install torch_npu matching your torch version (check the Ascend version-compatibility matrix).","Verify Ascend drivers/CANN: run npu-smi info and source the CANN set_env.sh.","Confirm torch_npu.npu.is_available() returns True in a plain python -c check before rerunning MinerU.","If you did not intend NPU, override the device (e.g. device=cpu/cuda) instead of relying on auto-detection."],"exampleFix":"# before (fails)\npython -c \"import torch_npu; torch_npu.npu.is_available()\"  # ImportError\n\n# after\npip install torch==2.x.y torch-npu==2.x.y.post1  # matching pair\nsource /usr/local/Ascend/ascend-toolkit/set_env.sh\npython -c \"import torch, torch_npu; print(torch.npu.is_available())\"  # True","handlingStrategy":"validation","validationCode":"def npu_ready() -> bool:\n    try:\n        import torch_npu\n        return torch_npu.npu.is_available()\n    except Exception:\n        return False\n\n# before selecting device=npu:\nassert npu_ready(), \"install torch_npu + CANN before using NPU\"","typeGuard":null,"tryCatchPattern":"try:\n    manager = ModelSingleton()\nexcept RuntimeError as e:\n    if \"torch_npu\" in str(e):\n        device = \"cpu\"  # or raise with ops context\n        manager = ModelSingleton()\n    else:\n        raise","preventionTips":["Install torch_npu strictly matching the torch version; pin both in requirements.","Source CANN set_env.sh in service unit files / container entrypoints.","Add a startup probe (npu-smi info + torch_npu import) before enabling NPU."],"tags":["npu","ascend","environment","torch-npu","device"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}