Skip to content

Environment Modules

Kennesaw State's HPC uses a piece of software known as Environment Modules to manage nearly all our installed software. There are two huge advantages of the module approach:

  1. We can provide many different versions and installations of a single package on a given machine, including a default version as well as several older and newer versions; and

  2. Users can easily switch to different versions or installations without specifying additional paths. The Environment Modules software manages environment variables and configuration settings for each package without the user needing any details about how we installed the software.

The Environment Modules software consists of two parts: the module command and the modulefiles on which it operates.

Module Command Syntax

module help

To get a usage list of module commands, type the following:

[barney@hpc ~]$ module help
Modules Release 5.2.0 (2022-11-08)
Usage: module [options] [command] [args ...]

Loading / Unloading commands:
  add | load      modulefile [...]  Load modulefile(s)
  try-add | try-load modfile [...]  Load modfile(s), no complain if not found
  add-any | load-any modfile [...]  Load first available modulefile in list
  rm | unload     modulefile [...]  Remove modulefile(s)
  purge                             Unload all loaded modulefiles
  reload                            Unload then load all loaded modulefiles
  switch | swap   [mod1] mod2       Unload mod1 and load mod2
  refresh                           Refresh loaded module volatile components
  reset                             Restore initial environment

Listing / Searching commands:
  list   [-a] [-t|-l|-j] [-S|-C] [mod ...]
                                    List all or matching loaded modules
  avail  [-a] [-t|-l|-j] [-S|-C] [-d|-L] [--indepth|--no-indepth] [mod ...]
                                    List all or matching available modules
  aliases         [-a]              List all module aliases
  whatis [-a] [-j] [modulefile ...] Print whatis information of modulefile(s)
  apropos | keyword | search [-a] [-j] str
                                    Search all name and whatis containing str
  is-loaded       [modulefile ...]  Test if any of the modulefile(s) are loaded
  is-avail        modulefile [...]  Is any of the modulefile(s) available
  info-loaded     modulefile        Get full name of matching loaded module(s)

Collection of modules handling commands:
  save            [collection|file] Save current module list to collection
  restore         [collection|file] Restore module list from collection or file
  saverm          [collection]      Remove saved collection
  saveshow        [collection|file] Display information about collection
  savelist  [-a] [-t|-l|-j] [-S|-C] [collection ...]
                                    List all or matching saved collections
  is-saved        [collection ...]  Test if any of the collection(s) exists
  stash                             Save current environment and reset
  stashpop        [stash]           Restore then remove stash collection
  stashrm         [stash]           Remove stash collection
  stashshow       [stash]           Display information about stash collection
  stashclear                        Remove all stash collections
  stashlist                         List all stash collections

Environment direct handling commands:
  prepend-path [-d c] var val [...] Prepend value to environment variable
  append-path [-d c] var val [...]  Append value to environment variable
  remove-path [-d c] var val [...]  Remove value from environment variable

Other commands:
  help            [modulefile ...]  Print this or modulefile(s) help info
  display | show  modulefile [...]  Display information about modulefile(s)
  test            [modulefile ...]  Test modulefile(s)
  use     [-a|-p] dir [...]         Add dir(s) to MODULEPATH variable
  unuse           dir [...]         Remove dir(s) from MODULEPATH variable
  is-used         [dir ...]         Is any of the dir(s) enabled in MODULEPATH
  path            modulefile        Print modulefile path
  paths           modulefile        Print path of matching available modules
  clear           [-f]              Reset Modules-specific runtime information
  source          scriptfile [...]  Execute scriptfile(s)
  config [--dump-state|name [val]]  Display or set Modules configuration
  state           [name]            Display Modules state
  sh-to-mod       shell shellscript [arg ...]
                                    Make modulefile from script env changes
  mod-to-sh       shell modulefile [...]
                                    Make shell code from modulefile env changes
  edit            modulefile        Open modulefile in editor
  lint       [-a] [modulefile ...]  Check syntax of modulefile

Switches:
  -t | --terse    Display output in terse format
  -l | --long     Display output in long format
  -j | --json     Display output in JSON format
  -o LIST | --output=LIST
                  Define elements to output on 'avail' or 'list' sub-commands
                  in addition to module names (LIST is made of items like
                  'sym', 'tag' or 'key' separated by ':')
  -a | --all      Include hidden modules in search
  -d | --default  Only show default versions available
  -L | --latest   Only show latest versions available
  -S | --starts-with
                  Search modules whose name begins with query string
  -C | --contains Search modules whose name contains query string
  -i | --icase    Case insensitive match
  -a | --append   Append directory to MODULEPATH (on 'use' sub-command)
  -p | --prepend  Prepend directory to MODULEPATH
  --auto          Enable automated module handling mode
  --no-auto       Disable automated module handling mode
  -f | --force    By-pass dependency consistency or confirmation dialog
  --tag=LIST      Apply tag to loading module on 'load', 'try-load', 'load-any'
                  or 'switch' sub-commands (LIST is made of tag names
                  separated by ':')

Options:
  -h | --help     This usage info
  -V | --version  Module version
  -D | --debug    Enable debug messages
  -T | --trace    Enable trace messages
  -v | --verbose  Enable verbose messages
  -s | --silent   Turn off error, warning and informational messages
  --timer         Report execution times
  --paginate      Pipe mesg output into a pager if stream attached to terminal
  --no-pager      Do not pipe message output into a pager
  --redirect      Send output to stdout (only for sh, bash, ksh, zsh and fish)
  --no-redirect   Send output to stderr
  --color[=WHEN]  Colorize the output; WHEN can be 'always' (default if
                  omitted), 'auto' or 'never'
  -w COLS | --width=COLS
                  Set output width to COLS columns.

module list

[barney@hpc ~]$ module list

This command lists all the modulefiles that are currently loaded into your environment.

module avail

[barney@hpc ~]$ module avail

This command lists all the modulefiles that are available to be loaded. Notice that many have version numbers associated with them and that one is labeled as the default where there is more than one version. You can also restrict this command to a single package; for example,

[barney@hpc ~]$ module avail visit

module display

[barney@hpc ~]$ module display [modulefile]

Use this command to see all of the changes a given modulefile will make in your environment, such as changes to the PATH environment variable. This command is synonymous with

[barney@hpc ~]$ module show [modulefile]

module load

[barney@hpc ~]$ module load [modulefile1] [modulefile2] ...

This command adds one or more modulefiles to your current environment. It does so silently unless there is a problem with a modulefile. If you load the generic name of a module, you will get the default version. To load a specific version, load the modulefile using its full specification. For example,

[barney@hpc ~]$ module load visit

will do the same thing as

[barney@hpc ~]$ module load visit/2.1.2

module unload

[barney@hpc ~]$ module unload [modulefile]

This command removes the listed module from the user's current environment. Modulefiles can be removed in any order. Note that this command will fail silently if the modulefile you specify is not already loaded.

module switch

[barney@hpc ~]$ module switch [modulefile_old] [modulefile_new]

This command demonstrates the true advantage of using modules. You can use this command to switch between versions of software packages (or even switch between different packages) with a single module command.

This command is synonymous with

[barney@hpc ~]$ module swap [modulefile_old] [modulefile_new]

Note that the following command would be completely correct and appropriate if, before issuing it, you had issued a module load command for a non-default version of the VisIt software and you wish to switch to the default version:

[barney@hpc ~]$ module swap visit visit

Please refer to module man page for more details.

Loading Modules into Your Default Environment

Use the .modules file to maintain the modules you wish to load whenever you log in. However, you can use any of the following files, depending on your shell:

Shell Shell Startup Files
csh .modules, .cshrc(.ext), .csh_variables, and .login(.ext)
tcsh .modules, .tcshrc, .cshrc(.ext), .csh_variables, and .login(.ext)
sh .modules and .profile(.ext)
ksh .modules, .profile(.ext), and kshenv(.ext)
bash .modules, .bash_profile, .bash_login, .profile(.ext), and .bashrc(.ext)
zsh .modules, .zshenv(.ext), .zlogin(.ext), and .zshrc(.ext)

The system checks for the startup files in the order they are listed.

The module command comes with a series of sub-commands to help maintain your startup files:

module initadd

[barney@hpc ~]$ module initadd modulefile

This command adds modulefile to the shell's initialization file in your home directory. For any of the init sub-commands to work correctly, you must add a module load line to one of the startup files listed above. If the module load line is found in multiple shell initialization files, all instances of the module load lines are changed.

module initprepend

[barney@hpc ~]$ module initprepend modulefile

This command does the same thing as module initadd but prepends the given modules to the beginning of the list.

module initrm

[barney@hpc ~]$ module initrm modulefile

This command removes modulefile from the shell's initialization files.

module initswitch

[barney@hpc ~]$ module initswitch modulefile_old modulefile_new

This command switches modulefile_old with modulefile_new in the shell's initialization files.

module initlist

[barney@hpc ~]$ module initlist

This command lists all of the modulefiles loaded from the shell's initialization file.

module initclear

[barney@hpc ~]$ module initclear

This command clears all of the modulefiles from the shell's initializtion files.

Install your own customized modules

You can create and install modules for your convenience or share software among collaborators. The module definition files can be in a project directory, your home directory, or any available file system. Ensure the UNIX file permissions grant access to all users who want to use the software. (Note: do not give write permissions in your home directory to anyone else!)

You can look at the existing modules and the modulefile man page for information regarding writing module files. Take a look at the use.own module. It automatically creates and enables a private module directory in your home directory.

Please contact hpc@kennesaw.edu if you need help with creating modules.

References

Information taken from NERSC Web Site: http://www.nersc.gov/users/software/nersc-user-environment/modules/