docling-project/docling · error · AcceleratorDeviceNotAvailableError

XPU is not available in the system. Please ensure PyTorch wi

Error message

XPU is not available in the system. Please ensure PyTorch with Intel XPU support is installed, or use --device auto/cpu.

What it means

AcceleratorDeviceNotAvailableError raised by decide_device() when the user requests 'xpu' but the runtime lacks Intel XPU: torch has no 'xpu' attribute or torch.xpu.is_available() is false. PyTorch must be a build with Intel XPU support (e.g. intel-extension builds / upstream XPU-enabled wheels) and an Intel GPU driver must be present.

Source

Thrown at docling/utils/accelerator_utils.py:119

        else:
            raise AcceleratorDeviceNotAvailableError(
                "MPS is not available in the system. "
                "Please ensure you are running on Apple Silicon with MPS support, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.XPU.value:
        if (
            supported_devices is not None
            and AcceleratorDevice.XPU not in supported_devices
        ):
            raise AcceleratorDeviceNotAvailableError(
                f"XPU is not supported by this model. Supported devices: {[d.value for d in supported_devices]}"
            )

        if has_xpu:
            device = "xpu"
        else:
            raise AcceleratorDeviceNotAvailableError(
                "XPU is not available in the system. "
                "Please ensure PyTorch with Intel XPU support is installed, or use --device auto/cpu."
            )

    elif accelerator_device == AcceleratorDevice.CPU.value:
        device = "cpu"

    else:
        raise AcceleratorDeviceNotAvailableError(
            f"Unknown device option '{accelerator_device}'. "
            f"Valid options are: auto, cpu, cuda, mps, xpu, or cuda:N"
        )

    _log.info("Accelerator device: '%s'", device)
    return device

View on GitHub (pinned to 61d76f1ff3)

Solutions

Verify with python -c "import torch; print(hasattr(torch, 'xpu') and torch.xpu.is_available())"
Install a PyTorch build with Intel XPU support and matching drivers (intel-extension-for-pytorch where required)
Or switch to accelerator_device='auto'/'cpu'
Keep the xpu setting scoped to the Intel GPU hosts only

Example fix

# before
accelerator_options.accelerator_device = "xpu"  # stock torch wheel

# after
accelerator_options.accelerator_device = "auto"

Defensive patterns

Strategy: validation

Validate before calling

import torch

xpu_ok = hasattr(torch, "xpu") and torch.xpu.is_available()
if not xpu_ok:
    accelerator_options.accelerator_device = "auto"

Type guard

def xpu_available() -> bool:
    import torch
    return hasattr(torch, "xpu") and torch.xpu.is_available()

Try / catch

from docling.exceptions import AcceleratorDeviceNotAvailableError

try:
    device = decide_device("xpu")
except AcceleratorDeviceNotAvailableError:
    device = decide_device("auto")

Prevention

Check hasattr(torch, 'xpu') and torch.xpu.is_available() before requesting XPU
Install XPU-enabled PyTorch builds with matching Intel drivers
Don't reuse Intel-node configs on CUDA/CPU machines
Use 'auto' for portable configuration

When it happens

Trigger: Setting accelerator_device='xpu' on machines without Intel discrete GPUs, with stock CPU/CUDA PyTorch wheels (no torch.xpu module), or with missing/old Intel GPU drivers; also when supported_devices filtering cleared the has_xpu flag.

Common situations: Config written for Intel GPU nodes run elsewhere; installing regular pip torch which lacks XPU; driver/intel-extension version mismatch after upgrades.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/e26ccda86a69135e. Report an issue: GitHub.