[cpp extension] Provide a clear error message when using inconsistent oneapi versions.

[ZhaoqiongZ]

🐛 Describe the bug

When the prebuilt wheels is built with oneapi 2025.0 and I use oneapi 2025.1 for cpp extension, the following error shows up

Could we provide a clear error message like "Error: Inconsistent OneAPI versions detected. Please check the version" for better UX

Steps to reproduce this issue

# Create conda env and install ninja by  
conda install ninja

# Install nightly wheels  , packages from oneapi 2025.0 included in this wheel  
pip3 install --pre torch==2.8.0.dev20250427+xpu  --index-url https://download.pytorch.org/whl/nightly/xpu


# Install oneapi 2025.1 by offline packages
wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/73863085-58a9-4dbb-ae65-83497edb05fa/intel-deep-learning-essentials-2025.1.2.13_offline.sh 
sudo sh ./intel-deep-learning-essentials-2025.1.2.13_offline.sh -a --silent --eula accept

# build & run cpp extension example
git clone https://github.com/ZhaoqiongZ/pytorch_examples.git
cd pytorch_examples/pytorch/extension-cpp-sycl

source /opt/intel/oneapi/setvars.sh
pip install --no-build-isolation -e .

This will cause the above libur_loader error

And if we uninstall pip installed oneapi and rebuild

pip uninstall intel-cmplr-lib-rt  intel-cmplr-lib-ur intel-cmplr-lic-rt intel-pti intel-sycl-rt
pip install --no-build-isolation -e .

Error related to pti package will appear.

Motivation for this issue

When users install PyTorch wheels (which bundle several packages in specific oneapi version), they are often unaware of the implicit oneAPI dependency.

When build with sycl extension, users also need install the entire oneAPI packages (e.g., from Intel’s official sources) into their environment and source activate the env.

However, there is a time gap between Intel’s oneAPI release and PyTorch’s support for the new version.

When a oneAPI version mismatch occurs, the error messages shown is inconsistent with different scenario and do not explicitly indicate the root cause (oneAPI incompatibility). These cryptic error messages reference internal dependency packages (e.g., pti / libur_loader etc), which are unfamiliar to users. Consequently, users cannot determine how to resolve the version mismatch because they are unaware of the purpose of these dependencies.

Improve the error handling logic to detect oneAPI version mismatches explicitly. When detected, surface a clear, actionable error message that:

Clearly states the root cause: "oneAPI component version mismatch detected."
Lists the conflicting packages and their detected versions
Provides direct steps to resolve the issue, such as:

To fix this,

1. let user know which oneapi packages is installed with current pytorch wheel
2. where can user install oneapi which match the current pytorch wheel

Versions

Collecting environment information...
PyTorch version: 2.8.0.dev20250427+xpu
Is debug build: False
CUDA used to build PyTorch: None
ROCM used to build PyTorch: N/A

OS: Ubuntu 24.10 (x86_64)
GCC version: (Ubuntu 14.2.0-4ubuntu2) 14.2.0
Clang version: Could not collect
CMake version: version 3.31.6
Libc version: glibc-2.40

Python version: 3.10.17 | packaged by conda-forge | (main, Apr 10 2025, 22:19:12) [GCC 13.3.0] (64-bit runtime)
Python platform: Linux-6.11.0-24-generic-x86_64-with-glibc2.40
Is CUDA available: False
CUDA runtime version: No CUDA
CUDA_MODULE_LOADING set to: N/A
GPU models and configuration: No CUDA
Nvidia driver version: No CUDA
cuDNN version: No CUDA
HIP runtime version: N/A
MIOpen runtime version: N/A
Is XNNPACK available: True

CPU:
Architecture: x86_64
CPU op-mode(s): 32-bit, 64-bit
Address sizes: 39 bits physical, 48 bits virtual
Byte Order: Little Endian
CPU(s): 6
On-line CPU(s) list: 0-5
Vendor ID: GenuineIntel
Model name: Intel(R) Core(TM) i5-9600K CPU @ 3.70GHz
CPU family: 6
Model: 158
Thread(s) per core: 1
Core(s) per socket: 6
Socket(s): 1
Stepping: 13
CPU(s) scaling MHz: 37%
CPU max MHz: 4600.0000
CPU min MHz: 800.0000
BogoMIPS: 7399.70
Flags: fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush dts acpi mmx fxsr sse sse2 ss ht tm pbe syscall nx pdpe1gb rdtscp lm constant_tsc art arch_perfmon pebs bts rep_good nopl xtopology nonstop_tsc cpuid aperfmperf pni pclmulqdq dtes64 monitor ds_cpl vmx smx est tm2 ssse3 sdbg fma cx16 xtpr pdcm pcid sse4_1 sse4_2 x2apic movbe popcnt tsc_deadline_timer aes xsave avx f16c rdrand lahf_lm abm 3dnowprefetch cpuid_fault epb ssbd ibrs ibpb stibp ibrs_enhanced tpr_shadow flexpriority ept vpid ept_ad fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid mpx rdseed adx smap clflushopt intel_pt xsaveopt xsavec xgetbv1 xsaves dtherm ida arat pln pts hwp hwp_notify hwp_act_window hwp_epp vnmi md_clear flush_l1d arch_capabilities
Virtualization: VT-x
L1d cache: 192 KiB (6 instances)
L1i cache: 192 KiB (6 instances)
L2 cache: 1.5 MiB (6 instances)
L3 cache: 9 MiB (1 instance)
NUMA node(s): 1
NUMA node0 CPU(s): 0-5
Vulnerability Gather data sampling: Mitigation; Microcode
Vulnerability Itlb multihit: KVM: Mitigation: VMX disabled
Vulnerability L1tf: Not affected
Vulnerability Mds: Not affected
Vulnerability Meltdown: Not affected
Vulnerability Mmio stale data: Mitigation; Clear CPU buffers; SMT disabled
Vulnerability Reg file data sampling: Not affected
Vulnerability Retbleed: Mitigation; Enhanced IBRS
Vulnerability Spec rstack overflow: Not affected
Vulnerability Spec store bypass: Mitigation; Speculative Store Bypass disabled via prctl
Vulnerability Spectre v1: Mitigation; usercopy/swapgs barriers and __user pointer sanitization
Vulnerability Spectre v2: Mitigation; Enhanced / Automatic IBRS; IBPB conditional; RSB filling; PBRSB-eIBRS SW sequence; BHI SW loop, KVM SW loop
Vulnerability Srbds: Mitigation; Microcode
Vulnerability Tsx async abort: Mitigation; TSX disabled

Versions of relevant libraries:
[pip3] numpy==2.1.2
[pip3] pytorch-triton-xpu==3.3.0+git0bcc8265
[pip3] torch==2.8.0.dev20250427+xpu
[pip3] torchaudio==2.6.0.dev20250428+xpu
[pip3] torchvision==0.22.0.dev20250428+xpu
[conda] numpy 2.1.2 pypi_0 pypi
[conda] pytorch-triton-xpu 3.3.0+git0bcc8265 pypi_0 pypi
[conda] torch 2.8.0.dev20250427+xpu pypi_0 pypi
[conda] torchaudio 2.6.0.dev20250428+xpu pypi_0 pypi
[conda] torchvision 0.22.0.dev20250428+xpu pypi_0 pypi

[dvrogozh]

I was expecting this issue... Yes, that's one of the improvements we need to incorporate. Thank you for filing.

[dvrogozh]

I think that the issue which user will face mixing different torch builds with different oneapi environments is highly dependent on the usage scenarios. For example, consider the very basic pytorch developer usage scenario when user builds pytorch itself with oneapi 2025.0. I.e.:

. /opt/intel/oneapi/compiler/2025.0/env/vars.sh
. /opt/intel/oneapi/umf/0.9/env/vars.sh
. /opt/intel/oneapi/pti/0.10/env/vars.sh
. /opt/intel/oneapi/ccl/2021.14//env/vars.sh
cd pytorch && python3 setup.py develop

Then if user activates 2025.1 environment, he will get this just importing torch:

. /opt/intel/oneapi/compiler/2025.0/env/vars.sh
. /opt/intel/oneapi/umf/0.9/env/vars.sh
. /opt/intel/oneapi/pti/0.10/env/vars.sh
. /opt/intel/oneapi/ccl/2021.14//env/vars.sh
python3 -c "import torch"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/dvrogozh/git/pytorch/pytorch/torch/__init__.py", line 419, in <module>
    from torch._C import *  # noqa: F403
    ^^^^^^^^^^^^^^^^^^^^^^
ImportError: libpti_view.so.0.10: cannot open shared object file: No such file or directory

And the error signature will change depending on which libraries will be found in the path and which exact step user has taken to activate oneapi environment.

So, one thing we need to do before digging into this issue is to itemize key usage scenarios we can face around this story.

[dvrogozh]

And if we uninstall pip installed oneapi and rebuild <..> Error related to pti package will appear.

@ZhaoqiongZ, this part needs to be clarified. If you completely uninstall oneapi, then you should not be able to rebuild extension with sycl kernels at all as compiler will be missing. And if you mean that you uninstall oneapi 2025.1 and install 2025.0, then all should work ok as 2025.0 corresponds to the oneapi used to build pytorch.

[dvrogozh]

I think there are the following cases we need to consider at the moment:

• User installs pytorch xpu from wheels and activates oneAPI environment. Eventually, there are 3 cases depending on which oneAPI environment he activates (version B) in relevance to what oneAPI environment was used to build installed pytorch version (version A):
  • Versions match - everything's good
  • B > A - that's backward compatibility case. This should work to import torch, but currently fails. Basically that's the case @ZhaoqiongZ described in the issue. At the moment the failure here is actually not CPP extension issue - that's import torch issue and an be reproduced with:

$ python3 -c "import torch"
  File "/home/dvrogozh/pytorch.xpu2/lib/python3.12/site-packages/torch/__init__.py", line 418, in <module>
    from torch._C import *  # noqa: F403
    ^^^^^^^^^^^^^^^^^^^^^^
ImportError: /opt/intel/oneapi/2025.1/lib/libur_loader.so.0: version `LIBUR_LOADER_0.10' not found (required by /home/dvrogozh/pytorch.xpu2/lib/python3.12/site-packages/torch/lib/../../../../libsycl.so.8)

• A < B - that's forward compatibility case. It should not work unless compatibility package exists and is installed.

• User builds extension with wrong pytorch version. Basically that's what will happen if user does not specify XPU index in extension pip install command. Extension will get built, but it will be unclear with which pytorch version it is compatible as it was built using pytorch where XPU support was not included at all. We can add a check to SYCL CPP extension to avoid such use case entirely.

$ git clone https://github.com/ZhaoqiongZ/pytorch_examples.git
$ cd pytorch_examples/pytorch/extension-cpp-sycl

$ source /opt/intel/oneapi/setvars.sh
$ pip install -e .  # mind no --no-build-isolation

... here default CUDA torch version will be installed
... instead user should have used --index-url https://download.pytorch.org/whl/nightly/xpu

Further, if oneAPI backward compatibility will get fixed to import torch, then additional question for B >A case is whether extensions built with B should work with A. Here we step into forward compatibility and this might not work without compatibility packages.

[chuanqi129]

@dvrogozh if we has dependencies on oneAPI, please submit the request to them