The module system

The module system enables managing several mutually incompatible software environments within one computer. Use the module command to query the available applications, libraries or compiler suites, and dynamically initialize them. The module system should be used for both interactive and batch jobs.

The environment modules provide a convenient way to set up everything required by a particular application. The module system modifies the environment variables of the user's shell so that the correct versions of executables are in the path and the linker can find the correct version of the required libraries. For example, the command mpicc points to different compilers depending on the module loaded.

CSC uses Lmod environment modules. They are developed at the Texas Advanced Computing Center (TACC) and implemented using the Lua programming language. More technical details can be found on the Lmod homepage.

Basic usage

The syntax of the module command:

module command module-name

Listing the modules loaded (including your current environment):

module list

The command module help provides general information about a module. For example, to get more information about the module intel, use:

module help intel

Load new modules to your environment with the command load. For example, to load the intel-mpi module, use:

module load intel-mpi

Note that you can only load modules that are compatible with the other loaded modules. That is, you cannot load modules that are conflicting with previously loaded modules, or modules that depend on modules that have not been loaded.

Modules that are not needed or conflict with other modules can be unloaded using unload:

module unload intel-mkl

The most commonly used module commands:

Module command Description
module help modulename Information about a module.
module load modulename Loads the environment module.
module unload modulename Unloads the environment module.
module list List the loaded modules.
module avail List all available modules.
module spider name Searches the entire module list.
module swap module1 module2 Replace a module with another.

Finding modules

You can list the modules that are compatible with your current module set by using:

module avail

Because of the hierarchical structure of the Lmod system, it is not possible to load all installed modules simply using a single module load command. The avail command does not show modules that cannot be loaded due to conflicts or unmet dependencies. These protective restrictions prevent the loading of incompatible module combinations.

List all installed software packages:

module spider

List modules by name:

module spider int

The above command will list all modules with the string int in their name. A more detailed description of a module can be printed using the full module name with a version number:

module spider fftw/3.3.8

Solving module dependencies

Some modules depend on other modules. If a required module is missing, the module system prints an error message:

$ module load parallel-netcdf

Lmod has detected the following error:  These module(s) exist but
cannot be loaded as requested: "parallel-netcdf"
Try: "module spider parallel-netcdf" to see how to load the module(s).

$ module spider parallel-netcdf

----------------------------------------------------------------------------
  parallel-netcdf:
----------------------------------------------------------------------------
     Versions:
        parallel-netcdf/1.8.0

----------------------------------------------------------------------------
  For detailed information about a specific "parallel-netcdf" module
  (including how to load the modules) use the module's full name.
  For example:

$ module spider parallel-netcdf/1.8.0
----------------------------------------------------------------------------

In such cases, the module avail command excludes the module from the list and the module load command cannot find it. The easiest way to find out the required environment is to use the module spider command with the version information. For example:

$ module spider parallel-netcdf/1.8.0
------------------------------------------------------------------
 parallel-netcdf: parallel-netcdf/1.8.0
------------------------------------------------------------------
 You will need to load all module(s) on any one of the lines below before
 the "parallel-netcdf/1.8.0" module is available to load.

 gcc/9.1.0  hpcx-mpi/2.4.0
 intel/19.0.4  hpcx-mpi/2.4.0
...

In this case, you will have to load one the listed environments before proceeding with module load command.

Advanced topics

In general, applications and their dependencies should be compiled and linked using the same compiler. In some cases this is a strict requirement. For example, you can not use the MPI Fortran90 module compiled with Intel compilers with gfortran. Environment modules have several mechanisms that prevent the user from setting up an incompatible environment.

The module hierarchy contributes to keeping the compiler and MPI library settings compatible with each other. In practice, for each supported compiler, there is a module for a supported MPI library. When the user switches the compiler module, the module system tries to find the correct versions of the loaded modules:

$ module list
Currently Loaded Modules:
 1) gcc/9.1.0   2) hpcx-mpi/2.4.0   3) parallel-netcdf/1.8.0

$ module swap gcc intel
Due to MODULEPATH changes the following modules have been reloaded:
 1) hpcx-mpi/2.4.0     2) parallel-netcdf/1.8.0

$ module list
Currently Loaded Modules:
 1) intel/19.0.4   2) hpcx-mpi/2.4.0   3) parallel-netcdf/1.8.0

If the correct version is not found, the module system deactivates these modules. In practice, the module is unloaded, but it is marked so that when the compiler/MPI configuration is changed, the system tries to find the correct version automatically.

This hierarchy is implemented by changing the $MODULEPATH variable. Every compiler module adds its own path to the module path so that the software modules compatible with that specific compiler can be listed. When the compiler module is unloaded, this path is removed from the module path. The same applies to the MPI modules as well.

Using your own module files

If you want to control the software packages using modules installed by yourself, you can place your own module files in your home directory. For example, if you include module files in $HOME/modulefiles, you can access them after adding the path to the module search path using the command:

module use $HOME/modulefiles