NAME¶module - command interface to the Modules package
SYNOPSIS¶module [switches] [sub-command [sub-command-args]]
DESCRIPTION¶module is a user interface to the Modules package. The Modules package provides for the dynamic modification of the user's environment via modulefiles.
Each modulefile contains the information needed to configure the shell for an application. Once the Modules package is initialized, the environment can be modified on a per-module basis using the module command which interprets modulefiles. Typically modulefiles instruct the module command to alter or set shell environment variables such as PATH, MANPATH, etc. Modulefiles may be shared by many users on a system and users may have their own set to supplement or replace the shared modulefiles.
The modulefiles are added to and removed from the current environment by the user. The environment changes contained in a modulefile can be summarized through the module command as well. If no arguments are given, a summary of the module usage and sub-commands are shown.
The action for the module command to take is described by the sub-command and its associated arguments.
Package Initialization¶The Modules package and the module command are initialized when a shell-specific initialization script is sourced into the shell. The script creates the module command as either an alias or function and creates Modules environment variables.
The module alias or function executes the modulecmd.tcl program located in /usr/lib/x86_64-linux-gnu and has the shell evaluate the command's output. The first argument to modulecmd.tcl specifies the type of shell.
The initialization scripts are kept in /usr/share/modules/init/<shell> where <shell> is the name of the sourcing shell. For example, a C Shell user sources the /usr/share/modules/init/csh script. The sh, csh, tcsh, bash, ksh, zsh and fish shells are supported by modulecmd.tcl. In addition, python, perl, ruby, tcl, cmake, r and lisp "shells" are supported which writes the environment changes to stdout as python, perl, ruby, tcl, lisp, r or cmake code.
Initialization may also be performed by calling the autoinit sub-command of the modulecmd.tcl program. Evaluation into the shell of the result of this command defines the module alias or function.
Examples of initialization¶C Shell initialization (and derivatives):
source /usr/share/modules/init/csh module load modulefile modulefile ...
Bourne Shell (sh) (and derivatives):
. /usr/share/modules/init/sh module load modulefile modulefile ...
require "/usr/share/modules/init/perl.pm"; &module('load', 'modulefile', 'modulefile', '...');
import os exec(open('/usr/share/modules/init/python.py').read()) module('load', 'modulefile', 'modulefile', '...')
Bourne Shell (sh) (and derivatives) with autoinit sub-command:
eval "`/usr/lib/x86_64-linux-gnu/modulecmd.tcl sh autoinit`"
Modulecmd startup¶Upon invocation modulecmd.tcl sources if it exists a site-specific configuration script located in /etc/environment-modules/siteconfig.tcl. This Tcl script enables to supersede any global variable or procedure definition of modulecmd.tcl.
Afterward, modulecmd.tcl sources rc files which contain global, user and modulefile specific setups. These files are interpreted as modulefiles. See modulefile(4) for detailed information.
Upon invocation of modulecmd.tcl module run-command files are sourced in the following order:
- Global RC file as specified by $MODULERCFILE or /usr/share/modules/etc/rc. If $MODULERCFILE points to a directory, the modulerc file in this directory is used as global RC file.
- User specific module RC file $HOME/.modulerc
- All .modulerc and .version files found during modulefile seeking.
Command line switches¶The module command accepts command line switches as its first parameter. These may be used to control output format of all information displayed and the module behavior in case of locating and interpreting modulefiles.
All switches may be entered either in short or long notation. The following switches are accepted:
Module Sub-Commands¶help [modulefile...]
load [--auto|--no-auto] [-f] modulefile...
unload [--auto|--no-auto] [-f] modulefile...
swap [modulefile1] modulefile2
switch [--auto|--no-auto] [-f] [modulefile1] modulefile2
avail [-d|-L] [-t|-l] [path...]
Symbolic version-names and aliases found in the search are displayed in the result of this sub-command. Symbolic version-names are displayed next to the modulefile they are assigned to within parenthesis. Aliases are listed in the MODULEPATH section where they have been defined. To distinguish aliases from modulefiles a @ symbol is added within parenthesis next to their name. Aliases defined through a global or user specific module RC file are listed under the global/user modulerc section.
use [-a|--append] directory...
Reference counter environment variable MODULEPATH_modshare is also set to increase the number of times directory has been added to MODULEPATH.
Reference counter of directory in MODULEPATH denotes the number of times directory has been enabled. When attempting to remove directory from MODULEPATH, reference counter variable MODULEPATH_modshare is checked and directory is removed only if its relative counter is equal to 1 or not defined. Elsewhere directory is kept and reference counter is decreased by 1.
No unload then load is performed and an error is returned if the loaded modulefiles have unsatisfied constraint corresponding to the prereq and conflict they declare.
If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable will be appended to the collection file name.
By default, if loaded modulefile corresponds to the default module version, the bare module name is recorded. If MODULES_COLLECTION_PIN_VERSION is set to 1, module version is always recorded even if it is the default version.
No collection is recorded and an error is returned if the loaded modulefiles have unsatisfied constraint corresponding to the prereq and conflict they declare.
When restoring a collection, the currently set MODULEPATH directory list and the currently loaded modulefiles are unused and unloaded then used and loaded to exactly match the MODULEPATH and loaded modulefiles lists saved in this collection file. The order of the paths and modulefiles set in collection is preserved when restoring. It means that currently loaded modules are unloaded to get the same LOADEDMODULES root than collection and currently used module paths are unused to get the same MODULEPATH root. Then missing module paths are used and missing modulefiles are loaded.
TENEX C Shell
Bourne and Korn Shells
GNU Bourne Again Shell
Friendly Interactive Shell
If a module load line is found in any of these files, the modulefiles are appended to any existing list of modulefiles. The module load line must be located in at least one of the files listed above for any of the init sub-commands to work properly. If the module load line is found in multiple shell initialization files, all of the lines are changed.
initswitch modulefile1 modulefile2
append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
remove-path [-d C|--delim C|--delim=C] [--index] variable value...
Modulefiles¶modulefiles are written in the Tool Command Language (Tcl) and are interpreted by modulecmd.tcl. modulefiles can use conditional statements. Thus the effect a modulefile will have on the environment may change depending upon the current state of the environment.
Environment variables are unset when unloading a modulefile. Thus, it is possible to load a modulefile and then unload it without having the environment variables return to their prior state.
Collections¶Collections describe a sequence of module use then module load commands that are interpreted by modulecmd.tcl to set the user environment as described by this sequence. When a collection is activated, with the restore sub-command, module paths and loaded modules are unused or unloaded if they are not part or if they are not ordered the same way as in the collection.
Collections are generated by the save sub-command that dumps the current user environment state in terms of module paths and loaded modules. By default collections are saved under the $HOME/.module directory.
Collections may be valid for a given target if they are suffixed. In this case these collections can only be restored if their suffix correspond to the current value of the MODULES_COLLECTION_TARGET environment variable (see the dedicated section of this topic below).
EXIT STATUS¶The module command exits with 0 if its execution succeed. Elsewhere 1 is returned.
Path elements registered in the MODULEPATH environment variable may contain reference to environment variables which are converted to their corresponding value by module command each time it looks at the MODULEPATH value. If an environment variable referred in a path element is not defined, its reference is converted to an empty string.
Automated module handling mode consists in additional actions triggered when loading or unloading a modulefile to satisfy the constraints it declares. When loading a modulefile, following actions are triggered:
- Requirement Load: load of the modulefiles declared as a prereq of the loading modulefile.
- Dependent Reload: reload of the modulefiles declaring a prereq onto loaded modulefile or declaring a prereq onto a modulefile part of this reloading batch.
When unloading a modulefile, following actions are triggered:
- Dependent Unload: unload of the modulefiles declaring a non-optional prereq onto unloaded modulefile or declaring a non-optional prereq onto a modulefile part of this unloading batch. A prereq modulefile is considered optional if the prereq definition order is made of multiple modulefiles and at least one alternative modulefile is loaded.
- Useless Requirement Unload: unload of the prereq modulefiles that have been automatically loaded for either the unloaded modulefile, an unloaded dependent modulefile or a modulefile part of this useless requirement unloading batch. Modulefiles are added to this unloading batch only if they are not required by any other loaded modulefiles.
- Dependent Reload: reload of the modulefiles declaring a conflict or an optional prereq onto either the unloaded modulefile, an unloaded dependent or an unloaded useless requirement or declaring a prereq onto a modulefile part of this reloading batch.
In case a loaded modulefile has some of its declared constraints unsatisfied (pre-required modulefile not loaded or conflicting modulefile loaded for instance), this loaded modulefile is excluded from the automatic reload actions described above.
For the specific case of the switch sub-command, where a modulefile is unloaded to then load another modulefile. Dependent modulefiles to Unload are merged into the Dependent modulefiles to Reload that are reloaded after the load of the switched-to modulefile.
Automated module handling mode enablement is defined in the following order of preference: --auto/--no-auto command line switches, then MODULES_AUTO_HANDLING environment variable, then the default set in modulecmd.tcl script configuration. Which means MODULES_AUTO_HANDLING overrides default configuration and --auto/--no-auto command line switches override every other ways to enable or disable this mode.
Collection directory may sometimes be shared on multiple machines which may use different modules setup. For instance modules users may access with the same HOME directory multiple systems using different OS versions. When it happens a collection made on machine 1 may be erroneous on machine 2.
When a target is set, only the collections made for that target are available to the restore, savelist, saveshow and saverm sub-commands. Saving collection registers the target footprint by suffixing the collection filename with .$MODULES_COLLECTION_TARGET. Collection target is not involved when collection is specified as file path on the saveshow, restore and save sub-commands.
For example, the MODULES_COLLECTION_TARGET variable may be set with results from commands like lsb_release, hostname, dnsdomainname, etc.
This environment variable is intended for module command internal use to get knowledge of the alternative names matching loaded modulefiles in order to keep environment consistent when conflicts or pre-requirements are set over these alternative designations. It also helps to find a match after modulefiles being loaded when unload, is-loaded or info-loaded actions are run over these names.
This environment variable is intended for module command internal use to get knowledge of the conflicts declared by the loaded modulefiles in order to keep environment consistent when a conflicting module is asked for load afterward.
This environment variable is intended for module command internal use to distinguish the modulefiles that have been loaded automatically from modulefiles that have been asked by users.
This environment variable is intended for module command internal use to get knowledge of the pre-requirement declared by the loaded modulefiles in order to keep environment consistent when a pre-required module is asked for unload afterward.
Paging command and options are defined for Modules in the following order of preference: MODULES_PAGER environment variable, then the default set in modulecmd.tcl script configuration. Which means MODULES_PAGER overrides default configuration.
If MODULES_PAGER variable is set to an empty string or to the value cat, pager will not be launched.
Each variable found in MODULES_RUN_QUARANTINE will have its value emptied or set to the value of the corresponding MODULES_RUNENV_<VAR> variable when defining modulecmd.tcl run-time environment.
Original values of these environment variables set in quarantine are passed to modulecmd.tcl via <VAR>_modquar variables.
COPYRIGHT¶1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen, 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2019 Xavier Delaruelle