Use Environment Modulefiles with Linux*
Modulefiles can be used to setup your environment, allowing you to specify the precise versions of components you wish to use.
There are two methods for customizing your environment variables in Linux*:
Use modulefiles, as described on this page
Most of the component tool folders contain one or more modulefile
scripts that configure the environment variables needed by that
component to support development work. Modulefiles are an alternative to
using the setvars.sh
script to set up the development environment.
Because modulefiles do not support arguments, multiple modulefiles are
available for oneAPI tools and libraries that support multiple
configurations (such as a 32-bit configuration and a 64-bit
configuration).
Note
Moduleffiles can only be used with setvars.sh
in the Component
Directory Layout. The Unified Directory Layout utilizes
oneapi-vars.sh
, which does not support modulefiles. To learn
more about the layouts, see
:ref: Use the setvars and oneapi-vars Scripts with Linux <use-the-setvars-script-with-linux-or-macos>
Note
The modulefiles provided with the Intel oneAPI toolkits are compatible with the Tcl Environment Modules (Tmod) and Lua Environment Modules (Lmod). The following minimum versions are supported:
Tmod (version 4.0)
Tcl version 8.4
Lmod version 8.7.31
Test which version of Tmod is installed on your system using the following command:
module --version
Test which version of Tcl is installed on your system with the following commands:
$ tclsh
$ puts $tcl_version
8.6
$ exit
Each modulefile automatically verifies the Tcl version on your system when it runs, but it does not test the version of Tmod on your System.
If your modulefile version is not supported, a workaround may be possible. See Using Environment Modules with Intel Development Tools for more details.
As of the oneAPI 2024.0 release, the icc
modulefile has been removed
because the Intel® Classic Compiler has been discontinued. Please use the
Intel® oneAPI C/C++ Complier (icx
and icpx
) instead. The
ifort
compiler is still available, but you are encouraged to use the
equivalent Intel® oneAPI Fortran Compiler (ifx
).
The oneAPI modulefile scripts are located in a modulefiles directory
inside each component folder (similar to where the individual vars scripts
are located). For example, in a default installation for 2024.0 and later
oneAPI Toolkit releases, the compiler
modulefiles script(s) are in the
/opt/intel/compiler/<component-version>/etc/modulefiles/
directory. In
2023 or earlier oneAPI Toolkit releases, the compiler
modulefiles
script(s) are in the
/opt/intel/compiler/<component-version>/modulefiles/
directory.
Note
<component-version>
is the version number of a component (a
library or tool). You may have multiple components installed side-by-side on
your development system (e.g., compiler/2023.1
, compiler/2023.2
,
compiler/2024.0
, etc.). The Toolkit version, which is the version of a
collection of components, may be different than the component version that was
delivered with that Toolkit.
Due to how oneAPI component folders are organized on the disk, it can be
difficult to use the oneAPI modulefiles directly where they are
installed. Therefore, a special modulefiles-setup.sh
script is
provided in the oneAPI installation folder to make it easier to work
with the oneAPI modulefiles. In a default installation, that setup
script is located here: /opt/intel/oneapi/modulefiles-setup.sh
The modulefiles-setup.sh
script locates all modulefile scripts that
are part of your oneAPI installation and organizes them into a single
directory of versioned modulefiles scripts.
Each of these versioned modulefiles scripts is a symlink that points to
the modulefiles located by the modulefiles-setup.sh
script. Each
component folder includes (at minimum) a “latest” version modulefile
that will be selected, by default, when loading a modulefile without
specifying a version label. If you use the --ignore-latest
option
when running the modulefiles-setup.sh
script, the modulefile with
the highest version (per semver rules) will be loaded if no version
is specified by the module_load
command.
Alternatively, on a 2024.0 or later toolkit installation, within the
Unified Directory Layout, you will find a modulefiles folder that contains all the
component modulefiles associated with that toolkit version. For example, if you
install the 2024.0 Intel® oneAPI Base Toolkit into the default location, you
will find a preconfigured and ready to use collection of the 2024.0 Base
Toolkit modulefiles located in the /opt/intel/oneapi/2024.0/etc/modulefiles
folder, which you can add to your modulefile setup by adding that folder to
your MODULEPATH environment variable, or by running the module use
command
and specify that pre-configured modulefile folder. Installing the 2024.0 Intel
oneAPI HPC Toolkit will add additional modulefiles to that same location,
because the two toolkits are of the same version (in this case, 2024.0).
Within the pre-configured toolkit modulefiles folder there is a modulefile
named oneapi
that will load the 64-bit component modulefiles that belong to
that toolkit version. The oneapi
modulefile is a convenience modulefile, it
is not required to use the individual modulefiles. Also, the oneapi
modulefile will not work as expected within a folder created by the
modulefiles-setup.sh
script.
Note that the modulefiles delivered as part of the 2024.0 and later toolkits
will not automatically load prerequisite modulefiles. Instead, any modulefile
that has prerequisites will check if the appropriate modulefile is loaded and,
if not, will issue an error message. Pre-loading any prerequisite modulefiles
is left to the developer. The oneap
convenience modulefile will
automatically load all prerequisite modulefiles and load them first, before
loading any modulefile(s) that require(s) them.
Creating the modulefiles
Directory
Run the modulefiles-setup.sh
script.
By default, the modulefiles-setup.sh
script creates a folder
named modulefiles in the oneAPI toolkit installation folder. If your
oneAPI installation folder is not writeable, use the
--output-dir=<path-to-folder>
option to create the modulefiles
folder in a writeable location. Run modulefiles-setup.sh --help
for more information about this and other modulefiles-setup.sh script
options.
Running the modulefiles-setup.sh
script creates the modulefiles
output folder, which is organized like the following example (the
precise list of modulefiles depends on your installation). In this
example, there is one modulefile for configuring the Intel® Advisor
environment and two modulefiles for configuring the compiler environment
(the compiler modulefile configures the environment for all Intel
compilers). If you follow the latest symlinks, they point to the highest
version modulefile, per semver rules.

Update your MODULEFILESPATH to include to the modulefiles
output
folder that was created by the modulefiles-setup.sh
script or run
the module_use <folder_name>
command.
Installing the Tcl Modulefiles Environment onto Your System
The instructions below will help you quickly get started with the
Environment Modules utility on Ubuntu*. For full details regarding
installation and configuration of the module
utility, see
http://modules.sourceforge.net/.
Set your environment:
$ sudo apt update
$ sudo apt install tcl
$ sudo apt install environment-modules
Confirm that the local copy of
tclsh
is new enough (see the beginning of this page for a list of supported versions):
$ echo 'puts [info patchlevel] ; exit 0' | tclsh
8.6.8
Test the
module
installation by initializing themodule
alias.
$ source /usr/share/modules/init/sh
$ module
Note
Initialization of the Modulefiles environment in POSIX-compatible shells
should work with the source
command shown above. Shell-specific init
scripts are provided in the /usr/share/modules/init/
folder. See that
folder and the initialization section in man module
for more details.
Note that the precise location of the modules init folder varies with the
Linux distribution.
Source the
module
alias init script (.../modules/init/sh
) in a global or local startup script to ensure the module command is always available. At this point, the system should be ready to use the module command as shown in the following section.
Getting Started with the modulefiles-setup.sh
Script
The following example assumes you have:
installed
tclsh
on to the Linux development systeminstalled the Environment Modules utility (i.e.,
module
) onto the systemsourced the
.../modules/init/sh
(or equivalent) module init commandinstalled the oneAPI toolkits required for your oneAPI development
Navigate to the install directory, and load
tbb
:
$ cd <oneapi-root-folder> # cd to the oneapi_root install directory
$ ./modulefiles-setup.sh # run the modulefiles setup script
$ module use modulefiles # use the modulefiles folder created above
$ module avail # will show tbb/X.Y, etc.
$ module load tbb # loads tbb/X.Y module
$ module list # should list the tbb/X.Y module you just loaded
Use the
env
command to inspect the environment and look for the changes that were made by the modulefile you loaded.
$ env | grep -i "intel"
For example, if you loaded the tbb modulefile
, the
command will show you some of the env changes made by that
modulefile
.
Unload
tbb
:
$ module unload tbb # removes tbb/X.Y changes from the environment
$ module list # should no longer list the tbb/X.Y env var module
Note
A modulefile
is a script, but it does not need to have the ‘x’
(executable) permission set, because it is loaded and interpreted by
the “module” interpreter that is installed and maintained by the
end-user. Installation of the oneAPI toolkits do not include the
modulefile
interpreter. It must be installed separately.
Likewise, modulefiles
do not require that the ‘w’ permission be
set, but they must be readable (ideally, the ‘r’ permission is set
for all users).
Versioning
The oneAPI toolkit installer uses version folders to allow oneAPI tools
and libraries to exist in a side-by-side layout. These versioned
component folders are used by the modulefiles-setup.sh
script to
create the versioned modulefiles
. The script organizes the symbolic
links it creates in the modulefiles
output folder as
<modulefile-name>/version
, so that each respective modulefile
can be referenced by version when using the module command.
$ module avail
---------------- modulefiles -----------------
ipp/1.1 ipp/1.2 compiler/1.0 compiler32/1.0
Multiple modulefiles
A tool or library may provide multiple modulefiles
within its
modulefiles
folder. Each becomes a loadable module. They will be
assigned a version per the component folder from which they were
extracted.
How modulefiles
Are Set Up in oneAPI
Symbolic links are used by the modulefiles-setup.sh
script to gather
all the available modulefiles
into a single modulefiles
folder.
The actual modulefile
scripts are not moved or
modified. The ${ModulesCurrentModulefile}
variable
points to the symlink to each modulefile
, not to the actual
modulefile
located in the respective installation folders. To
determine the full path to the real modulefiles, each modulefile
includes a statement simliar to this:
[ file normalize ${scriptpath} ]
to get a direct reference to the original modulefile
in the product
install directory. This is done because the install location might
be customized and is therefore unknown at runtime.
The actual modulefile cannot be moved outside of the
installed location, otherwise it will not be able to locate the absolute
path to the library or application that it must configure.
For a better understanding, review the modulefiles
included with the
installation. Most include comments explaining how they resolve
symlink
references to a real file, as well as parsing the version
number (and version directory). They also include checks to insure that
the installed Tcl is an appropriate version level.
Use of the module load
Command by modulefiles
Note
This section only applies to modulefiles delivered in a 2023.2
toolkit or earlier. The modulefiles delivered as part of 2024.0 and later
toolkits will not automatically load prerequisite modulefiles. Instead, any
modulefile that has prerequisites will check if the appropriate modulefile is
loaded (using the modulefile prereq
command) and, if not, will issue an error
message. Pre-loading any prerequisite modulefiles is left to the developer. The
oneap
convenience modulefile automatically loads all prerequisite
modulefiles and loads them first.
Several of the modulefiles
use the module load
command to ensure
that any required dependent modules are also loaded. There is no attempt
to specify the version of those dependent modulefiles. This means you
have the option to load a specific version of a dependent module prior
to loading the module that requires that dependent module. If you do not
preload a dependent module, the latest available version is loaded.
This gives you the flexibility to control the environment. For example, you may have installed an updated version of a library that you want to test against a previous version of the compiler. Perhaps the updated library has a bug fix and you are not interested in changing the version of any other libraries in your build. If the dependent modulefiles were hard-coded to require a specific dependent version of this library, you could not perform such a test.
If a dependent module load
cannot be satisfied, the currently
loading module file will be terminated and no changes will be made to
your environment.
Additional Resources
For more information about modulefiles
, see: