Environment Modules

Make using pre-installed software packages and libraries easy

Environment modules make using pre-installed software packages and libraries easy by setting the appropriate environment variables. You can use environment modules by running the module command.

Available Modules

To see all available modules, run module avail:

$ module avail

---------- /usr/local/share/Modules/modulefiles -----------------
boost/1.55.0
boost/openmpi-1.10.2/1.55.0
cudann/cuda-8.0/5.0
cudann/cuda-8.0/5.1
cudatoolkit/10.0
...
-------------- /opt/share/Modules/modulefiles --------------
intel/16.0/64/16.0.4.258
intel/17.0/64/17.0.5.239
intel/18.0/64/18.0.3.222
...

One can also list specific modules:

$ module avail anaconda3

--------- /usr/licensed/Modules/modulefiles ----------
anaconda3/2018.12  anaconda3/2020.7   anaconda3/2022.5   
anaconda3/2019.3   anaconda3/2020.11  anaconda3/2022.10  
anaconda3/2019.10  anaconda3/2021.5   anaconda3/2023.3   
anaconda3/2020.2   anaconda3/2021.11  anaconda3/2023.9

Loading Modules

The environment modules that you load define part of your software environment which plays a role in determining the results of your code. For numerous reasons including scientific reproducibility, when loading an environment module you must specify the full name of the module. This can be done using module load, for example:

$ module load intel/19.0/64/19.0.3.199 openmpi/intel-17.0/3.1.3/64

Or equivalently:

$ module load intel/19.0/64/19.0.3.199
$ module load openmpi/intel-17.0/3.1.3/64

On some clusters you will encounter an error if you fail to specify the full name of the module:

$ module load anaconda3
ERROR: No default version defined for 'anaconda3'

$ module load anaconda3/2023.9
$ python --version
3.11.5

To see which specific modules are loaded, run module list:

$ module list
Currently Loaded Modulefiles:
1) openmpi/intel-17.0/3.1.3/64
2) intel-mkl/2019.3/3/64
3) intel/19.0/64/19.0.3.199
4) anaconda3/2023.9

Note that the module list command shows four modules while only three were explicitly loaded. In this case the intel module loads the intel-mkl module.

Since the the openmpi module has been loaded (as shown in module list above), you can run Open MPI commands. For example:

$ which mpicc
/usr/local/openmpi/3.1.3/intel170/x86_64/bin/mpicc

And a code could now be built with:

$ mpicc -o program program.c

Do not put the module load modulename/version command in your shell's startup script (e.g., ~/.bashrc) as it can lead to conflicts and difficult-to-diagnose problems. Instead, load modules directly in your Slurm scripts.

Module Aliases

If you would rather use short aliases instead of full module names then create a ~/.modulerc file as follows:

cat ~/.modulerc
#%Modulerc
module-alias anaconda3 anaconda3/2023.9
module-alias myintel intel/19.1.1.217

One can then do:

$ module load anaconda3 myintel

What exactly does loading a module do?

To see exactly which environment variables the module modifies, run module show modulename/version. For instance:

$ module show gsl/2.6
-------------------------------------------------------------------
/usr/local/share/Modules/modulefiles/gsl/2.6:

module-whatis	 Sets up gsl26 2.6 in your environment 
setenv		 GSL_ROOT_DIR /usr/local/gsl/2.6/x86_64 
prepend-path	 PATH /usr/local/gsl/2.6/x86_64/bin 
prepend-path	 CPATH /usr/local/gsl/2.6/x86_64/include 
prepend-path	 LD_LIBRARY_PATH /usr/local/gsl/2.6/x86_64/lib64 
prepend-path	 LIBRARY_PATH /usr/local/gsl/2.6/x86_64/lib64 
prepend-path	 MANPATH /usr/local/gsl/2.6/x86_64/share/man 
append-path	 -d   LOCAL_CFLAGS -I/usr/local/gsl/2.6/x86_64/include 
prepend-path	 PKG_CONFIG_PATH /usr/local/gsl/2.6/x86_64/lib64/pkgconfig 
-------------------------------------------------------------------

The output makes clear the path to the include files and libraries. This is useful for editing Makefiles.

Purging and Unloading Modules

To clear all modules use the following command:

$ module purge

The command above is often used in Slurm scripts to ensure that the environment is clean before setting the environment for the particular job.

To unload a module, use module unload. For example:

$ module unload anaconda3/2023.9

Create Your Own Module

You can create your own custom environment modules which will behave the same as the system modules.

Module Help

Run the following command to see all the options:

$ module help

  Modules Release 3.2.10 2012-12-21 (Copyright GNU GPL v2 1991):

  Usage: module [ switches ] [ subcommand ] [subcommand-args ]

Switches:
	-H|--help		this usage info
	-V|--version		modules version & configuration options
	-f|--force		force active dependency resolution
	-t|--terse		terse    format avail and list format
	-l|--long		long     format avail and list format
	-h|--human		readable format avail and list format
	-v|--verbose		enable  verbose messages
	-s|--silent		disable verbose messages
	-c|--create		create caches for avail and apropos
	-i|--icase		case insensitive
	-u|--userlvl 	set user level to (nov[ice],exp[ert],adv[anced])
  Available SubCommands and Args:
	+ add|load		modulefile [modulefile ...]
	+ rm|unload		modulefile [modulefile ...]
	+ switch|swap		[modulefile1] modulefile2
	+ display|show		modulefile [modulefile ...]
	+ avail			[modulefile [modulefile ...]]
	+ use [-a|--append]	dir [dir ...]
	+ unuse			dir [dir ...]
	+ update
	+ refresh
	+ purge
	+ list
	+ clear
	+ help			[modulefile [modulefile ...]]
	+ whatis		[modulefile [modulefile ...]]
	+ apropos|keyword	string
	+ initadd		modulefile [modulefile ...]
	+ initprepend		modulefile [modulefile ...]
	+ initrm		modulefile [modulefile ...]
	+ initswitch		modulefile1 modulefile2
	+ initlist
	+ initclear