Environment Modules

Quite often, a very specific set of adjustments must be made to your shell environment in order to use a scientific software package.  This requires knowledge of file tedious system specifics, and involves issuing a number of lengthy commands, such as:

$ export PATH=$PATH:/a/binary
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/a/library.

Environment modules make it easier to modify your environment, switch between different environments, and provide a good way to document available software and libraries on the system.

To get started, take a look at what software and libraries are available:

$ module avail

------------------------------------------ /tools/modulefiles/compilers ------------------------------------------
cmake/     gcc/4.9.3(default)     openmpi/gcc/5.1.0/1.10.2
------------------------------------------ /tools/modulefiles/libraries ------------------------------------------
acml/gcc/4.4.7/5.3.1   fftw2/openmpi/gcc/float/2.1.5   hdf5/gcc/5.3.0/1.10.0
------------------------------------------ /tools/modulefiles/software -------------------------------------------
couenne/0.5.6  geant4/10.2.1  openfoam/3.0.1  python/3.5.1  soapdenovo/2.3.1
------------------------------------------ /tools/modulefiles/workload -------------------------------------------
default-environment torque/5.1.0

Here, you can see that modules are broken down into four categories: compilers, libraries, software, and workload.

System administrators create a module for every software package that is installed through a system software request. During this process, valuable details about the purpose of a particular software package, usage specifics, and installation are documented in the module “whatis” section.

To find out more information about what a module is and how to use it, issue “module whatis “:

$ module whatis openmpi

openmpi :

Name: OpenMPI
Version: 1.10.2 \ GCC 5.3.0
Category: Parallel, Compiler


OpenMPI is an open source implementation of the Message Passing Interface
specification. MPI facilitates parallel workloads through interprocess
communication where multiple communicators each perform similar work on a
subset of input, and results are aggregated to arrive upon a solution.

*Documentation available at https://www.open-mpi.org/doc/
*Tutorials available in /tools/docs/tutorials/mpi
*Version 1.10.2 installed by morgaia on 02.16.16. Built with GCC 5.3.0.
*Issue "module avail openmpi" to see all available versions.


Once you have found software of interest, “module load” can be used to set your environment to use a particular library or package:

To load a particular module:

module load [modulefile]

To unload a module:

module unload [modulefile]

To see what modules you currently have loaded:

module list

So, for example, in preparing to run a parallel job with MPI, you could see what versions are available with:

$ module avail openmpi
------------------------------------------ /tools/modulefiles/compilers ------------------------------------------
openmpi/gcc/4.9.1/1.8.3             openmpi/gcc/5.1.0/1.10.2    openmpi/gcc/5.1.0/1.8.5
openmpi/gcc/4.9.3/1.10.2(default)   openmpi/gcc/5.1.0/1.8.3     openmpi/gcc/5.3.0/1.10.2

From that list, you might choose the latest version:

$ module load openmpi/gcc/5.3.0/1.10.2

And then submit a quick test to the debug queue:

$ qsub -q debug my_mpi_job.sh

Essentially, a module’s main purpose is to make the necessary adjustments to environment variables so that software and libraries can be used without missing paths or runtime errors. As such, it abstracts some of the more terse details about software usage. In some cases, you may want to see exactly what a module is doing:

[hpcadmin@hopper-login](~)[09:54]: module show openmpi
prereq gcc/5.3.0
prepend-path PATH /tools/openmpi-1.10.2/gcc/5.3.0/bin
prepend-path MANPATH /tools/openmpi-1.10.2/gcc/5.3.0/share/man/
setenv MPI_HOME /tools/openmpi-1.10.2/gcc/5.3.0
setenv MPI_RUN /tools/openmpi-1.10.2/gcc/5.3.0/bin/mpirun
prepend-path LD_RUN_PATH /tools/openmpi-1.10.2/gcc/5.3.0/lib
prepend-path LD_LIBRARY_PATH /tools/openmpi-1.10.2/gcc/5.3.0/lib
prepend-path CPATH /tools/openmpi-1.10.2/gcc/5.3.0/include

To confirm and validate any changes made to your environment by the module file, you can take a look at your expected environment variable values. As mentioned previously, PATH and LD_LIBRARY_PATH are common environment variables that often need to be modified so that certain software and libraries can be used…


Because modules employ a very simple syntax, they are easy to learn and incorporate into your workflow. We hope you find Hopper’s implementation of modules as a convenient way to increase your research productivity.

You may also like...

Leave a Reply