Environment Modules

Environment Modules is a free open source environment manager software which provides simple environment initialization and modification of a working session. Software can be loaded or unloaded automatically and dynamically in a clean fashion. It supports the most popular shells : bash, ksh, zsh, sh, csh, tcsh, fish, as well as scripting languages : perl, ruby, tcl, python, cmake and R.

Useful commands

The following present the basic usefull commands for the use of Modules at CC-IN2P3.

% module help
Diplay the help of all commands.
% module [avail|view] [options]
List available software.
% module alias
Display available aliases.
% module help modulefile
Get information about the installed release of a software, such as version installed, and link to the changelog.
% module whatis modulefile
Get general information about a software, such as a short description and the official website.
% module [load|add] modulefile
Load a software.

Note

The path to the software version is necessary to load the software: module load Category/software/version

Aliases are avalaible and allow to load/unload directly the module: module load <alias>

Some software need to be loaded with additionnal options called variant. One can see the different variant using module show <modulefile> command.

% module [unload|rm] modulefile
Unload a software.
% module list
List the loaded software.
% module switch old-module new-module
Switch version.
% module [purge|clear]
Unload all loaded software.
% module reload
Reload all unloaded software.
% module save [collection]
Save the current configuration within a collection (see the dedicated section Collections). The collection will be saved by default in your $HOME/.module directory.
% module restore [collection]
Restore a saved collection.
% module saveshow [collection]
Display the current collection content.
% module [show|display] modulefile
To display the current modulefile environment variables as well as prerequisites and conflicts.

Warning

In case of problems with the module command, as command not found: module, please force the correct setting of the environment using the following commands:

  • (t)csh:

    source /etc/profile.d/modules.csh
    
  • bash, ksh, zsh:

    source /etc/profile.d/modules.sh
    
  • another solution can be to specify the -l option in the script shebang:

    #!/bin/SHELL -l
    

More commands and options are available in the official documentation command list.

Note

The module command can be shortened into ml, and some other commands also possess aliases which can be found in the alias section on the official documentation. You may also add shortcuts of your choice for software versions using aliases, tags or versions within the .modulerc as desribe in the paragraph Create a .modulerc file.

Usage examples

Get the software categories list:

% module view cat                % module view Compilers
 Analysis/                        --- Compilers/ : ---
 CC-IN2P3/                         f95/  g95/  gcc/  ghc/ intel/ pgi/  swig/
 Collaborative_Tools/
 Compilers/                      % module view gcc
 Containers/                       Compilers/gcc/
 [...]                             10.2.0  10.3.0 (gcc) [...] 8.3.1  9.3.1 (rh-devtoolset)

Load and unload Root 6.23.01:

% module add Analysis/root/6.23.01
Loading Analysis/root/6.23.01
    Loading requirement: Programming_Languages/python/3.8.6 Compilers/gcc/10.3.0

% module list
module list
Currently Loaded Modulefiles:
    1) Programming_Languages/python/3.8.6 <aL>   2) Compilers/gcc/10.3.0(latest) <aL>   3) Analysis/root/6.23.01

% module rm Analysis/root/6.23.01
Unloading Analysis/root/6.23.01
    Unloading useless requirement: Compilers/gcc/10.3.0 Programming_Languages/python/3.8.6

Customize Modules

Specific initialization

Modules is automatically initialized with the used shell but it can be initialized manually with a specific shell or language, by sourcing the avalaible scripts as follow:

Shell:
% source /usr/share/Modules/init/SHELL
Perl:
% require "/usr/share/Modules/init/perl.pm";
Python:
% import os
% exec(open('/usr/share/Modules/init/python.py').read())

Create a .modulerc file

In order to manage your aliases, versions, etc, you first need to create a .modulerc file in your $HOME directory. This file is then automatically loaded each time you run a module command.

Then, fill this file as shown in the following example:

#%Module1.0##################################################################
#
# This file defines the initial module command configuration, the default
# modulefiles search path and modulefiles you want to load by default for all
# users. It should contains lines of module command like 'module config conf
# val', 'module use path' and 'module load mod'
#
#############################################################################
# To load the default CC-IN2P3 configuration:
module config rcfile /pbs/software/centos-7-x86_64/modules/modulefiles/modulerc

# Add a modulefiles directory:
module use --append {/path/to/modulefiles}

# Remove a modulefiles directory from list:
module unuse {/path/to/already/used/modulefiles}

# Add alias to a module. It acts as a shortcup name to call a module.
module-alias name modulefile

# Add a version name to a module. It is shown by module as a tag after the module name and allows to load it with this name.
module-version modulefile version

# Add a virtual name to a module. This name is hide and allow to load the module with this name.
module-virtual name /path/to/the/modulefile

# Add a tag to a module.
module-tag [option] tag module

# Hide a modulefile.
module-hide [options] modulefile...

Note

In order to add the default CC-IN2P3 configuration to yours, you need to add in your $HOME/.modulerc file the following line: module config rcfile /pbs/software/centos-7-x86_64/modules/modulefiles/modulerc

Create his own modulefile

A modulefile sets the necessary environment variables for using a software. It can also manage easily dependances by forcing or, on the contrary, preventing the loading of other modules if there are needed or in conflict. To do so, the official documentation and the following template (also present in /pbs/software/centos-7-x86_64/modules/modulefiles/module-template) are at your disposal.

#%Module1.0####################################################################
##
##  my_module modulefile
##
##  Modulefile template, specifies some usefull and general commands.
##
##
###############################################################################

## Display help message:
proc ModulesHelp { } {
        puts stderr "Adds my personal infos to the environment."
}

## Create a whatis file.  Not nessecary but cool.
module-whatis   "Adds my own personal links, aliases and paths"

## Make conflict if some not wanted packages are already loaded.
## Print error if at least one of the modulefiles are already loaded.

conflict [modulefile or folder of modulefiles]

## Make prerequisites to load other modulefiles requested.
## Load automatically the module if it is not already loaded.

prereq [modulefile]

##
# for Tcl script use only
## Set local variables (usually: version, top dir and OS) :

set     var             var-value
set     version         v.XX-XX
set     topdir          path/to/soft/version
set     sys             centos-7-x86_64

## Set environnement variable:
setenv          SOFT_NAME             $topdir/bin/soft

## Unset an environment variable:
unsetenv        MY_VAR  "hello"

## Append a specific path:
append-path     PATH    /path/to

## Prepend a specific path:
prepend-path    PATH    /path/to

## Remove path:
remove-path     PATH    /path/to

## Source a shell script:
source-sh       /path/to/script.sh

## Set personal aliases:
set-alias       "alias"    "command"

## More options are avalaible here:
## https://modules.readthedocs.io/en/latest/modulefile.html#modules-specific-tcl-commands

In case of specific issues or demand please contact the user support.

Manage collections

Collections in Modules allow to save a complete environment, using a sequence of module use and module load commands.

  1. Using command line:
# Set a given modulepath
$ module use my/modulepath
# Load given softwares
$ module load soft1
$ module load soft2
# Save my_collection
$ module save my_collection

Those commands will store the collection in a $HOME/.module/my_collection file.

Note

If no name is given during the module save command, then the file is named $HOME/.module/default.

The default collection is automatically loaded at login.

  1. Collection file edition:

<<<<<<< HEAD Moreover, one can directly edit $HOME/.module/my_collection using the succesion of module use and module load commands. ======= Moreover, one can directly edit $HOME/.module/my_collection using the commands module use and module load. >>>>>>> 2fc93869c9d2504906457d4d8e0b65e9f7d84173

Finally, one can load a saved collection` using module restore my_collection command.