opendatalab/MinerU · critical · RuntimeError

NPU is selected as device, but torch_npu is not available. P

Error message

NPU is selected as device, but torch_npu is not available. Please ensure that the torch_npu package is installed correctly.

What it means

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.

Source

Thrown at mineru/backend/pipeline/model_init.py:354

            lang=None,
            formula_enable=True,
    ):
        if device is not None:
            self.device = device
        else:
            self.device = get_device()

        self.lang = lang

        self.enable_ocr_det_batch = ocr_det_batch_setting()

        if str(self.device).startswith('npu'):
            try:
                import torch_npu
                if torch_npu.npu.is_available():
                    torch_npu.npu.set_compile_mode(jit_compile=False)
            except Exception as e:
                raise RuntimeError(
                    "NPU is selected as device, but torch_npu is not available. "
                    "Please ensure that the torch_npu package is installed correctly."
                ) from e

        self.atom_model_manager = AtomModelSingleton()

        # 初始化OCR模型
        self.ocr_model = self.atom_model_manager.get_atom_model(
            atom_model_name=AtomicModel.OCR,
            lang=self.lang
        )

        # 初始化layout模型，用于提供行内公式检测框和Hybrid标题拆分
        self.layout_model = self.atom_model_manager.get_atom_model(
            atom_model_name=AtomicModel.Layout,
            pp_doclayout_v2_weights=str(
                os.path.join(
                    auto_download_and_get_model_root_path(ModelPath.pp_doclayout_v2),

View on GitHub (pinned to 4fe4bde114)

Solutions

1. pip install torch_npu matching your torch version (check the Ascend version-compatibility matrix).
2. Verify Ascend drivers/CANN: run npu-smi info and source the CANN set_env.sh.
3. Confirm torch_npu.npu.is_available() returns True in a plain python -c check before rerunning MinerU.
4. If you did not intend NPU, override the device (e.g. device=cpu/cuda) instead of relying on auto-detection.

Example fix

# before (fails)
python -c "import torch_npu; torch_npu.npu.is_available()"  # ImportError

# after
pip install torch==2.x.y torch-npu==2.x.y.post1  # matching pair
source /usr/local/Ascend/ascend-toolkit/set_env.sh
python -c "import torch, torch_npu; print(torch.npu.is_available())"  # True

def npu_ready() -> bool:
    try:
        import torch_npu
        return torch_npu.npu.is_available()
    except Exception:
        return False

# before selecting device=npu:
assert npu_ready(), "install torch_npu + CANN before using NPU"

try:
    manager = ModelSingleton()
except RuntimeError as e:
    if "torch_npu" in str(e):
        device = "cpu"  # or raise with ops context
        manager = ModelSingleton()
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• NPU is selected as device, but torch_npu is not available. P
• CUDA is not available.
• Unsupported lmdeploy device type: {device_type}
• Unsupported lmdeploy device type: {device_type}
• Local worker {server_id} exited before becoming healthy

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/c405a72ad64f5f81. Report an issue: GitHub.