Installation Guide

System Requirements

Hardware Requirement

Verified Hardware Platforms:

  • Intel® Data Center GPU Flex Series 170

  • Intel® Data Center GPU Max Series

  • Intel® Arc™ A-Series GPUs (Experimental support)

Software Requirements

  • OS & Intel GPU Drivers

Hardware OS Driver
Intel® Data Center GPU Flex Series Ubuntu 22.04 (Validated), Red Hat 8.6 Stable 602
Intel® Data Center GPU Max Series Ubuntu 22.04, Red Hat 8.6, Sles 15sp3/sp4 (Validated) Stable 602
Intel® Arc™ A-Series Graphics Ubuntu 22.04 Stable 602
Intel® Arc™ A-Series Graphics Windows 11 or Windows 10 21H2 (via WSL2) for Windows 11 or Windows 10 21H2
CPU (3rd and 4th Gen of Intel® Xeon® Scalable Processors) Linux* distributions with glibc>=2.17. Validated on RHEL 8. N/A

Preparations

Install Intel GPU Driver

OS Instructions for installing Intel GPU Driver
Linux* Refer to the Installation Guides for the driver installation on individual Linux* distributions. When installing the verified driver mentioned in the table above, use the specific version of each component packages mentioned in the installation guide page, such as sudo apt-get install intel-opencl-icd=<version>
Windows 11 or Windows 10 21H2 (via WSL2) Please download drivers for Intel® Arc™ A-Series from the web page mentioned in the table above. Please note that you would have to follow the rest of the steps in WSL2, but the drivers should be installed on Windows. Besides that, please follow Steps 4 & 5 of the Installation Guides on WSL2 Ubuntu 22.04.

Install oneAPI Base Toolkit

Please refer to Install oneAPI Base Toolkit Packages.

Need to install components of Intel® oneAPI Base Toolkit:

  • Intel® oneAPI DPC++ Compiler (DPCPPROOT as its installation path)

  • Intel® oneAPI Math Kernel Library (oneMKL) (MKLROOT as its installation path)

Default installation location {ONEAPI_ROOT} is /opt/intel/oneapi for root account, ${HOME}/intel/oneapi for other accounts. Generally, DPCPPROOT is {ONEAPI_ROOT}/compiler/latest, MKLROOT is {ONEAPI_ROOT}/mkl/latest.

A DPC++ compiler patch is required to use with oneAPI Basekit 2023.1.0. Use the command below to download the patch package.

wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/89283df8-c667-47b0-b7e1-c4573e37bd3e/2023.1-linux-hotfix.zip

You can either follow instructions in the README.txt of the patch package, or use the commands below to install the patch.

unzip 2023.1-linux-hotfix.zip
cd 2023.1-linux-hotfix
source {ONEAPI_ROOT}/setvars.sh
bash installpatch.sh

If later on you are not using the environment of the patch installation, you need to activate ONLY DPC++ compiler and oneMKL environment later on when no matter compiling or using Intel® Extension for PyTorch* on Intel GPUs.

source {DPCPPROOT}/env/vars.sh
source {MKLROOT}/env/vars.sh

PyTorch-Intel® Extension for PyTorch* Version Mapping

Intel® Extension for PyTorch* has to work with a corresponding version of PyTorch. Here are the PyTorch versions that we support and the mapping relationship:

PyTorch Version Extension Version
v1.13.* (patches needed) v1.13.*
v1.10.* (patches needed) v1.10.*

Install via wheel files

Prebuilt wheel files availability matrix for Python versions:

Extension Version Python 3.6 Python 3.7 Python 3.8 Python 3.9 Python 3.10
1.13.120+xpu ✔️ ✔️ ✔️ ✔️
1.13.10+xpu ✔️ ✔️ ✔️ ✔️
1.10.200+gpu ✔️ ✔️ ✔️ ✔️

Prebuilt wheel files for generic Python* and Intel® Distribution for Python* are released in separate repositories.

# General Python*
python -m pip install torch==1.13.0a0+git6c9b55e torchvision==0.14.1a0 intel_extension_for_pytorch==1.13.120+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/

# Intel® Distribution for Python*
python -m pip install torch==1.13.0a0+git6c9b55e torchvision==0.14.1a0 intel_extension_for_pytorch==1.13.120+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu-idp/us/

Note: Wheel files for Intel® Distribution for Python* only supports Python 3.9. The support starts from 1.13.10+xpu.

Note: Installation of TorchVision is optional.

Note: You may need to have gomp package in your system (apt install libgomp1 or yum/dnf install libgomp).

Note: Since DPC++ compiler doesn’t support old C++ ABI (_GLIBCXX_USE_CXX11_ABI=0), ecosystem packages, including PyTorch and TorchVision, need to be compiled with the new C++ ABI (_GLIBCXX_USE_CXX11_ABI=1).

Note: If you need TorchAudio, please follow the instructions to compile it from source. According to torchaudio-pytorch dependency table, torchaudio 0.13.0 is recommended.

Install via compiling from source

Configure the AOT (Optional)

Please refer to AOT documentation for how to configure USE_AOT_DEVLIST. Without configuring AOT, the start-up time for processes using Intel® Extension for PyTorch* will be long, so this step is important.

Compile the bundle (PyTorch*, torchvision, torchaudio, Intel® Extension for PyTorch*) with script

To ensure a smooth compilation of the bundle, including PyTorch*, torchvision, torchaudio, Intel® Extension for PyTorch*, a script is provided in the Github repo. If you would like to compile the binaries from source, it is highly recommended to utilize this script.

$ wget https://github.com/intel/intel-extension-for-pytorch/raw/release/xpu/1.13.120/scripts/compile_bundle.sh
$ bash compile_bundle.sh <DPCPPROOT> <MKLROOT> [AOT]
  DPCPPROOT and MKLROOT are mandatory, should be absolute or relative path to the root directory of DPC++ compiler and oneMKL respectively.
  AOT is optional, should be the text string for environment variable USE_AOT_DEVLIST.

Note: Recommend to use the compile_bundle.sh script in a clean docker container.

Note: Use the compile_bundle.sh script under a conda environment.

Note: Depends on what applications are available on your OS, you probably need to install some Linux commands, like patch, git, etc. Installation of these Linux commands are not included in this script.

Note: The compile_bundle.sh script downloads source code of PyTorch*, torchvision, torchaudio, Intel® Extension for PyTorch* into individual folders in its directory. You can consider to create a specific folder to use this script. Wheel files will be generated under dist folder of each source code directory. Besides, compilation progress is dumped into a log file build.log in each source code directory. The log file is helpful to identify errors occurred during compilation. Should any failure happened, after addressing the issue, you can simply run the compile_bundle.sh script again with the same command.

$ mkdir ipex_bundle
$ cd ipex_bundle
$ wget .../compile_bundle.sh
$ bash compile_bundle.sh ...
$ ls
audio  compile_bundle.sh  intel_extension_for_pytorch  torch  vision
$ tree -L 3 .
.
├── audio
│   ├── dist
│   │   └── torchaudio-....whl
│   ├ build.log
│   └ ...
├── compile_bundle.sh
├── intel_extension_for_pytorch
│   ├── dist
│   │   └── intel_extension_for_pytorch-....whl
│   ├ build.log
│   └ ...
├── torch
│   ├── dist
│   │   └── torch-....whl
│   ├ build.log
│   └ ...
└── vision
    ├── dist
    │   └── torchvision-....whl
    ├ build.log
    └ ...

Solutions to potential issues on WSL2

Issue Explanation
Building from source for Intel® Arc™ A-Series GPUs failed on WSL2 without any error thrown Your system probably does not have enough RAM, so Linux kernel's Out-of-memory killer got invoked. You can verify it by running dmesg on bash (WSL2 terminal). If the OOM killer had indeed killed the build process, then you can try increasing the swap-size of WSL2, and/or decreasing the number of parallel build jobs with the environment variable MAX_JOBS (by default, it's equal to the number of logical CPU cores. So, setting MAX_JOBS to 1 is a very conservative approach, which would slow things down a lot).
On WSL2, some workloads terminate with an error CL_DEVICE_NOT_FOUND after some time This is due to the TDR feature in Windows. You can try increasing TDRDelay in your Windows Registry to a large value, such as 20 (it is 2 seconds, by default), and reboot.