Installation Guide for Intel® oneAPI Toolkits

Version History

    Date

Version

Change Summary  

November 2019

2021.1-beta

Initial Beta release

1. Introduction

This guide covers installation of Intel® oneAPI Toolkits on Windows* or Linux* systems. The following installation options are available:

Supported Distributions
Installation OptionLinuxWindows
Customizable Online InstallerYesYes
Full package local installerYesYes
ContainerYesNo
APTYesNo
YUMYesNo
ZypperYesNo

 

NOTE: Be sure to read the Toolkit Release notes and System requirements to learn more about compatibility details.

2. Online Installer

  1. Go to the Intel® oneAPI page.
  2. Locate the Intel® oneAPI Base Toolkit or Domain-Specific Toolkit for Specialized Workloads.
    • NOTE: Some Domain-Specific Toolkits require Intel oneAPI Base Toolkit to be installed first for full functionality.

NOTE: To use third-party IDE - install Eclipse* on your Linux* host system or Microsoft Visual Studio* on your Windows system before installing the Intel® oneAPI Toolkits. This allows you to integrate the plug-ins as part of the base toolkit installation.


 Get the Base Kit

  1. Click the Get the Base Kit button or click the Domain-Specific Toolkit button for standalone capable kits.
  2. Select your OS from the drop-down list.
    Choose your OS
  3. For a web-based download, click the Configure Install button  
    • For Linux*, you will also have a container and package manager options – refer to these Linux* install instructions.
  4. Click on the Download button for the Online Installer or click the Customize your download link to remove components from the Intel oneAPI Base Toolkit. (Alternatively, you can choose the Local Installer.)


Click Configure Install

NOTE: If you are targeting an FPGA and would like to install additional components for this kind of development, click on the Intel® FPGA Add-on for oneAPI Base Toolkit in the gray box. This provides an add-on, separate download. See the FPGA install instructions for detailed steps.

2.1 Configure the Online Installer (optional)

By default, all components in the Toolkit are included. The customization option allows you to select components.  It does not provide the option to add components from other Toolkits.

  • Click on the Next Step button when your customization is complete. 
    Click Next Step

2.2 Run the Online Installer

  1. Click the Download button. The initial download is for the installer application files only. It does not include the tools you selected. The installer will acquire all the tools you selected during the installation process.
  2. Extract the contents of the installer .zip file. The contents include:
    • An archive file (for Linux)
    • An .exe installer (for Windows)
    • A .json file, used for configuration

For Linux users:

   Step 1: Unpack the ZIP archive file you downloaded using 

        unzip <archive-name>

   Step 2: Extract the installer from the tar.gz file using

        tar -xvf <tar-file-name>

                The ZIP archive contains a config file and a tar.gz file.

   Step 3: Locate the install.sh file in the extracted installer folder.

   Step 4: Use sudo ./install.sh to launch the GUI installer as root.

        sudo ./install.sh


​​​​​Optionally, use  ./install.sh to launch the installer as a normal user.

   Step 5: Follow the installer instruction screens.

   NOTE: root permission is required in order to install the drivers for CPU, GPU, and FPGA.

  • Check if these two files intel-cpu.icd and intel-neo.icd exist in directory "/etc/OpenCL/vendors" after the installation. Otherwise, create these files:
            echo 'libigdrcl.so' > intel-neo.icd
            echo 'libintelocl.so' > intel-cpu.icd

        NOTE: Root permission or sudo is required to create these files.

For Windows users:

  Step 1:  Unpack the ZIP archive file you downloaded, using Windows Explorer.
                Right-click the ZIP file and select "Extract All..." from the menu.
                The ZIP archive contains a config file and an EXE file.

   Step 2: Double-click the EXE file to launch the GUI installer

     w_[Toolkit Name]Kit_[version].exe

   Step 3: Follow the installer instruction screens

  • Once the installation is complete, verify that your toolkit has been installed to the correct installation directory, as follows:
Default Installation Directory
LinuxWindows
/opt/intel/inteloneapiC:\Program Files (x86)\inteloneapi

 

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

NOTE: If you have applications with long-running GPU compute workloads in native environments, you must disable the hangcheck timeout period to avoid terminating workloads.

3. Local Installer (Full package only)

This section contains steps to install your toolkit using the Local Installer. When selecting Local Installer only full package is available for download.

On selected toolkit download page click Get It Now button. Select your OS and then under Local Installer on the right, click the Download button. Save the installation file to your computer.

Download Local Installer

For Linux users:

For Windows users:

3.1 Install with the GUI on Linux or Windows

For Linux users:

   Step 1: Unpack the archive and launch the GUI installer by running

        install.sh

   Step 2: Follow the instructions in the installer.

    NOTE: root permission is required in order to install the drivers for CPU, GPU, and FPGA.

  • Check if these two files intel-cpu.icd and intel-neo.icd exist in directory "/etc/OpenCL/vendors" after the installation. Otherwise, create these files:
       echo 'libigdrcl.so' > intel-neo.icd
       echo 'libintelocl.so' > intel-cpu.icd

        NOTE: Root permission or sudo is required to create these files.


For Windows users:

   Step 1: Double-click on the installer:

       w_[Toolkit Name]Kit_[version].exe

   Step 2: Follow the installer instruction screens

  • Once the installation is complete, verify that your toolkit has been installed to the correct directory, as follows:
    Default Installation Directory
    LinuxWindows
    /opt/intel/inteloneapiC:\Program Files (x86)\inteloneapi

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

NOTE: If you have applications with long-running GPU compute workloads in native environments, you must disable the hangcheck timeout period to avoid terminating workloads.

3.2 Install with the Command Line on Linux

Currently, the interactive command-line installation is not supported. However, the command line installation can still be achieved by a silent install. Follow the detailed instructions below:

Step 1: Extract the contents of the archive file you downloaded using the following command:

  tar –xvf [archive_filename].tar.gz

Step 2: Create a silent configuration file (silent.cfg) with following content:

 # accept EULA, valid values are: {accept, decline}
 ACCEPT_EULA=accept

Step 3: Save the configuration file.

Step 4: Launch the installation with the following command:

    sudo ./install.sh --silent ./silent.cfg

Step 5: The installation will start and may take some time to finish.

Step 6: Once the installation is complete, verify that your toolkit has been installed to the correct directory:

/opt/intel/inteloneapi

  • Check if these two files intel-cpu.icd and intel-neo.icd exist in directory "/etc/OpenCL/vendors" after the installation. Otherwise, create these files:
       echo 'libigdrcl.so' > intel-neo.icd 
       echo 'libintelocl.so' > intel-cpu.icd

     NOTE: Root permission or sudo is required to create these files.

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

NOTE: If you have applications with long-running GPU compute workloads in native environments, you must disable the hangcheck timeout period to avoid terminating workloads.

3.3 Install Selected oneAPI Toolkit Components from the Command Line on Linux

You can specify which components to include when installing your toolkit from the command line. Follow the steps below.

  1. Extract the contents of the archive file you downloaded using the following command:
      tar -zxvf [archive_filename].tar.gz
  2. First, you’ll need to obtain a list of which components are available in the toolkit package. Use the command below:
     ./install.sh --list_components
  1. You’ll see output like the following:
      intel-dpc++-compiler-1.0-128__noarch - Intel(R) DPC++ Compiler, version: 1.0
      intel-oneapi-mkl-1.0-056__noarch - Intel(R) oneAPI Math Kernel Library, version: 1.0
  1. Create a silent configuration file, silent.cfg. The contents of the file should be similar to the following example. Be sure to add the unique component identifiers to the COMPONENTS section of silent.cfg, using a semicolon (;) to separate the different components you want to install:
      # accept EULA, valid values are: {accept, decline}
      ACCEPT_EULA=accept
      # List of components to install, valid values are: {ALL, DEFAULTS, anythingpat}
      COMPONENTS=intel-dpc++-compiler-1.0-128__noarch;intel-oneapi-mkl-1.0-056__noarch
    
  2. Save the configuration file.
  3. Run the installation with the command:
      sudo ./install.sh --silent ./silent.cfg

    This will install the components to the default installation directory.

  4. Once the installation is complete, verify that your toolkit has been installed to the correct directory, as follows:
    Default Installation Directory
    LinuxWindows
    /opt/intel/inteloneapiC:\Program Files (x86)\inteloneapi
  5. For Linux users: Check if these two files intel-cpu.icd and intel-neo.icd exist in directory "/etc/OpenCL/vendors" after the installation. Otherwise, create these files:
      echo 'libigdrcl.so' > intel-neo.icd
      echo 'libintelocl.so' > intel-cpu.icd

        NOTE: Root permission or sudo is required to create these files.

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

NOTE: If you have applications with long-running GPU compute workloads in native environments, you must disable the hangcheck timeout period to avoid terminating workloads.

3.4 Code Samples

We have code samples available for download on github* to help you get started. You can clone them to your local machine directly from the following repositories:

4. Other installation methods for Linux*

Install via Linux* Package Managers

Following the instructions below to install from Linux repos:

  1. Install from yum (Internet connection required)
  2. Install from APT (Internet connection required)
  3. Install from Zypper (Internet connection required)

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

NOTE: If you have applications with long-running GPU compute workloads in native environments, you must disable the hangcheck timeout period to avoid terminating workloads.

4.1 Install a Docker Container

NOTE: Be sure to read the Toolkit release notes and system requirements to learn more about compatibility details.

5. Set Up a Standalone System with the Intel® Programmable Acceleration Card (PAC) with Intel® Arria® 10 GX FPGA (Linux only)

We recommend using the Intel® DevCloud, which is already set up with an Intel® PAC with Intel® Arria® 10 GX FPGA and the necessary software stack. However, for flexibility, you may want to have your own setup. You can set up separate runtime and development systems. With this option, you install the FPGA hardware on the runtime system and run the design only. On the development system, you compile and generate the FPGA bitstream.

You can also use a single system as both a runtime and development system. To do so, perform the following high-level steps on the same system, as described below: 

  1. (Hardware-run machine specific) Install the Intel® PAC with Intel® Arria® 10 GX FPGA software stack
  2. Install the Intel® FPGA add-on package on the development system

5.1 Install the Intel® PAC with Intel® Arria® 10 GX FPGA Software Stack (Linux only)

This step applies only to the machine with a physical card or the runtime system. If you need an Intel® PAC with Intel® Arria® 10 GX FPGA, contact the Intel sales representatives. Perform the following steps:

  1. Run the following command to install the Intel® PAC with Intel® Arria® 10 GX FPGA software stack only on a system with a physical card:
    aocl install
  2. Accept the installation prompts to proceed with installing the Intel® PAC with Intel® Arria® 10 GX FPGA software stack. 

NOTE: You must ensure that the FPGA development board is plugged into the system. Verify it using the aocl diagnose command. This diagnostic should be done only once per installation.

TIP: The installer will attempt to install the prerequisite packages. If it fails to install a package (for example, due to version conflict or repository incomplete), you can either manually install that package or run the sudo apt -fix-broken install command.

5.2 Installing the Intel® FPGA Add-on for oneAPI Base Toolkit Package (Linux only)

The Intel® FPGA Add-on for oneAPI Base Toolkit, also known as the Intel® Quartus® Prime Pro Edition, provides necessary tools to compile an FPGA image for deployment onto your chosen FPGA platform. It is intended for use in conjunction with the oneAPI Data Parallel C++ Compiler, and cannot be used as a standalone component. Use the add-on to compile your FPGA design flow for deployment to real hardware.

The Intel® FPGA Add-on for oneAPI Base Toolkit package includes the following:

  • Hybrid Placer & Global Router
  • Timing Analyzer
  • Physical Synthesis
  • Incremental Fitter Optimization
  • Interface Planner
  • Synthesis Engine
  • Platform Designer
  • Partial Reconfiguration
  • Block-Based (Hierarchical) Design

NOTE: Use the Intel® FPGA Add-on for oneAPI Base Toolkit only with the Intel® Programmable Acceleration Card (PAC) with Intel® Arria® 10 GX FPGA. The add-on is not required for the emulation or report generation stages of the FPGA development flow. You can complete those stages with just the oneAPI Data Parallel C++ Compiler.

  1. Download the Intel® FPGA add-on for oneAPI Base Toolkit package, as described in the Online Installer section
  2. Extract the package using the following command:
      tar -xzf l_intel_fpga_dpcpp_2021.1-beta01.tar.gz
  3. Run the setup.sh script in the add-on package directory, as follows: 
       cd l_intel_fpga_dpcpp_2021.1-beta01
      sudo ./setup.sh
  4. Perform the following for the installer prompts:
    1. Accept the license agreement.
    2. Enter the add-on package installation path. Alternatively, you can use the default path: /opt/intel/inteloneapi/
    3. Choose to install prerequisite packages.
  5. Close the existing shell.
  6. Open a new shell.
  7. Diagnose the FPGA installation and environment by running the fpga_sys_check.sh script:
      $INTELFPGAOCLSDKROOT/fpga_sys_check.sh
    

NOTE: If this diagnostic passes, the script does not print anything. If it fails, the script prints why it failed.

5.3 Installing the Intel® FPGA Add-on for oneAPI Base Toolkit Package (Linux only) using silent install option

  1. Download the Intel® FPGA add-on for oneAPI Base Toolkit package, as described in the Online Installer section
  2. Extract the package using the following command:
         tar -xzf l_intel_fpga_dpcpp_2021.1-beta01.tar.gz
  3. Run the CLI installer as follows:
     sudo ./setup.sh
  1. Close the existing shell.
  2. Open a new shell.
  3. Diagnose the FPGA installation and environment by running the fpga_sys_check.sh script:
     $INTELFPGAOCLSDKROOT/fpga_sys_check.sh
    

NOTE: If this diagnostic passes, the script does not print anything. If it fails, the script prints why it failed.

6. Uninstall oneAPI Toolkits and components

6.1 Uninstalling Intel PAC card (Linux only)

If you installed the Intel PAC card, run the following command to uninstall it:

aocl uninstall

6.2 Uninstall  oneAPI Toolkits

     For Linux:  use the following commands to uninstall oneAPI Toolkits:
cd /opt/intel/inteloneapi 
sudo ./install.sh

        Using Linux silent CLI 

  1. cd to installation folder and create empty silent_uninstall.cfg configuration file
  2. Add “PSET_MODE=uninstall” and save the configuration file
  3. Run the following command
sudo ./install.sh --silent ./silent_uninstall.cfg

 

     For Windows:  use the Add/Remove Programs option from Control Panel to uninstall oneAPI Toolkits.

   Using Windows silent CLI

  1. Go to installation folder, create empty silent_uninstall.cfg configuration file
  2. Add “PSET_MODE=uninstall”
  3. Run the following command
install.exe --silent silent_uninstall.cfg

   Using Linux package manager

  • APT
sudo apt autoremove <package_name>
  • YUM
sudo yum autoremove <package_name> 

6.3 Uninstall PyTorch and TensorFlow (part of Intel® AI Analytics Toolkit)

  • To uninstall PyTorch:
  1. Deactivate the pytorch environment, if activated.
  2. Uninstall using the following commands: 
     conda remove -p $<install_dir>/pytorch/1.1.0/ --all
     rm -rf $<install_dir>/pytorch
  • To uninstall TensorFlow:
  1. Deactivate the tensorflow environment, if activated.
  2. Uninstall using the following commands:         
     conda remove -p $<install_dir>/tensorflow/1.14.0/ --all
     rm -rf $<install_dir>/tensorflow

7. Disable Hangcheck

This section applies only to applications with long-running GPU compute workloads in native environments. Not recommended for virtualizations or other standard usages of GPU, such as gaming.

A workload that takes more than four seconds for GPU hardware to execute is a long running workload. By default, individual threads that qualify as long-running workloads are considered hung and are terminated. Disabling the hangcheck timeout period avoids this problem.

NOTE: If the system is rebooted, hangcheck is automatically enabled. You must disable hangcheck again after every reboot or follow the directions below to disable hangcheck persistently (across multiple reboots). Please re-run this GPU Hangcheck disable with reboot fix if you update (or auto-update) the kernel.

To disable hangcheck until the next reboot:

   sudo sh -c "echo N> /sys/module/i915/parameters/enable_hangcheck"

To disable hangcheck across multiple reboots:

  1. Open a terminal and run this command:
    append i915.enable_hangcheck=0 to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub
    run sudo update-grub
  2. Reboot the system. Hangcheck will remain disabled.

8. Install GPU Drivers  

8.1 For Linux: RHEL* v8.x hosts only

  • Install the following Agama packages: 
    • OpenCL (Neo) 19.43.14583
    • Media 19.3.1
    • Hardware validated with this release: Intel's 9th generation graphics processing unit (SkyLake) and newer
  • To access the packages, add the repository to your system and then install the packages using dnf (Note: root permission is required)
cat << EOF | sudo tee /etc/yum.repos.d/intel-graphics.repo
[intel-graphics]
name=Intel Graphics Drivers Repository
baseurl=https://repositories.intel.com/graphics/rhel/8.0/
enabled=1
gpgcheck=0
EOF 
  • You can then install the packages:
     sudo dnf install intel-opencl  
  • The user needs to be on the "video" group to have an access to hardware. Use the command below to add:
     usermod -a -G video $LOGNAME

8.2 For Windows

For more complete information about compiler optimizations, see our Optimization Notice.