Intel oneAPI DPC++/C++ Compiler Runtime

2025.3.3 · active · verified Fri Apr 17

The `dpcpp-cpp-rt` package provides the essential runtime libraries and components for applications compiled with the Intel® oneAPI DPC++/C++ Compiler. It is a critical dependency for Python libraries like `dpctl` and `numba-dppy` that leverage SYCL for heterogeneous computing. This package primarily provides shared objects and header files, not directly imported Python modules. It aligns with the Intel oneAPI release cadence, typically receiving annual major updates and more frequent minor revisions.

Common errors

```
ModuleNotFoundError: No module named 'dpcpp_cpp_rt'
```
cause The `dpcpp-cpp-rt` package provides C++ runtime libraries, not a Python module that can be directly imported. Python attempts to find a Python module named `dpcpp_cpp_rt`, which does not exist.

fix This is expected behavior. The `dpcpp-cpp-rt` package is a backend dependency. Instead of importing it, ensure it's installed and correctly configured in your environment for Python libraries that depend on it (e.g., `import dpctl`).
```
dpctl.SyclQueueCreationError: No SYCL device found.
```
cause While `dpcpp-cpp-rt` might be installed, the SYCL runtime cannot discover any compatible devices, or `SYCL_DEVICE_FILTER` might be set too restrictively, or the oneAPI environment is not properly sourced.

fix 1. Ensure the oneAPI `setvars.sh`/`setvars.bat` script is sourced. 2. Verify hardware compatibility (Intel GPU/CPU, or OpenCL/CUDA backend). 3. Check `SYCL_DEVICE_FILTER` environment variable (e.g., `export SYCL_DEVICE_FILTER='opencl:gpu,cpu'` for broader device selection or `export SYCL_DEVICE_FILTER='level_zero:gpu'` for Intel GPUs). 4. Reinstall `dpcpp-cpp-rt` and `dpctl` from official channels.
```
ImportError: libdpcpp_common.so: cannot open shared object file: No such file or directory
```
cause The dynamic linker cannot find the necessary shared libraries provided by `dpcpp-cpp-rt`. This usually means the `LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS) environment variable is not correctly set.

fix Source the oneAPI `setvars.sh` (Linux/macOS) or `setvars.bat` (Windows) script. This script correctly sets up all necessary environment variables, including `PATH` and `LD_LIBRARY_PATH`, to point to the oneAPI component directories.

Warnings

gotcha The `dpcpp-cpp-rt` package is a runtime dependency, not a Python library with modules intended for direct `import`. Attempting to `import dpcpp-cpp-rt` will result in a `ModuleNotFoundError`.
Fix: Do not attempt to import `dpcpp-cpp-rt` directly. Instead, ensure it is installed, and then use Python libraries that depend on it (e.g., `dpctl`, `numba-dppy`).
breaking Incorrect or incomplete environment setup (e.g., `PATH`, `LD_LIBRARY_PATH` on Linux, `DYLD_LIBRARY_PATH` on macOS) can prevent dependent applications from finding the DPC++ runtime libraries, leading to linker errors or device discovery failures.
Fix: Always source the oneAPI `setvars.sh` (Linux/macOS) or `setvars.bat` (Windows) script from your oneAPI installation (`<install_dir>/oneapi/setvars.sh`) before running DPC++ or SYCL applications, including Python scripts that use libraries like `dpctl`.
gotcha Version mismatches between `dpcpp-cpp-rt` and other oneAPI components (like the DPC++ compiler, `dpctl`, `numba-dppy`) can lead to unexpected runtime errors or instability. It's recommended to maintain a consistent oneAPI installation.
Fix: Install all oneAPI components from the same major release and, ideally, the same minor update. When using `pip` or `conda`, ensure your environment matches the oneAPI installation version used for development.

Install

pip install dpcpp-cpp-rt Install via pip
conda install -c intel dpcpp-cpp-rt Install via Conda (Intel channel)

Imports

No direct Python imports
```
This package provides runtime components for C++/SYCL, not Python modules for direct import.
```
Users often mistake this for a Python library that can be imported directly. It's a foundational runtime for other Python packages (e.g., dpctl) that expose SYCL capabilities.

Quickstart

The `dpcpp-cpp-rt` package provides the underlying runtime for SYCL-enabled applications. It does not have direct Python imports. Instead, Python libraries like `dpctl` (Data Parallel Control Library) leverage its presence. This example shows how `dpctl` would interact with the SYCL runtime that `dpcpp-cpp-rt` enables. Ensure your oneAPI environment is sourced before running Python code that uses SYCL.

import os

# This package is a runtime, not directly imported. 
# Its presence allows other Python packages (like dpctl) to function.
# Example using dpctl, which relies on dpcpp-cpp-rt:

try:
    import dpctl
    print("dpctl successfully imported.")
    
    # Try to find a SYCL device
    try:
        device = dpctl.select_default_device()
        print(f"Selected SYCL device: {device.name}")
    except Exception as e:
        print(f"Could not select SYCL device. Ensure SYCL_DEVICE_FILTER is set if needed. Error: {e}")
        print("Make sure oneAPI environment is sourced and DPC++ runtime is configured correctly.")

except ImportError:
    print("dpctl is not installed. This quickstart demonstrates usage of a library that depends on dpcpp-cpp-rt.")
    print("Install with: pip install dpctl")

# You would typically set environment variables before running Python code
# For example, to filter devices:
# os.environ['SYCL_DEVICE_FILTER'] = 'opencl:gpu,cpu'

view raw JSON →