Use the setvars and oneapi-vars Scripts with Linux*
The Unified Directory Layout was implemented in 2024.0. If you have multiple toolkit versions installed, the Unified layout adds the ability to ensure your development environment contains the component versions that were released as part of that specific toolkit version.
With the new Unified Directory Layout, you will see components installed together in a collection of common folders (e.g., bin, lib, include, share, etc.). These common folders are located in a top-level folder that is named for the toolkit version number. For example:
/opt/intel/oneapi/2024.0/
|-- bin
|-- lib
|-- include
...etc...
The directory layout that was used prior to 2024.0 is still supported on new and existing installations. This prior layout is called the Component Directory Layout. Now you have the option to use the Component Directory Layout or the Unified Directory Layout.
Differences in Component Directory Layout and Unified Directory Layout
Most of the component tool folders contain an environment script named
env/vars.sh
that configures the environment variables needed by that
component to support oneAPI development work. For example, in a default
installation, the Intel® Integrated Performance Primitives (Intel® IPP)
env/vars script on Linux is located at:
/opt/intel/oneapi/ipp/latest/env/vars.sh
in the Component Directory
Layout.
This pattern is shared by all oneAPI
components that include an env\vars
setup script.
In the Component Directory Layout the component env/vars
scripts can be called
directly or collectively. To call them collectively, a script named setvars.sh
is provided in the oneAPI installation folder. For example, in a default
Component Directory Layout installation on a Linux machine: /opt/intel/oneapi/setvars.sh
.
The Unified Directory Layout does not use the env/vars.sh
scripts to initialize
the development environment. Instead, each component is “corralled” into shared
folders that are common to the components. In other words, each component
contributes its header files to a single common include
folder, its library
files to a single common lib
folder, and so on.
Advantages of the Unified Directory Layout
The Unified Directory Layout
makes it much easier to switch between different toolkit versions without
having to build and maintain setvars
config files or play games with
installation of multiple oneAPI toolkits. It is also useful for limiting the
length of environment variables, especially the PATH variable, on Windows
development systems, a troublesome issue for some Windows developers.
The
Unified Directory Layout environment variables can only be setup collectively.
To initialize the development environment variables a script named
oneapi-vars.sh
. In a default Unified Directory Layout installation, on a Linux
machine, that script is located here:
/opt/intel/oneapi/<toolkit-version>/oneapi-vars.sh
. The <toolkit-version>
corresponds to the version number of the oneAPI toolkit that you installed.
Example:
/opt/intel/oneapi/2024.0/oneapi-vars.sh
/opt/intel/oneapi/2024.1/oneapi-vars.sh
Sourcing the setvars.sh
script without any arguments causes it to locate
and source all <component>/latest/env/vars.sh
scripts in the Component
Directory Layout installation. Changes made to the environment by these scripts
can be seen by running the env
command after running the environment setup
scripts.
Sourcing the oneapi-vars.sh
script without any arguments causes it to configure
the environment for the specific toolkit version in which that oneapi-vars.sh
script is located. It will also source any optional
/opt/intel/oneapi/<toolkit-version>/etc/<component>/vars.sh
scripts that are
part of that Unified Directory installation. Changes made to the environment by
these scripts can be seen by running the env command after sourcing the
oneapi-vars.sh
script.
Note
Changes to your environment made by sourcing the setvars.sh
/
oneapi-vars.sh
script (or the individual env/vars.sh
scripts) are not permanent.
Those changes only apply to the terminal session in which the
setvars.sh
/ oneapi-vars.sh
environment script was sourced.
To learn more about the differences in setvars and oneapi-vars, see Environment Initialization in the Unified Directory Layout
Command Line Arguments
The setvars.sh
/ oneapi-vars
script supports several command-line
arguments, which are displayed using the --help
option. For example:
Component Directory Layout
For system-wide installations:
. /opt/intel/oneapi/setvars.sh --help
For private installations:
. ~/intel/oneapi/setvars.sh --help
Unified Directory Layout
For system-wide installations:
. /opt/intel/oneapi/<version>/oneapi-vars.sh --help
For private installations:
. ~/intel/oneapi/<version>/oneapi-vars.sh --help
The --config=file
argument and the ability to include arguments that will
be passed to the vars.sh
scripts that are called by the setvars.sh
/
oneapi-vars.sh
script can be used to customize the environment setup. The
--config=file
option is only supported by the setvars.sh
script.
The --config=file
argument provides the ability to limit environment
initialization to a specific set of oneAPI components. It also provides
a way to initialize the environment for specific component versions. For
example, to limit environment setup to just the Intel® IPP library and
the Intel® oneAPI Math Kernel Library (Intel® oneMKL), pass a config
file that tells the setvars.sh
/ oneapi-vars
script to only call the vars.sh
environment scripts for those two oneAPI components. More details and
examples are provided in Use a Config file for setvars.sh on Linux.
Any extra arguments passed on the setvars.sh
/ oneapi-vars
command line that are
not described in the setvars.sh
/ oneapi-vars
help message will be passed to every
called vars.sh
script. That is, if the setvars.sh
/ oneapi-vars
script does
not recognize an argument, it assumes the argument is meant for use by
one or more component scripts and passes those extra arguments to every
component vars.sh
script that it calls. The most common extra
arguments are ia32
and intel64
, which are used by the Intel
compilers and the IPP, MKL, and TBB libraries to specify the application
target architecture.
Inspect the individual vars.sh
scripts to determine which, if any,
command line arguments they accept.
How to Run
Component Directory Layout
source <install-dir>/setvars.sh
Unified Directory Layout
source <install-dir>/<toolkit-version>/oneapi-vars.sh
Note
If you are using a non-POSIX shell, such as csh, use the following command:
Component Directory Layout
$ bash -c 'source <install-dir>/setvars.sh ; exec csh'
Unified Directory Layout
$ bash -c 'source <install-dir>/<toolkit-version>/oneapi-vars.sh ; exec csh'
If environment variables are set correctly, you will see a confirmation message similar to this:

If you receive an error message, troubleshoot using the Diagnostics Utility for Intel® oneAPI Toolkits, which provides system checks to find missing dependencies and permissions errors. Learn more.
Alternatively, use the modulefiles scripts to set up your development environment. The modulefiles scripts work with all Linux shells.
If you wish to fine tune the list of components and the version of those components, use a setvars config file to set up your development environment.
Multiple Runs
Because many of the individual env/vars.sh
scripts make significant
changes to PATH, CPATH, and other environment variables, the top-level
setvars.sh
/ oneapi-vars
script will not allow multiple invocations of itself in
the same session. This is done to ensure that your environment variables
do not become too long due to redundant path references, especially the
$PATH
environment variable.
This behavior can be overridden by passing setvars.sh
/ oneapi-vars
the
--force
flag. In this example, the user tries to run setvars.sh
/
oneapi-vars
twice. The second instance is stopped because setvars.sh
/
oneapi-vars
has already been run.
Component Directory Layout
> source <install-dir>/setvars.sh
.. code-block:: initializing oneAPI environment ...
(SNIP: lot of output)
.. code-block:: oneAPI environment initialized ::
> source <install-dir>/setvars.sh
.. code-block:: WARNING: setvars.sh has already been run. Skipping re-execution.
To force a re-execution of setvars.sh, use the '--force' option.
Using '--force' can result in excessive use of your environment variables
In the third instance, the user runs setvars.sh --force
and the
initialization is successful.
> source <install-dir>/setvars.sh --force
.. code-block:: initializing oneAPI environment ...
(SNIP: lot of output)
.. code-block:: oneAPI environment initialized ::
Unified Directory Layout
> source <install-dir>/<version>/oneapi-vars.sh
.. code-block:: initializing oneAPI environment ...
(SNIP: lot of output)
.. code-block:: oneAPI environment initialized ::
> source <install-dir>/<toolkit-version>/oneapi-vars.sh
.. code-block:: WARNING: setvars.sh has already been run. Skipping re-execution.
To force a re-execution of setvars.sh, use the '--force' option.
Using '--force' can result in excessive use of your environment variables
In the third instance, the user runs oneapi-vars.sh --force
and the initialization is successful.
> source <install-dir>/ ``oneapi-vars.sh`` --force
.. code-block:: initializing oneAPI environment ...
(SNIP: lot of output)
.. code-block:: oneAPI environment initialized ::
Environment Initialization in the Unified Directory Layout
The Unified Directory Layout was implemented with the 2024.0 release. If you are unfamiliar with the change, please see Use the setvars and oneapi-vars Scripts with Linux at the top of this page.
Initializing the environment for a “unified” directory is done by the
oneapi-vars.sh
script, not the setvars.sh
script. The usage of oneapi-vars
is similar to setvars, but there are some subtle differences.
The key difference between the setvars script and the oneapi-vars script is that the setvars script does not define any environment variables (other than ONEAPI_ROOT) and the oneapi-vars script defines the common environment variables.
In the Component Directory Layout, each component is responsible
for defining the environment variables needed in order to function. For
example, in the Component Directory Layout each component adds its linkable library
folders to LD_LIBRARY_PATH
and include headers to CPATH
, etc. The
components do this via their individual vars scripts, which are always located
in:
$ONEAPI_ROOT/<component-name>/<component-version>/env/vars.sh
The Unified Directory Layout combines the externally facing include, lib, and bin folders into a set of common folders. In this scenario, the top-level oneapi-vars script defines the environment variables that are needed to locate these common folders. For example, setvars will define LD_LIBRARY_PATH as $ONEAPI_ROOT/lib and CPATH as $ONEAPI_ROOT/include and so on.
Modulefiles continue to be supported in the 2024.0 release, and can be used as an alternative to using setvars.sh to initialize an environment setup. Modulefiles scripts are only supported on Linux.
ONEAPI_ROOT Environment Variable
The ONEAPI_ROOT
variable is set by the top-level setvars.sh
and
oneapi-vars.sh
script when either script is sourced. If there is already a
ONEAPI_ROOT
environment variable defined, setvars.sh
overwrites it in
the terminal session in which you sourced the setvars.sh
or
oneapi-vars.sh
script. This variable is primarily used by the
oneapi-cli
sample browser and the Eclipse* and Visual Studio Code* sample
browsers to help them locate oneAPI tools and components, especially for
locating the setvars.sh
script if the SETVARS_CONFIG
feature has been
enabled. For more information about the SETVARS_CONFIG
feature, see
Automate the setvars.sh Script with Eclipse*.
With the 2024.0 release, the installer does not add the
ONEAPI_ROOT
variable to the environment. To add it to your default
environment, define the variable in your local shell initialization
file(s) or in the system’s /etc/environment
file.