Ubuntu Manpage: module - command interface to the Modules package

Provided by: environment-modules_5.2.0-1_amd64

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 executes the autoinit
sub-command of the modulecmd.tcl program located in /usr/lib/x86_64-linux-gnu for the
corresponding shell. The output of this execution is evaluated by shell which creates the
module command as either an alias or function and creates Modules environment variables.

During this initialization process, if the Modules environment is found undefined (when
both MODULEPATH and LOADEDMODULES are found either unset or empty), the modulespath and
initrc configuration files located in /etc/environment-modules are evaluated if present
and following this order. modulespath file contains the list of modulepaths to enable
during initialization. In this file, the modulepaths are separated by newline or colon
characters. initrc is a modulefile that defines during initialization the modulepaths to
enable, the modules to load and the module configuration to apply.

During the initialization process, if the Modules environment is found defined a module
refresh is automatically applied to restore in the current environment all non-persistent
components set by loaded modules.

The module alias or function executes the modulecmd.tcl program 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, fish and cmd 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 directly calling the autoinit sub-command of the
modulecmd.tcl program.

A ml alias or function may also be defined at initialization time if enabled (see
MODULES_ML section). ml is a handy frontend leveraging all module command capabilities
with less character typed. See ml(1) for detailed information.

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 ...

Perl:

require "/usr/share/modules/init/perl.pm";
&module('load', 'modulefile', 'modulefile', '...');

Python:

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 a site-specific configuration script if it exists.
Siteconfig script is a Tcl script located at /etc/environment-modules/siteconfig.tcl. It
enables to supersede any global variable or procedure definition of modulecmd.tcl. See
Site-specific configuration for detailed information.

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:

1. Global RC file as specified by MODULERCFILE variable or /etc/environment-modules/rc. If
MODULERCFILE points to a directory, the modulerc file in this directory is used as
global RC file.

2. User specific module RC file $HOME/.modulerc

3. All .modulerc and .version files found during modulefile seeking.

These module run-command files must begins like modulefiles with the #%Module file
signature, also called the Modules magic cookie. A version number may be placed after this
string. The version number reflects the minimum version of modulecmd.tcl required to
interpret the run-command file. If a version number doesn't exist, then modulecmd.tcl will
assume the run-command file is compatible. Files without the magic cookie or with a
version number greater than the current version of modulecmd.tcl will not be interpreted
and an error is reported. Such error does not abort the whole module evaluation. If the
mcookie_version_check configuration is disabled the version number set is not checked.

NOTE:
Run-command files are intended to set parameters for modulefiles, not to configure the
module command itself.

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:

--all, -a
Include hidden modules in search performed with avail, aliases, list, lint,
savelist, search or whatis sub-commands. Hard-hidden modules are not affected by
this option.

--auto Enable automated module handling mode on sub-commands that load or unload
modulefiles. See also MODULES_AUTO_HANDLING section.

--color=<WHEN>
Colorize the output. WHEN defaults to always or can be never or auto. See also
MODULES_COLOR section.

--contains, -C
On avail, list and savelist sub-commands, return modules or collections whose fully
qualified name contains search query string.

--debug, -D, -DD
Debug mode. Causes module to print debugging messages about its progress. Multiple
-D options increase the debug verbosity. The maximum is 2.

--default, -d
On avail sub-command, display only the default version of each module name. Default
version is the explicitly set default version or also the implicit default version
if the configuration option implicit_default is enabled (see Locating Modulefiles
section in the modulefile(4) man page for further details on implicit default
version).

--force, -f
On load, unload, switch, load-any, try-load, mod-to-sh and source sub-commands
by-pass any unsatisfied modulefile constraint corresponding to the declared prereq
and conflict. Which means for instance that a modulefile will be loaded even if it
comes in conflict with another loaded modulefile or that a modulefile will be
unloaded even if it is required as a prereq by another modulefile.

On clear sub-command, skip the confirmation dialog and proceed.

On purge sub-command also unload sticky modules and modulefiles that are depended
by non-unloadable modules.

--help, -h
Give some helpful usage information, and terminates the command.

--icase, -i
Match module specification arguments in a case insensitive manner.

--indepth
On avail sub-command, include in search results the matching modulefiles and
directories and recursively the modulefiles and directories contained in these
matching directories.

--json, -j
Display avail, list, savelist, stashlist, whatis and search output in JSON format.

--latest, -L
On avail sub-command, display only the highest numerically sorted version of each
module name (see Locating Modulefiles section in the modulefile(4) man page).

--long, -l
Display avail, list, savelist and stashlist output in long format.

--no-auto
Disable automated module handling mode on sub-commands that load or unload
modulefiles. See also MODULES_AUTO_HANDLING section.

--no-indepth
On avail sub-command, limit search results to the matching modulefiles and
directories found at the depth level expressed by the search query. Thus
modulefiles contained in directories part of the result are excluded.

--no-pager
Do not pipe message output into a pager.

--no-redirect
Do not send message output to stdout. Keep it on stderr.

--output=LIST, -o LIST
Define the content to report in addition to module names. This option is supported
by avail and list sub-commands on their regular or terse output modes. Accepted
values are a LIST of elements to report separated by colon character (:). The order
of the elements in LIST does not matter.

Accepted elements in LIST for avail sub-command are: modulepath, alias, dirwsym,
sym, tag and key.

Accepted elements in LIST for list sub-command are: header, idx, variant, sym, tag
and key.

The order of the elements in LIST does not matter. Module names are the only
content reported when LIST is set to an empty value.

See also MODULES_AVAIL_OUTPUT and MODULES_LIST_OUTPUT.

--paginate
Pipe all message output into less (or if set, to the command referred in
MODULES_PAGER variable) if error output stream is a terminal. See also
MODULES_PAGER section.

--redirect
Send message output to stdout instead of stderr. Only supported on sh, bash, ksh,
zsh and fish shells.

--silent, -s
Turn off error, warning and informational messages. module command output result is
not affected by silent mode.

--starts-with, -S
On avail, list and savelist sub-commands, return modules or collections whose name
starts with search query string.

--tag=LIST
On load, load-any, switch and try-load sub-commands, apply LIST of module tags to
the loading modulefile. LIST corresponds to the concatenation of multiple tags
separated by colon character (:). LIST should not contain tags inherited from
modulefile state or from other modulefile commands. If module is already loaded,
tags from LIST are added to the list of tags already applied to this module.

--terse, -t
Display avail, list, savelist and stashlist output in short format.

--timer
Prints at the end of the output an evaluation of the total execution time of the
module command. When mixed with a single or multiple --debug options, replaces
regular debug messages by reports of the execution time of every internal procedure
calls.

--trace, -T
Trace mode. Report details on module searches, resolutions, selections and
evaluations in addition to printing verbose messages.

--verbose, -v, -vv
Enable verbose messages during module command execution. Multiple -v options
increase the verbosity level. The maximum is 2.

--version, -V
Lists the current version of the module command. The command then terminates
without further processing.

--width=COLS, -w COLS
Set the width of the output to COLS columns. See also MODULES_TERM_WIDTH section.

Module Sub-Commands
add [options] modulefile...
See load.

add-any [options] modulefile...
See load-any.

aliases [-a]
List all available symbolic version-names and aliases in the current MODULEPATH.
All directories in the MODULEPATH are recursively searched in the same manner than
for the avail sub-command. Only the symbolic version-names and aliases found in the
search are displayed.

append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
Append value to environment variable. The variable is a colon, or delimiter,
separated list. See append-path in the modulefile(4) man page for further
explanation.

When append-path is called as a module sub-command, the reference counter variable,
which denotes the number of times value has been added to environment variable, is
not updated unless if the --duplicates option is set.

apropos [-a] [-j] string
See search.

avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]
List all available modulefiles in the current MODULEPATH. All directories in the
MODULEPATH are recursively searched for files containing the Modules magic cookie.
If a pattern argument is given, then each directory in the MODULEPATH is searched
for modulefiles whose pathname, symbolic version-name or alias match pattern in a
case insensitive manner by default. pattern may contain wildcard characters.
Multiple versions of an application can be supported by creating a subdirectory for
the application containing modulefiles for each version.

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.

When colored output is enabled and a specific graphical rendition is defined for
module default version, the default symbol is omitted and instead the defined
graphical rendition is applied to the relative modulefile. When colored output is
enabled and a specific graphical rendition is defined for module alias, the @
symbol is omitted. The defined graphical rendition applies to the module alias
name. See MODULES_COLOR and MODULES_COLORS sections for details on colored output.

Module tags applying to the available modulefiles returned by the avail sub-command
are reported along the module name they are associated to (see Module tags
section).

A Key section is added at the end of the output in case some elements are reported
in parentheses or chevrons along module name or if some graphical rendition is made
over some output elements. This Key section gives hints on the meaning of such
elements.

The parameter pattern may also refer to a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).

clear [-f]
Force the Modules package to believe that no modules are currently loaded. A
confirmation is requested if command-line switch -f (or --force) is not passed.
Typed confirmation should equal to yes or y in order to proceed.

config [--dump-state|name [value]|--reset name]
Gets or sets modulecmd.tcl options. Reports the currently set value of passed
option name or all existing options if no name passed. If a name and a value are
provided, the value of option name is set to value. If command-line switch --reset
is passed in addition to a name, overridden value for option name is cleared.

When a reported option value differs from default value a mention is added to
indicate whether the overridden value is coming from a command-line switch
(cmd-line) or from an environment variable (env-var). When a reported option value
is locked and cannot be altered a (locked) mention is added.

If no value is currently set for an option name, the mention <undef> is reported.

When command-line switch --dump-state is passed, current modulecmd.tcl state and
Modules-related environment variables are reported in addition to currently set
modulecmd.tcl options.

Existing option names are:

advanced_version_spec
Advanced module version specification to finely select modulefiles.

Default value is 1. It can be changed at installation time with
--disable-advanced-version-spec option. The MODULES_ADVANCED_VERSION_SPEC
environment variable is defined by config sub-command when changing this
configuration option from its default value. See
MODULES_ADVANCED_VERSION_SPEC description for details.

auto_handling
Automated module handling mode.

Default value is 1. It can be changed at installation time with
--disable-auto-handling option. The MODULES_AUTO_HANDLING environment
variable is defined by config sub-command when changing this configuration
option from its default value. The --auto and --no-auto command line
switches change the value of this configuration option. See
MODULES_AUTO_HANDLING description for details.

avail_indepth
avail sub-command in depth search mode.

Default value is 1. It can be changed at installation time with
--disable-avail-indepth option. The MODULES_AVAIL_INDEPTH environment
variable is defined by config sub-command when changing this configuration
option from its default value. The --indepth and --no-indepth command line
switches change the value of this configuration option. See
MODULES_AVAIL_INDEPTH description for details.

avail_output
Content to report in addition to module names on avail sub-command regular
output mode.

Default value is modulepath:alias:dirwsym:sym:tag:key. It can be changed at
installation time with --with-avail-output option. The MODULES_AVAIL_OUTPUT
environment variable is defined by config sub-command when changing this
configuration option from its default value. The --output/-o command line
switches change the value of this configuration option. See
MODULES_AVAIL_OUTPUT description for details.

avail_terse_output
Content to report in addition to module names on avail sub-command terse
output mode.

Default value is modulepath:alias:dirwsym:sym:tag. It can be changed at
installation time with --with-avail-terse-output option. The
MODULES_AVAIL_TERSE_OUTPUT environment variable is defined by config
sub-command when changing this configuration option from its default value.
The --output/-o command line switches change the value of this configuration
option. See MODULES_AVAIL_TERSE_OUTPUT description for details.

collection_pin_version
Register exact modulefile version in collection.

Default value is 0. The MODULES_COLLECTION_PIN_VERSION environment variable
is defined by config sub-command when changing this configuration option
from its default value. See MODULES_COLLECTION_PIN_VERSION description for
details.

collection_pin_tag
Register full tag list applying to modulefiles in collection.

Default value is 0. The MODULES_COLLECTION_PIN_TAG environment variable is
defined by config sub-command when changing this configuration option from
its default value. See MODULES_COLLECTION_PIN_TAG description for details.

collection_target
Collection target which is valid for current system.

This configuration option is unset by default. The MODULES_COLLECTION_TARGET
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_COLLECTION_TARGET
description for details.

color Colored output mode.

Default value is auto. It can be changed at installation time with
--disable-color option. The MODULES_COLOR environment variable is defined by
config sub-command when changing this configuration option from its default
value. The --color command line switches changes the value of this
configuration option. See MODULES_COLOR description for details.

colors Chosen colors to highlight output items.

Default value is
hi=1:db=2:tr=2:se=2:er=91:wa=93:me=95:in=94:mp=1;94:di=94:al=96:va=93:sy=95:de=4:cm=92:aL=100:L=90;47:H=2:F=41:nF=43:S=46:sS=44:kL=30;48;5;109.
It can be changed at installation time with --with-dark-background-colors or
--with-light-background-colors options in conjunction with
--with-terminal-background. The MODULES_COLORS environment variable is
defined by config sub-command when changing this configuration option from
its default value. See MODULES_COLORS description for details.

contact
Modulefile contact address.

Default value is root@localhost. The MODULECONTACT environment variable is
defined by config sub-command when changing this configuration option from
its default value. See MODULECONTACT description for details.

extended_default
Allow partial module version specification.

Default value is 1. It can be changed at installation time with
--disable-extended-default option. The MODULES_EXTENDED_DEFAULT environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_EXTENDED_DEFAULT description for
details.

editor Text editor command to open modulefile with through edit sub-command.

Default value is vi. It can be changed at installation time with
--with-editor option. The MODULES_EDITOR environment variable is defined by
config sub-command when changing this configuration option from its default
value. See MODULES_EDITOR description for details.

extra_siteconfig
Additional site-specific configuration script location. See Site-specific
configuration section for details.

This configuration option is unset by default. The MODULES_SITECONFIG
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_SITECONFIG
description for details.

home Location of Modules package main directory.

Default value is /usr/share/modules. It can be changed at installation time
with --prefix or --with-moduleshome options. The MODULESHOME environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULESHOME description for details.

icase Enable case insensitive match.

Default value is search. It can be changed at installation time with
--with-icase option. The MODULES_ICASE environment variable is defined by
config sub-command when changing this configuration option from its default
value. The --icase/-i command line switches change the value of this
configuration option. See MODULES_ICASE description for details.

ignored_dirs
Directories ignored when looking for modulefiles.

Default value is CVS RCS SCCS .svn .git .SYNC .sos. The value of this option
cannot be altered.

implicit_default
Set an implicit default version for modules.

Default value is 1. It can be changed at installation time with
--disable-implicit-default option. The MODULES_IMPLICIT_DEFAULT environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_IMPLICIT_DEFAULT description for
details.

implicit_requirement
Implicitly define a requirement onto modules specified on module commands in
modulefile.

Default value is 1. It can be changed at installation time with
--disable-implicit-requirement option. The MODULES_IMPLICIT_REQUIREMENT
environment variable is defined by config sub-command when changing this
configuration option from its default value. See
MODULES_IMPLICIT_REQUIREMENT description for details.

list_output
Content to report in addition to module names on list sub-command regular
output mode.

Default value is header:idx:variant:sym:tag:key. It can be changed at
installation time with --with-list-output option. The MODULES_LIST_OUTPUT
environment variable is defined by config sub-command when changing this
configuration option from its default value. The --output/-o command line
switches change the value of this configuration option. See
MODULES_LIST_OUTPUT description for details.

list_terse_output
Content to report in addition to module names on list sub-command terse
output mode.

Default value is header. It can be changed at installation time with
--with-list-terse-output option. The MODULES_LIST_TERSE_OUTPUT environment
variable is defined by config sub-command when changing this configuration
option from its default value. The --output/-o command line switches change
the value of this configuration option. See MODULES_LIST_TERSE_OUTPUT
description for details.

locked_configs
Configuration options that cannot be superseded. All options referred in
locked_configs value are locked, thus their value cannot be altered.

This configuration option is set to an empty value by default. It can be
changed at installation time with --with-locked-configs option. The value
of this option cannot be altered.

mcookie_check
Defines if the Modules magic cookie (i.e., #%Module file signature) should
be checked to determine if a file is a modulefile.

Default value is always. The MODULES_MCOOKIE_CHECK environment variable is
defined by config sub-command when changing this configuration option from
its default value. See MODULES_MCOOKIE_CHECK description for details.

mcookie_version_check
Defines if the version set in the Modules magic cookie used in modulefile
should be checked against the version of modulecmd.tcl to determine if the
modulefile could be evaluated or not.

Default value is 1. It can be changed at installation time with
--disable-mcookie-version-check option. The MODULES_MCOOKIE_VERSION_CHECK
environment variable is defined by config sub-command when changing this
configuration option from its default value. See
MODULES_MCOOKIE_VERSION_CHECK description for details.

ml Define ml command at initialization time.

Default value is 1. It can be changed at installation time with --disable-ml
option. The MODULES_ML environment variable is defined by config sub-command
when changing this configuration option from its default value. See
MODULES_ML description for details.

nearly_forbidden_days
Set the number of days a module should be considered nearly forbidden prior
reaching its expiry date.

Default value is 14. It can be changed at installation time with
--with-nearly-forbidden-days option. The MODULES_NEARLY_FORBIDDEN_DAYS
environment variable is defined by config sub-command when changing this
configuration option from its default value. See
MODULES_NEARLY_FORBIDDEN_DAYS description for details.

pager Text viewer to paginate message output.

Default value is less -eFKRX. It can be changed at installation time with
--with-pager and --with-pager-opts options. The MODULES_PAGER environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_PAGER description for details.

protected_envvars
Prevents any modification of listed environment variables (colon :
separator).

This configuration option is unset by default. The MODULES_PROTECTED_ENVVARS
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_PROTECTED_ENVVARS
description for details.

quarantine_support
Defines if code for quarantine mechanism support should be generated in
module shell function definition.

Default value is 0. It can be changed at installation time with
--enable-quarantine-support option. The MODULES_QUARANTINE_SUPPORT
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_QUARANTINE_SUPPORT
description for details.

rcfile Global run-command file location.

This configuration option is unset by default. The MODULERCFILE environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULERCFILE description for details.

redirect_output
Control whether or not the output of module command should be redirected
from stderr to stdout.

Default value is 1. The MODULES_REDIRECT_OUTPUT environment variable is
defined by config sub-command when changing this configuration option from
its default value. The --redirect and --no-redirect command line switches
change the value of this configuration option. See MODULES_REDIRECT_OUTPUT
description for details.

reset_target_state
Control behavior of reset sub-command. Whether environment should be purged
(__purge__), initial environment (__init__) or a named collection (any other
value) should restored.

Default value is __init__. The MODULES_RESET_TARGET_STATE environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_RESET_TARGET_STATE description
for details.

run_quarantine
Environment variables to indirectly pass to modulecmd.tcl.

This configuration option is set to an empty value by default. It can be
changed at installation time with --with-quarantine-vars option that sets
MODULES_RUN_QUARANTINE. This environment variable is also defined by config
sub-command when changing this configuration option. See
MODULES_RUN_QUARANTINE description for details.

search_match
Module search match style.

Default value is starts_with. It can be changed at installation time with
--with-search-match option. The MODULES_SEARCH_MATCH environment variable is
defined by config sub-command when changing this configuration option from
its default value. The --contains and --starts-with command line switches
change the value of this configuration option. See MODULES_SEARCH_MATCH
description for details.

set_shell_startup
Ensure module command definition by setting shell startup file.

Default value is 0. It can be changed at installation time with
--enable-set-shell-startup option. The MODULES_SET_SHELL_STARTUP environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_SET_SHELL_STARTUP description for
details.

shells_with_ksh_fpath
Ensure module command is defined in ksh when it is started as a sub-shell
from the listed shells.

This configuration option is set to an empty value by default. The
MODULES_SHELLS_WITH_KSH_FPATH environment variable is defined by config
sub-command when changing this configuration option from its default value.
See MODULES_SHELLS_WITH_KSH_FPATH description for details.

silent_shell_debug
Disablement of shell debugging property for the module command. Also defines
if code to silence shell debugging property should be generated in module
shell function definition.

Default value is 0. It can be changed at installation time with
--enable-silent-shell-debug-support option. The MODULES_SILENT_SHELL_DEBUG
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_SILENT_SHELL_DEBUG
description for details.

siteconfig
Primary site-specific configuration script location. See Site-specific
configuration section for details.

Default value is /etc/environment-modules/siteconfig.tcl. It can be changed
at installation time with --prefix or --etcdir options. The value of this
option cannot be altered.

tag_abbrev
Abbreviations to use to report module tags.

Default value is
auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL.
It can be changed at installation time with --with-tag-abbrev option. The
MODULES_TAG_ABBREV environment variable is defined by config sub-command
when changing this configuration option from its default value. See
MODULES_TAG_ABBREV description for details.

tag_color_name
Tags whose name should be colored instead of module name.

This configuration option is set to an empty value by default. It can be
changed at installation time with --with-tag-color-name option. The
MODULES_TAG_COLOR_NAME environment variable is defined by config sub-command
when changing this configuration option from its default value. See
MODULES_TAG_COLOR_NAME description for details.

tcl_ext_lib
Modules Tcl extension library location.

Default value is @libdir@/libtclenvmodules.so. It can be changed at
installation time with --prefix or --libdir options. The value of this
option cannot be altered.

tcl_linter
Command to check syntax of modulefiles with through lint sub-command.

Default value is nagelfar.tcl. It can be changed at installation time with
--with-tcl-linter and --with-tcl-linter-opts options. The MODULES_TCL_LINTER
environment variable is defined by config sub-command when changing this
configuration option from its default value. See MODULES_TCL_LINTER
description for details.

term_background
Terminal background color kind.

Default value is dark. It can be changed at installation time with
--with-terminal-background option. The MODULES_TERM_BACKGROUND environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_TERM_BACKGROUND description for
details.

term_width
Set the width of the output.

Default value is 0. The MODULES_TERM_WIDTH environment variable is defined
by config sub-command when changing this configuration option from its
default value. The --width/-w command line switches change the value of this
configuration option. See MODULES_TERM_WIDTH description for details.

unload_match_order
Unload firstly loaded or lastly loaded module matching request.

Default value is returnlast. It can be changed at installation time with
--with-unload-match-order option. The MODULES_UNLOAD_MATCH_ORDER environment
variable is defined by config sub-command when changing this configuration
option from its default value. See MODULES_UNLOAD_MATCH_ORDER description
for details.

variant_shortcut
Shortcut characters that could be used to specify or report module variants.

This configuration option is set to an empty value by default. It can be
changed at installation time with --with-variant-shortcut option. The
MODULES_VARIANT_SHORTCUT environment variable is defined by config
sub-command when changing this configuration option from its default value.
See MODULES_VARIANT_SHORTCUT description for details.

verbosity
Module command verbosity level.

Default value is normal. It can be changed at installation time with
--with-verbosity option. The MODULES_VERBOSITY environment variable is
defined by config sub-command when changing this configuration option from
its default value. The --debug/-D, --silent/-s, --trace/-T and --verbose/-v
command line switches change the value of this configuration option. See
MODULES_VERBOSITY description for details.

wa_277 Workaround for Tcsh history issue.

Default value is 0. It can be changed at installation time with
--enable-wa-277 option. The MODULES_WA_277 environment variable is defined
by config sub-command when changing this configuration option from its
default value. See MODULES_WA_277 description for details.

display modulefile...
Display information about one or more modulefiles. The display sub-command will
list the full path of the modulefile and the environment changes the modulefile
will make if loaded. (Note: It will not display any environment changes found
within conditional statements.)

The parameter modulefile may also be a symbolic modulefile name or a modulefile
alias. It may also leverage a specific syntax to finely select module version (see
Advanced module version specifiers section below).

edit modulefile
Open modulefile for edition with text editor command designated by the editor
configuration option.

help [modulefile...]
Print the usage of each sub-command. If an argument is given, print the
Module-specific help information for the modulefile.

info-loaded modulefile
Returns the names of currently loaded modules matching passed modulefile. Returns
an empty string if passed modulefile does not match any loaded modules. See
module-info loaded in the modulefile(4) man page for further explanation.

initadd modulefile...
Add modulefile to the shell's initialization file in the user's home directory. The
startup files checked (in order) are:

C Shell
.modules, .cshrc, .csh_variables and .login

TENEX C Shell
.modules, .tcshrc, .cshrc, .csh_variables and .login

Bourne and Korn Shells
.modules, .profile

GNU Bourne Again Shell
.modules, .bash_profile, .bash_login, .profile and .bashrc

Z Shell
.modules, .zshrc, .zshenv and .zlogin

Friendly Interactive Shell
.modules, .config/fish/config.fish

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.

initclear
Clear all of the modulefiles from the shell's initialization files.

initlist
List all of the modulefiles loaded from the shell's initialization file.

initprepend modulefile...
Does the same as initadd but prepends the given modules to the beginning of the
list.

initrm modulefile...
Remove modulefile from the shell's initialization files.

initswitch modulefile1 modulefile2
Switch modulefile1 with modulefile2 in the shell's initialization files.

is-avail modulefile...
Returns a true value if any of the listed modulefiles exists in enabled MODULEPATH.
Returns a false value otherwise. See is-avail in the modulefile(4) man page for
further explanation.

is-loaded [modulefile...]
Returns a true value if any of the listed modulefiles has been loaded or if any
modulefile is loaded in case no argument is provided. Returns a false value
otherwise. See is-loaded in the modulefile(4) man page for further explanation.

is-saved [collection...]
Returns a true value if any of the listed collections exists or if any collection
exists in case no argument is provided. Returns a false value otherwise. See
is-saved in the modulefile(4) man page for further explanation.

is-used [directory...]
Returns a true value if any of the listed directories has been enabled in
MODULEPATH or if any directory is enabled in case no argument is provided. Returns
a false value otherwise. See is-used in the modulefile(4) man page for further
explanation.

keyword [-a] [-j] string
See search.

lint [-a] [modulefile...]
Analyze syntax of one or more modulefiles with the linter command designated by the
tcl_linter configuration option.

If no modulefile is specified, all the modulefiles and modulerc available in
enabled modulepaths are analyzed as well as global and user rc files. Hidden
modulefiles are also analyzed when --all/-a option is set.

When nagelfar.tcl is the selected linter command, a static Tcl syntax analysis is
performed. In addition, syntax of modulefile commands are checked in these files
based on their kind (global/user rc, modulerc or modulefile).

list [-t|-l|-j] [-a] [-o LIST] [-S|-C] [pattern...]
List loaded modules. If a pattern is given, then the loaded modules are filtered to
only list those whose name matches this pattern. It may contain wildcard
characters. pattern is matched in a case insensitive manner by default. If multiple
patterns are given, loaded module has to match at least one of them to be listed.

Module tags applying to the loaded modules are reported along the module name they
are associated to (see Module tags section).

Module variants selected on the loaded modules are reported along the module name
they belong to (see Module variants section).

load [options] modulefile...
Load modulefile into the shell environment.

load command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

Once loaded, the loaded module tag is associated to the loaded module. If module
has been automatically loaded by another module, the auto-loaded tag is associated
instead (see Module tags section).

The --tag option accepts a list of module tags to apply to modulefile once loaded.
If module is already loaded, tags from taglist are added to the list of tags
already applied to this module.

load-any [options] modulefile...
Load into the shell environment one of the modulefile specified. Try to load each
modulefile specified in list from the left to the right until one got loaded or is
found already loaded. Do not complain if modulefile cannot be found but if its
evaluation fails an error is reported.

load-any command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

Once loaded, the loaded module tag is associated to the loaded module. If module
has been automatically loaded by another module, the auto-loaded tag is associated
instead (see Module tags section).

The --tag option accepts a list of module tags to apply to modulefile once loaded.
If module is already loaded, tags from taglist are added to the list of tags
already applied to this module.

mod-to-sh [options] shell modulefile...
Evaluate modulefile and report resulting environment changes as code for shell.

mod-to-sh command accepts the following options:

• --auto|--no-auto

• -f|--force

An attempt to load modulefile is made to get its environment changes. This
evaluation does not change the current shell environment. Like for load
sub-command, no evaluation occurs if modulefile is found loaded in current
environment.

Changes made on environment variable intended for Modules private use (e.g.,
LOADEDMODULES, _LMFILES_, __MODULES_*) are ignored.

Shell could be any shell name supported by modulecmd.tcl.

Produced shell code is returned on the message output channel by modulecmd.tcl.
Thus it is not rendered in current environment by the module shell function.

mod-to-sh automatically set verbosity to the silent mode, to avoid messages to mix
with the produced shell code. Verbosity is not changed if set to the trace mode or
any higher debugging level.

path modulefile
Print path to modulefile.

paths modulefile
Print path of available modulefiles matching argument.

prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
Prepend value to environment variable. The variable is a colon, or delimiter,
separated list. See prepend-path in the modulefile(4) man page for further
explanation.

When prepend-path is called as a module sub-command, the reference counter
variable, which denotes the number of times value has been added to environment
variable, is not updated unless if the --duplicates option is set.

purge [-f]
Unload all loaded modulefiles.

When the --force option is set, also unload sticky modules and modulefiles that are
depended by non-unloadable modules.

refresh
Force a refresh of all non-persistent components of currently loaded modules. This
should be used on derived shells where shell completions, shell aliases or shell
functions need to be reinitialized but the environment variables have already been
set by the currently loaded modules.

Loaded modules are evaluated in refresh mode following their load order. In this
evaluation mode only the complete, set-alias and set-function modulefile commands
will produce environment changes. Other modulefile commands that produce
environment changes (like setenv or append-path) are ignored during a refresh
evaluation as their changes should already be applied.

Only the loaded modules defining non-persistent environment changes are evaluated
in refresh mode. Such loaded modules are listed in the __MODULES_LMREFRESH
environment variable.

reload Unload then load all loaded modulefiles.

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.

remove-path [-d C|--delim C|--delim=C] [--index] variable value...
Remove value from the colon, or delimiter, separated list in environment variable.
See remove-path in the modulefile(4) man page for further explanation.

When remove-path is called as a module sub-command, the reference counter variable,
which denotes the number of times value has been added to environment variable, is
ignored and value is removed whatever the reference counter value set.

reset Restore initial environment, which corresponds to the loaded state after Modules
initialization.

reset sub-command restores the environment definition found in __MODULES_LMINIT
environment variable.

reset behavior can be changed with reset_target_state. This configuration option
is set by default to __init__, which corresponds to the above behavior description.
When set to __purge__, reset performs a purge of the environment. When set to any
other value, reset performs a restore of corresponding name collection.

restore [collection]
Restore the environment state as defined in collection. If collection name is not
specified, then it is assumed to be the default collection if it exists, __init__
special collection otherwise. If collection is a fully qualified path, it is
restored from this location rather than from a file under the user's collection
directory. If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of
this variable is appended to the collection file name to restore.

If collection name is __init__, initial environment state defined in
__MODULES_LMINIT environment variable is restored.

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.

If a module, without a default version explicitly defined, is recorded in a
collection by its bare name: loading this module when restoring the collection will
fail if the configuration option implicit_default is disabled.

rm [--auto|--no-auto] [-f] modulefile...
See unload.

save [collection]
Record the currently set MODULEPATH directory list and the currently loaded
modulefiles in a collection file under the user's collection directory
$HOME/.module. If collection name is not specified, then it is assumed to be the
default collection. If collection is a fully qualified path, it is saved at this
location rather than under the user's collection directory.

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 a loaded modulefile corresponds to the explicitly defined default
module version, the bare module name is recorded. If the configuration option
implicit_default is enabled, the bare module name is also recorded for the implicit
default module version. If MODULES_COLLECTION_PIN_VERSION is set to 1, module
version is always recorded even if it is the default version.

By default, only the module tags specifically set with the --tag option or
resulting from a specific module state (like auto-loaded and keep-loaded tags) are
recorded in collection. If MODULES_COLLECTION_PIN_TAG is set to 1, all tags are
recorded in collection except nearly-forbidden tag.

No collection is recorded and an error is returned if the loaded modulefiles have
unsatisfied constraint corresponding to the prereq and conflict they declare.

savelist [-t|-l|-j] [-a] [-S|-C] [pattern...]
List collections that are currently saved under the user's collection directory. If
MODULES_COLLECTION_TARGET is set, only collections matching the target suffix will
be displayed unless if the --all/-a option is set.

If a pattern is given, then the collections are filtered to only list those whose
name matches this pattern. It may contain wildcard characters. pattern is matched
in a case insensitive manner by default. If multiple patterns are given, collection
has to match at least one of them to be listed.

Stash collections are not listed unless if the --all/-a option is set. Stash
collections can be listed with stashlist sub-command.

saverm [collection]
Delete the collection file under the user's collection directory. If collection
name is not specified, then it is assumed to be the default collection. If
MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable
will be appended to the collection file name.

saveshow [collection]
Display the content of collection. If collection name is not specified, then it is
assumed to be the default collection if it exists, __init__ special collection
otherwise. If collection is a fully qualified path, this location is displayed
rather than a collection file under the user's collection directory. If
MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable
will be appended to the collection file name.

If collection name is __init__, initial environment content defined in
__MODULES_LMINIT environment variable is displayed.

search [-a] [-j] string
Seeks through the module-whatis information of all modulefiles for the specified
string. All module-whatis information matching the string in a case insensitive
manner will be displayed. string may contain wildcard characters.

sh-to-mod shell script [arg...]
Evaluate with shell the designated script with defined arguments to find out the
environment changes it does. Environment prior and after script evaluation are
compared to determine these changes. They are translated into modulefile commands
to output the modulefile content equivalent to the evaluation of shell script.

Changes on environment variables, shell aliases, shell functions, shell completions
and current working directory are tracked.

Changes made on environment variable intended for Modules private use (e.g.,
LOADEDMODULES, _LMFILES_, __MODULES_*) are ignored.

Shell could be specified as a command name or a fully qualified pathname. The
following shells are supported: sh, dash, csh, tcsh, bash, ksh, ksh93, zsh and
fish.

show modulefile...
See display.

source [options] modulefile...
Execute modulefile into the shell environment. Once executed modulefile is not
marked loaded in shell environment which differ from load sub-command.

source command accepts the following options:

• --auto|--no-auto

• -f|--force

If modulefile corresponds to a fully qualified path, this file is executed.
Otherwise modulefile is searched among the available modulefiles.

stash Save current environment in a stash collection then reset to initial environment.

A collection is created only if current environment state differs from initial
environment. Stash collection is named stash-<unix_millis_timestamp> where
<unix_millis_timestamp> is the number of milliseconds between Unix Epoch and when
this command is run.

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this
variable will be appended to the stash collection file name.

stashclear
Remove all stash collection files of current collection_target. If no collection
target is currently set, remove stash collection files without a target suffix.

stashlist [-t|-l|-j]
List all stash collection files of current collection_target. If no collection
target is currently set, list stash collection files without a target suffix.

stashpop [stash]
Restore stash collection then delete corresponding collection file.

stash is either a full stash collection name (i.e., stash-<unix_millis_timestamp>)
or a stash index. Most recent stash collection has index 0, 1 is the one before it.
When no stash is given the latest stash collection is assumed (that is stash index
0).

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this
variable will be appended to the stash collection file name to restore.

stashrm [stash]
Remove stash collection file.

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this
variable will be appended to the stash collection file name to delete.

stashshow [stash]
Display the content of stash collection file.

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this
variable will be appended to the stash collection file name to display.

state [name]
Gets modulecmd.tcl states. Reports the currently set value of passed state name or
all existing states if no name passed.

swap [options] [modulefile1] modulefile2
See switch.

switch [options] [modulefile1] modulefile2
Switch loaded modulefile1 with modulefile2. If modulefile1 is not specified, then
it is assumed to be the currently loaded module with the same root name as
modulefile2.

switch command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

The --tag option accepts a list of module tags to apply to modulefile once loaded.
If module is already loaded, tags from taglist are added to the list of tags
already applied to this module.

test modulefile...
Execute and display results of the Module-specific tests for the modulefile.

try-add [options] modulefile...
See try-load.

try-load [options] modulefile...
Like load sub-command, load modulefile into the shell environment, but do not
complain if modulefile cannot be found. If modulefile is found but its evaluation
fails, error is still reported.

try-load command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

Once loaded, the loaded module tag is associated to the loaded module. If module
has been automatically loaded by another module, the auto-loaded tag is associated
instead (see Module tags section).

The --tag option accepts a list of module tags to apply to modulefile once loaded.
If module is already loaded, tags from taglist are added to the list of tags
already applied to this module.

unload [--auto|--no-auto] [-f] modulefile...
Remove modulefile from the shell environment.

unuse directory...
Remove one or more directories from the MODULEPATH environment variable.

If module unuse is called during a modulefile evaluation, the reference counter
environment variable __MODULES_SHARE_MODULEPATH, which denotes the number of times
directory has been enabled, is checked and directory is removed only if its
relative counter is equal to 1 or not defined. Otherwise directory is kept and
reference counter is decreased by 1. When module unuse is called from the
command-line or within an initialization modulefile script directory is removed
whatever the reference counter value set.

If directory corresponds to the concatenation of multiple paths separated by colon
character, each path is treated separately.

use [-a|--append] directory...
Prepend one or more directories to the MODULEPATH environment variable. The
--append flag will append the directory to MODULEPATH.

When directory is already defined in MODULEPATH, it is not added again or moved at
the end or at the beginning of the environment variable.

If module use is called during a modulefile evaluation, the reference counter
environment variable __MODULES_SHARE_MODULEPATH is also set to increase the number
of times directory has been added to MODULEPATH. Reference counter is not updated
when module use is called from the command-line or within an initialization
modulefile script.

A directory that does not exist yet can be specified as argument and then be added
to MODULEPATH.

whatis [-a] [-j] [modulefile...]
Display the information set up by the module-whatis commands inside the specified
modulefiles. These specified modulefiles may be expressed using wildcard
characters. If no modulefile is specified, all module-whatis lines will be shown.

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.

Advanced module version specifiers
When the advanced module version specifiers mechanism is enabled (see
MODULES_ADVANCED_VERSION_SPEC), the specification of modulefile passed on Modules
sub-commands changes. After the module name a version constraint and variants may be
added.

Version specifiers
After the module name a version constraint prefixed by the @ character may be added. It
could be directly appended to the module name or separated from it with a space character.

Constraints can be expressed to refine the selection of module version to:

• a single version with the @version syntax, for instance foo@1.2.3 syntax will select
module foo/1.2.3

• a list of versions with the @version1,version2,... syntax, for instance foo@1.2.3,1.10
will match modules foo/1.2.3 and foo/1.10

• a range of versions with the @version1:, @:version2 and @version1:version2 syntaxes, for
instance foo@1.2: will select all versions of module foo greater than or equal to 1.2,
foo@:1.3 will select all versions less than or equal to 1.3 and foo@1.2:1.3 matches all
versions between 1.2 and 1.3 including 1.2 and 1.3 versions

Advanced specification of single version or list of versions may benefit from the
activation of the extended default mechanism (see MODULES_EXTENDED_DEFAULT) to use an
abbreviated notation like @1 to refer to more precise version numbers like 1.2.3. Range of
versions on its side natively handles abbreviated versions.

In order to be specified in a range of versions or compared to a range of versions, the
version major element should corresponds to a number. For instance 10a, 1.2.3, 1.foo are
versions valid for range comparison whereas default or foo.2 versions are invalid for
range comparison.

Range of versions can be specified in version list, for instance foo@:1.2,1.4:1.6,1.8:.
Such specification helps to exclude specific versions, like versions 1.3 and 1.7 in
previous example.

If the implicit default mechanism is also enabled (see MODULES_IMPLICIT_DEFAULT), a
default and latest symbolic versions are automatically defined for each module name (also
at each directory level for deep modulefiles). These automatic version symbols are defined
unless a symbolic version, alias, or regular module version already exists for these
default or latest version names. Using the mod@latest (or mod/latest) syntax ensures
highest available version will be selected.

The symbolic version loaded may be used over loaded module name to designate the loaded
version of the module with associated selected variants. This version symbol should be
specified using the @ prefix notation (e.g., foo@loaded). An error is returned if no
version of designated module is currently loaded.

Variants
After the module name, variants can be specified. Module variants are alternative
evaluation of the same modulefile. A variant is specified by associating a value to its
name. This specification is then transmitted to the evaluating modulefile which
instantiates the variant in the ModuleVariant array variable when reaching the variant
modulefile command declaring this variant.

Variant can be specified with the name=value syntax where name is the declared variant
name and value, the value this variant is set to when evaluating the modulefile.

Boolean variants can be specified with the +name syntax to set this variant on and with
the -name or ~name syntaxes to set this variant off. The -name syntax is not supported on
ml(1) command as the minus sign already means to unload designated module. The ~name and
+name syntaxes could also be defined appended to another specification word (e.g., the
module name, version or another variant specification), whereas -name syntax must be the
start of a new specification word.

Boolean variants may also be specified with the name=value syntax. value should be set to
1, true, t, yes, y or on to enable the variant or it should be set to 0, false, f, no, n
or off to disable the variant.

Shortcuts may be used to abbreviate variant specification. The variant_shortcut
configuration option associates shortcut character to variant name. With a shortcut
defined, variant could be specified with the <shortcut>value syntax. For instance if
character % is set as a shortcut for variant foo, the %value syntax is equivalent to the
foo=value syntax.

Specific characters used in variant specification syntax cannot be used as part of the
name of a module. These specific characters are +, ~, = and all characters set as variant
shortcut. Exception is made for + character which could be set one or several consecutive
times at the end of module name (e.g., name+ or name++).

Module tags
Module tags are piece of information that can be associated to individual modulefiles.
Tags could be purely informational or may lead to specific behaviors.

Module tags may be inherited from the module state set by a modulefile command or
consequence of a module action. The inherited tags are:

• auto-loaded: module has been automatically loaded by another module

• forbidden: module has been set forbidden through the use of the module-forbid command
and thus this module cannot be loaded.

• hidden: module has been set hidden through the use of the module-hide command and thus
it is not reported by default among the result of an avail sub-command.

• hidden-loaded: module has been set hidden once loaded through the use of the module-hide
--hidden-loaded command thus it is not reported bu default among the result of a list
sub-command.

• loaded: module is currently loaded

• nearly-forbidden: module will soon be forbidden, which has been set through the use of
the module-forbid command. Thus this module will soon not be able to load anymore.

Tags may also be associated to modules by using the module-tag modulefile command. Among
tags that could be set this way, some have a special meaning:

• keep-loaded: auto-loaded module cannot be automatically unloaded. This tag is also set
through the use of the always-load command.

• sticky: module once loaded cannot be unloaded unless forced or reloaded (see Sticky
modules section)

• super-sticky: module once loaded cannot be unloaded unless reloaded, module cannot be
unloaded even if forced (see Sticky modules section)

The --tag option helps to apply additional tags to modules. It is available on load,
load-any, switch and try-load sub-commands and on always-load, depends-on, module, prereq,
prereq-all and prereq-any modulefile commands. In case the designated module is already
loaded, the additional tags are added to the list of tags already applied to this module.

Module tags are reported along the module they are associated to on avail and list
sub-command results and also when module's loading, unloading, refreshing or tagging
evaluation is mentioned. Tags could be reported either:

• along the module name, all tags set within angle brackets, each tag separated from the
others with a colon character (e.g., foo/1.2 <tag1:tag2>).

• graphically rendered over the module name for each tag associated to a Select Graphic
Rendition (SGR) code in the color palette (see MODULES_COLORS)

When an abbreviated string is associated to a tag name (see MODULES_TAG_ABBREV), this
abbreviation is used to report tag along the module name or the tag is graphically
rendered over the module name if a SGR code is associated with tag abbreviation in the
color palette. With an abbreviation set, the SGR code associated to the tag full name is
ignored thus an SGR code should be associated to the abbreviation to get a graphical
rendering of tag. If the abbreviation associated to a tag corresponds to the empty string,
tag is not reported.

Graphical rendering is made over the tag name or abbreviation instead of over the module
name for each tag name or abbreviation set in the MODULES_TAG_COLOR_NAME environment
variable.

When several tags have to be rendered graphically over the same module name, each tag is
rendered over a sub-part of the module name. In case more tags need to be rendered than
the total number of characters in the module name, the remaining tags are graphically
rendered over the tag name instead of over the module name.

When the JSON output mode is enabled (with --json), tags are reported by their name under
the tags attribute. Tag abbreviation and color rendering do not apply on JSON output.

Module tags cannot be used in search query to designate a modulefile.

Sticky modules
Modules are said sticky when they cannot be unloaded (they stick to the loaded
environment). Two kind of stickiness can be distinguished:

• sticky module: cannot be unloaded unless if the unload is forced or if the module is
reloaded after being unloaded or if restoring a collection.

• super-sticky module: cannot be unloaded unless if the module is reloaded after being
unloaded; super-sticky modules cannot be unloaded even if the unload is forced.

Modules are designated sticky by associating them the sticky or the super-sticky module
tag with the module-tag modulefile command.

When stickiness is defined over the generic module name (and not over a specific module
version, a version list or a version range), sticky or super-sticky module can be swapped
by another version of module. For instance if the sticky tag is defined over foo module,
loaded module foo/1.2 can be swapped by foo/2.0. Such stickiness definition means one
version of module should stay loaded whatever version it is.

When restoring a collection or resetting to the initial environment, sticky modules are
unloaded to ensure restore or reset sub-commands fully set the environment in target
collection or initial state. Super-sticky modules still cannot be unloaded with restore
and reset sub-commands.

Module variants
Module variants are alternative evaluation of the same modulefile. A variant is specified
by associating a value to its name when designating module. Variant specification relies
on the Advanced module version specifiers mechanism.

Once specified, variant's value is transmitted to the evaluating modulefile which
instantiates the variant in the ModuleVariant array variable when reaching the variant
modulefile command declaring this variant. For instance the module load foo/1.2
bar=value1 command leads to the evaluation of foo/1.2 modulefile with bar=value1 variant
specification. When reaching the variant bar value1 value2 value3 command in modulefile
during its evaluation, the ModuleVariant(bar) array element is set to the value1 string.

Once variants are instantiated, modulefile's code could check the variant values to adapt
the evaluation and define for instance different module requirements or produce different
environment variable setup.

Variants are interpreted in contexts where modulefiles are evaluated. Thus the variants
specified on module designation are ignored by the avail, whatis, is-avail, path or paths
sub-commands.

When modulefile is evaluated a value should be specified for each variant this modulefile
declares. When reaching the variant modulefile command declaring a variant, an error is
raised if no value is specified for this variant and if no default value is declared.
Specified variant value should match a value from the declared accepted value list if such
list is defined otherwise an error is raised. Additionally if a variant is specified but
does not correspond to a variant declared in modulefile, an error is raised.

Module variants are reported along the module they are associated to on list sub-command
results. Variants are reported within curly braces next to module name, each variant
definition separated from the others with a colon character (e.g.,
foo/1.2{variant1=value:+variant2}). Boolean variants are reported with the +name or -name
syntaxes. When a shortcut character is defined for a variant (see
MODULES_VARIANT_SHORTCUT) it is reported with the <shortcut>value syntax. For instance if
% character is defined as a shortcut for variant1: foo/1.2{%value:+variant2}.

When the JSON output mode is enabled (with --json), variants are reported under the
variants JSON object as name/value pairs. Values of Boolean variant are set as JSON
Boolean. Other values are set as JSON strings. Variant shortcut and color rendering do
not apply on JSON output.

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.

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.

$ module list
Currently Loaded Modulefiles:
1) foo/1.2 2) bar/2.0 3) qux/3.5
$ module save foo
$ cat $HOME/.module/foo
module use --append /path/to/modulefiles
module load foo
module load bar/2.0
module load qux/3.5

The content of a collection can also be displayed with the saveshow sub-command. Note that
in the above example, bare module name is recorded for foo modulefile as loaded version is
the implicit default. Loaded version recording can be enforced by enabling
collection_pin_version configuration option.

$ module config collection_pin_version 1
$ module save foo
$ module saveshow foo
-------------------------------------------------------------------
/home/user/.module/foo:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0
module load qux/3.5

-------------------------------------------------------------------

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.

$ module list
Currently Loaded Modulefiles:
1) foo/1.2 2) bar/2.1 3) qux/3.5
$ module restore foo
Unloading qux/3.5
Unloading bar/2.1
Loading bar/2.0
Loading qux/3.5
$ module list
Currently Loaded Modulefiles:
1) foo/1.2 2) bar/2.0 3) qux/3.5

In the above example, second and third module loaded are changed. First loaded module is
not changed or reloaded as it is the same module between current environment and
collection. As second loaded module was different, this module and all those loaded
afterward are unloaded to then load the sequence described by collection. As a result,
third loaded module is reloaded, even if is was the same module between current
environment and collection.

Existing collections can be listed with savelist sub-command. They can be deleted with
saverm sub-command.

$ module savelist
Named collection list:
1) default 2) foo
$ module saverm default
$ module savelist
Named collection list:
1) foo

When no argument is provided to save, restore, saveshow or saverm sub-commands, the
default collection is assumed.

Collection can also be specified as a full pathname:

$ module save /path/to/collections/bar
$ module saveshow /path/to/collections/bar
-------------------------------------------------------------------
/path/to/collections/bar:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0
module load qux/3.5

-------------------------------------------------------------------

Initial environment
Initial environment state, which corresponds to modulepaths enabled and modules loaded
during Modules initialization, is referred as the __init__ collection. This collection is
virtual as its content is stored in the __MODULES_LMINIT and not in a file. It can be
displayed with saveshow and restored with restore sub-command.

$ module saveshow __init__
-------------------------------------------------------------------
initial environment:

module use --append /path/to/modulefiles
module load foo/1.2

-------------------------------------------------------------------

If the default collection does not exist, saveshow and restore sub-commands assume
__init__ collection when no argument provided to them.

$ module list
Currently Loaded Modulefiles:
1) foo/1.2 2) bar/2.1 3) qux/3.5
$ module savelist
Named collection list:
1) foo
$ module restore
Unloading qux/3.5
Unloading bar/2.1

Initial environment state can also be restored with the reset sub-command. This
sub-command behavior can be changed with reset_target_state configuration option to choose
to just purge loaded modules or to restore a specific collection.

Collection targets
A collection target can be defined for current environment session with the
collection_target configuration option. When set, available collections are reduced to
those suffixed with target name. Which means restore, saveshow, savelist and saverm only
find collections matching currently set target.

$ module savelist
Named collection list:
1) foo
$ module config collection_target mytarget
$ module savelist
No named collection (for target "mytarget").
$ module restore foo
ERROR: Collection foo (for target "mytarget") cannot be found

When saving a new collection, generated file is suffixed with currently set target name.

$ module save bar
$ module savelist
Named collection list (for target "mytarget"):
1) bar
$ ls $HOME/.module
bar.mytarget foo

Collection targets help to distinguish contexts and make collection reachable only from
the context they have been made for. For instance the same user account may be used to
access different OSes or machine architectures. With a target set, users are ensured to
only access collections built for the context they are currently connected to. See also
MODULES_COLLECTION_TARGET section.

Stash collections
Current user environment can be stashed with stash sub-command. When this sub-command is
called, current module environment is saved in a stash collection then initial environment
is restored.

$ module list
Currently Loaded Modulefiles:
1) foo/1.2 2) qux/4.2
$ module stash
Unloading qux/4.2

Specific sub-commands are available to handle stash collections: stashpop, stashlist,
stashshow, stashrm and stashclear. A stash collection is restored with stashpop which also
deletes the collection once restored.

$ module stashlist
Stash collection list (for target "mytarget"):
0) stash-1667669750191
$ module stashpop
Loading qux/4.2
$ module stashlist
No stash collection (for target "mytarget").

Stash collections have same format and are saved in the same location than other
collections. Collection target also applies to stash collection. Creation timestamp is
saved in stash collection name.

Stash collection can be designated by their full collection name (i.e.,
stash-<creation_timestamp>) or a stash index. Most recent stash collection has index 0, 1
is the one before it. When no argument is provided on stash sub-commands, the latest stash
collection is assumed (that is stash index 0).

$ module stashlist
Stash collection list (for target "mytarget"):
0) stash-1667669750783 1) stash-1667669750253
$ module stashshow 1
-------------------------------------------------------------------
/home/user/.module/stash-1667669750253.mytarget:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0

-------------------------------------------------------------------

Site-specific configuration
Siteconfig, the site-specific configuration script, is a way to extend modulecmd.tcl.
Siteconfig is a Tcl script. Its location is /etc/environment-modules/siteconfig.tcl.

When modulecmd.tcl is invoked it sources siteconfig script if it exists. Any global
variable or procedure of modulecmd.tcl can be redefined in siteconfig.

An additional siteconfig script may be specified through the extra_siteconfig
configuration option. The MODULES_SITECONFIG environment variable is defined by config
sub-command when setting extra_siteconfig. If it exists the extra siteconfig is sourced by
modulecmd.tcl right after main siteconfig script.

Hooks
Siteconfig relies on the ability of the Tcl language to overwrite previously defined
variables and procedures. Sites may deploy their own Tcl code in siteconfig to adapt
modulecmd.tcl to their specific needs. The trace Tcl command may especially be used to
define hooks that are run when entering or leaving a given procedure, or when a variable
is read or written. See trace(n) man page for detailed information. The following example
setup a procedure that is executed before each modulefile evaluation:

proc beforeEval {cmdstring code result op} {
# code to run right before each modulefile evaluation
}
trace add execution execute-modulefile enter beforeEval

Another possibility is to override the definition of an existing procedure by first
renaming its original version then creating a new procedure that will add specific code
and rely on the renamed original procedure for the rest. See rename(n) man page for
details. As an example, the following code adds a new query option to the module-info
modulefile command:

rename module-info __module-info
proc module-info {what {more {}}} {
switch -- $what {
platform { return myhost-$::tcl_platform(machine) }
default { return [__module-info $what $more] }
}
}

Siteconfig hook variables
Some Tcl variables can be defined in siteconfig script with special hook meaning. The
following variables are recognized:

modulefile_extra_vars
List of variable names and associated values to setup in modulefile evaluation
context. These variables can be accessed when modulefile is executed. In case code
in a modulefile changes the value of such variable, its value is reset to the one
defined in modulefile_extra_vars prior the evaluation of the next modulefile.

set modulefile_extra_vars {myvar 1 othervar {some text}}

In the above siteconfig example, modulefile_extra_vars sets the myvar and othervar
variables in the modulefile evaluation context with respectively 1 and some text as
value.

modulefile_extra_cmds
List of command and associated local procedure to setup in modulefile evaluation
context. These commands can be called from the modulefile to execute associated
procedure. In case a modulefile changes the definition of such command, its
definition is bound again on the procedure defined in modulefile_extra_cmds prior
the evaluation of the next modulefile.

proc mycmd {} {
# Tcl code
}
proc anotherproc {args} {
# Tcl code
}
set modulefile_extra_cmds {mycmd mycmd othercmd anotherproc}

In the above siteconfig example, modulefile_extra_cmds sets the mycmd and othercmd
commands in the modulefile evaluation context and bind them respectively to the
mycmd and anotherproc procedures defined in siteconfig script.

modulerc_extra_vars
List of variable names and associated values to setup in modulerc evaluation
context. These variables can be accessed when modulerc is executed. In case code in
a modulerc changes the value of such variable, its value is reset to the one
defined in modulerc_extra_vars prior the evaluation of the next modulerc.

set modulerc_extra_vars {myvar 1 othervar {some text}}

In the above siteconfig example, modulerc_extra_vars sets the myvar and othervar
variables in the modulerc evaluation context with respectively 1 and some text as
value.

modulerc_extra_cmds
List of command and associated local procedure to setup in modulerc evaluation
context. These commands can be called from the modulerc to execute associated
procedure. In case a modulerc changes the definition of such command, its
definition is bound again on the procedure defined in modulerc_extra_cmds prior the
evaluation of the next modulerc.

proc mycmd {} {
# Tcl code
}
proc anotherproc {args} {
# Tcl code
}
set modulerc_extra_cmds {mycmd mycmd othercmd anotherproc}

In the above siteconfig example, modulerc_extra_cmds sets the mycmd and othercmd
commands in the modulerc evaluation context and bind them respectively to the mycmd
and anotherproc procedures defined in siteconfig script.

EXIT STATUS

       The module command exits with 0 if its execution succeed.  Otherwise 1 is returned.

ENVIRONMENT

__MODULES_AUTOINIT_INPROGRESS
If set to 1, the autoinit sub-command process is skipped.

This environment variable is set to 1 by the autoinit sub-command after checking it
is not set. It ensures no nested initialization of Modules occur. At the end of the
processing of the autoinit sub-command, __MODULES_AUTOINIT_INPROGRESS is unset.

__MODULES_LMALTNAME
A colon separated list of the alternative names set through module-version and
module-alias statements corresponding to all loaded modulefiles. Each element in
this list starts by the name of the loaded modulefile followed by all alternative
names resolving to it. The loaded modulefile and its alternative names are
separated by the ampersand character.

Each alternative name stored in __MODULES_LMALTNAME is prefixed by the al| string
if it corresponds to a module alias or prefixed by the as| string if it corresponds
to an automatic version symbol. These prefixes help to distinguish the different
kind of alternative name.

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.

Starting version 4.7 of Modules, __MODULES_LMALTNAME is also used on list
sub-command to report the symbolic versions associated with the loaded modules.

__MODULES_LMCONFLICT
A colon separated list of the conflict statements defined by all loaded
modulefiles. Each element in this list starts by the name of the loaded modulefile
declaring the conflict followed by the name of all modulefiles it declares a
conflict with. These loaded modulefiles and conflicting modulefile names are
separated by the ampersand character.

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.

__MODULES_LMINIT
A colon separated list describing the modulepaths that have been enabled and the
modulefiles that have been loaded with their tags during Modules initialization.
Each element in this list corresponds to a collection definition line.

This environment variable is intended for module command internal use to get
knowledge of the initial loaded state after initialization.

This initial environment state can then be restored with reset sub-command. It can
also be restored with restore sub-command when __init__ collection name is
specified or when no collection name is specified and no default collection exists.

The content of the initial environment can be displayed with saveshow sub-command
when __init__ collection name is specified or when no collection name is specified
and no default collection exists.

__MODULES_LMPREREQ
A colon separated list of the prereq statements defined by all loaded modulefiles.
Each element in this list starts by the name of the loaded modulefile declaring the
pre-requirement followed by the name of all modulefiles it declares a prereq with.
These loaded modulefiles and pre-required modulefile names are separated by the
ampersand character. When a prereq statement is composed of multiple modulefiles,
these modulefile names are separated by the pipe character.

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.

__MODULES_LMREFRESH
A colon separated list of the loaded modules that are qualified for refresh
evaluation. Loaded modules listed in this variable are those defining volatile
environment changes like shell completion, alias and function.

__MODULES_LMSOURCESH
A colon separated list of the source-sh statements defined by all loaded
modulefiles. Each element in this list starts by the name of the loaded modulefile
declaring the environment changes made by the evaluation of source-sh scripts. This
name is followed by each source-sh statement call and corresponding result achieved
in modulefile. The loaded modulefile name and each source-sh statement description
are separated by the ampersand character. The source-sh statement call and each
resulting modulefile command (corresponding to the environment changes done by
sourced script) are separated by the pipe character.

This environment variable is intended for module command internal use to get
knowledge of the modulefile commands applied for each source-sh command when
loading the modulefile. In order to reverse these modulefile commands when
modulefile is unloaded to undo the environment changes.

__MODULES_LMEXTRATAG
A colon separated list of the tags corresponding to all loaded modulefiles that
have been set through the --tag option. Each element in this list starts by the
name of the loaded modulefile followed by all explicitly set tags applying to it.
The loaded modulefile and its tags are separated by the ampersand character.

This environment variable is intended for module command internal use to
distinguish from all tags those that have been specifically set with --tag option.

__MODULES_LMTAG
A colon separated list of the tags corresponding to all loaded modulefiles that
have been set through module-tag statements or from other modulefile statements
like module-forbid (that may apply the nearly-forbidden tag in specific situation)
(see Module tags section). Each element in this list starts by the name of the
loaded modulefile followed by all tags applying to it. The loaded modulefile and
its tags are separated by the ampersand character.

This environment variable is intended for module command internal use to get
knowledge of the tags applying to loaded modulefiles in order to report these tags
on list sub-command output or to apply specific behavior when unloading modulefile.

__MODULES_LMVARIANT
A colon separated list of the variant instantiated through variant statements by
all loaded modulefiles (see Module variants section). Each element in this list
starts by the name of the loaded modulefile followed by all the variant definitions
set during the load of this module. The loaded modulefile and each of its variant
definition are separated by the ampersand character. Each variant definition starts
with the variant name, followed by the variant value set, then a flag to know if
variant is of the Boolean type and last element in this definition is a flag to
know if the chosen value is the default one for this variant and if it has been
automatically set or not. These four elements composing the variant definition are
separated by the pipe character.

This environment variable is intended for module command internal use to get
knowledge of the variant value defined by the loaded modulefiles in order to keep
environment consistent when requirements are set over a specific variant value or
just to report these variant values when listing loaded modules.

__MODULES_PUSHENV_<VAR>
Stack of saved values for <VAR> environment variable. A colon-separated list
containing pairs of elements. A pair is formed by a loaded module name followed by
the value set to <VAR> in this module with pushenv command. An ampersand character
separates the two parts of the pair.

First element in list corresponds to the lastly set value of <VAR>. If a value
were set to <VAR> prior the first evaluated pushenv command, this value is
associated to an empty module name to record it as a pair element in
__MODULES_PUSHENV_<VAR>.

__MODULES_QUAR_<VAR>
Value of environment variable <VAR> passed to modulecmd.tcl in order to restore
<VAR> to this value once started.

__MODULES_QUARANTINE_SET
If set to 1, restore the environment variables set on hold by the quarantine
mechanism when starting modulecmd.tcl script. This variable is automatically
defined by Modules shell initialization scripts or module shell function when they
apply the quarantine mechanism. (see MODULES_QUARANTINE_SUPPORT).

__MODULES_SHARE_<VAR>
Reference counter variable for path-like variable <VAR>. A colon separated list
containing pairs of elements. A pair is formed by a path element followed its usage
counter which represents the number of times this path has been enabled in variable
<VAR>. A colon separates the two parts of the pair.

An element of a path-like variable is added to the reference counter variable as
soon as it is added more than one time. When an element of a path-like variable is
not found in the reference counter variable, it means this element has only be
added once to the path-like variable.

When an empty string is added as an element in the path-like variable, it is added
to the reference counter variable even if added only once to distinguish between an
empty path-like variable and a path-like variable containing an empty string as
single element.

_LMFILES_
A colon separated list of the full pathname for all loaded modulefiles.

This environment variable is generated by module command and should not be modified
externally.

LOADEDMODULES
A colon separated list of all loaded modulefiles.

This environment variable is generated by module command and should not be modified
externally.

MODULECONTACT
Email address to contact in case any issue occurs during the interpretation of
modulefiles.

This environment variable value supersedes the default value set in the contact
configuration option. It can be defined with the config sub-command.

MODULEPATH
The path that the module command searches when looking for modulefiles. Typically,
it is set to the main modulefiles directory, /usr/share/modules/modulefiles, by the
initialization script. MODULEPATH can be set using module use or by the module
initialization script to search group or personal modulefile directories before or
after the main modulefile directory.

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.

MODULERCFILE
The location of a global run-command file containing modulefile specific setup. See
Modulecmd startup section for detailed information.

This environment variable value supersedes the default value set in the rcfile
configuration option. It can be defined with the config sub-command.

MODULES_ADVANCED_VERSION_SPEC
If set to 1, enable advanced module version specifiers (see Advanced module version
specifiers section). If set to 0, disable advanced module version specifiers.

This environment variable value supersedes the default value set in the
advanced_version_spec configuration option. It can be defined with the config
sub-command.

MODULES_AUTO_HANDLING
If set to 1, enable automated module handling mode. If set to 0 disable automated
module handling mode. Other values are ignored.

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 and if they are not tagged keep-loaded.

• 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.

This environment variable value supersedes the default value set on the
auto_handling configuration option. It can be defined with the config sub-command.
The --auto and --no-auto command line switches override this environment variable.

MODULES_AVAIL_INDEPTH
If set to 1, enable in depth search results for avail sub-command. If set to 0
disable avail sub-command in depth mode. Other values are ignored.

When in depth mode is enabled, modulefiles and directories contained in directories
matching search query are also included in search results. When disabled these
modulefiles and directories contained in matching directories are excluded.

This environment variable value supersedes the default value set in the
avail_indepth configuration option. It can be defined with the config sub-command.
The --indepth and --no-indepth command line switches override this environment
variable.

MODULES_AVAIL_OUTPUT
A colon separated list of the elements to report in addition to module names on
avail sub-command regular output mode.

Accepted elements that can be set in value list are:

• alias: module aliases.

• dirwsym: directories associated with symbolic versions.

• key: legend appended at the end of the output to explain it.

• modulepath: modulepath names set as header prior the list of available modules
found in them.

• sym: symbolic versions associated with available modules.

• tag: tags associated with available modules.

The order of the elements in the list does not matter. Module names are the only
content reported when LIST is set to an empty value.

In case the modulepath element is missing from value list, the available modules
from global/user rc and all enabled modulepaths are reported as a single list.

This environment variable value supersedes the default value set in the
avail_output configuration option. It can be defined with the config sub-command.
The --output/-o command line switches override this environment variable.

MODULES_AVAIL_TERSE_OUTPUT
A colon separated list of the elements to report in addition to module names on
avail sub-command terse output mode.

See MODULES_AVAIL_OUTPUT to get the accepted elements that can be set in value
list.

The order of the elements in the list does not matter. Module names are the only
content reported when LIST is set to an empty value.

This environment variable value supersedes the default value set in the
avail_terse_output configuration option. It can be defined with the config
sub-command. The --output/-o command line switches override this environment
variable.

MODULES_CMD
The location of the active module command script.

This environment variable is generated by module command and should not be modified
externally.

MODULES_COLLECTION_PIN_VERSION
If set to 1, register exact version number of modulefiles when saving a collection.
Otherwise modulefile version number is omitted if it corresponds to the explicitly
set default version and also to the implicit default when the configuration option
implicit_default is enabled.

This environment variable value supersedes the default value set in the
collection_pin_version configuration option. It can be defined with the config
sub-command.

MODULES_COLLECTION_PIN_TAG
If set to 1, register all tags applying to modulefiles when saving a collection.
Otherwise only the extra tags set through the --tag option and tags resulting from
specific module states (like auto-loaded and keep-loaded tags) are recorded in
collection. Note that the nearly-forbidden tag due to its temporal meaning is not
saved in collection even when this configuration option is enabled.

This environment variable value supersedes the default value set in the
collection_pin_tag configuration option. It can be defined with the config
sub-command.

MODULES_COLLECTION_TARGET
The collection target that determines what collections are valid thus reachable on
the current system.

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, saverm, stash, stashpop, stashlist, stashshow, and
stashrm sub-commands. Saving a collection registers the target footprint by
suffixing the collection filename with .$MODULES_COLLECTION_TARGET. The 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 value supersedes the default value set in the
collection_target configuration option. It can be defined with the config
sub-command.

MODULES_COLOR
Defines if output should be colored or not. Accepted values are never, auto and
always.

When color mode is set to auto, output is colored only if the standard error output
channel is attached to a terminal.

This environment variable value supersedes the default value set in the color
configuration option. It can be defined with the config sub-command. The --color
command line switch overrides this environment variable.

NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables are also honored to
define color mode. The never mode is set if NO_COLOR is defined (regardless of its
value) or if CLICOLOR equals to 0. If CLICOLOR is set to another value, it
corresponds to the auto mode. The always mode is set if CLICOLOR_FORCE is set to a
value different than 0. NO_COLOR variable prevails over CLICOLOR and
CLICOLOR_FORCE. Color mode set with these three variables is superseded by mode set
with MODULES_COLOR environment variable or with --color command line switch..

MODULES_COLORS
Specifies the colors and other attributes used to highlight various parts of the
output. Its value is a colon-separated list of output items associated to a Select
Graphic Rendition (SGR) code. It follows the same syntax than LS_COLORS.

Output items are designated by keys. Items able to be colorized are: highlighted
element (hi), debug information (db), trace information (tr), tag separator (se);
Error (er), warning (wa), module error (me) and info (in) message prefixes;
Modulepath (mp), directory (di), module alias (al), module variant (va), module
symbolic version (sy), module default version (de) and modulefile command (cm).

Module tags can also be colorized. The key to set in the color palette to get a
graphical rendering of a tag is the tag name or the tag abbreviation if one is
defined for tag. The SGR code applied to a tag name is ignored if an abbreviation
is set for this tag thus the SGR code should be defined for this abbreviation to
get a graphical rendering. Each basic tag has by default a key set in the color
palette, based on its abbreviated string: auto-loaded (aL), forbidden (F), hidden
and hidden-loaded (H), loaded (L), nearly-forbidden (nF), sticky (S), super-sticky
(sS) and keep-loaded (kL).

See the Select Graphic Rendition (SGR) section in the documentation of the text
terminal that is used for permitted values and their meaning as character
attributes. These substring values are integers in decimal representation and can
be concatenated with semicolons. Modules takes care of assembling the result into a
complete SGR sequence (\33[...m). Common values to concatenate include 1 for bold,
4 for underline, 30 to 37 for foreground colors and 90 to 97 for 16-color mode
foreground colors. See also
https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
for a complete SGR code reference.

No graphical rendition will be applied to an output item that could normally be
colored but which is not defined in the color set. Thus if MODULES_COLORS is
defined empty, no output will be colored at all.

This environment variable value supersedes the default value set in the colors
configuration option. It can be defined with the config sub-command.

MODULES_EDITOR
Text editor command name or path for use to open modulefile through the edit
sub-command.

This environment variable value supersedes the default value set in the editor
configuration option. It can be defined with the config sub-command.

Text editor could also be defined through the VISUAL or EDITOR environment
variables. These environment variables are overridden by MODULES_EDITOR.

MODULES_EXTENDED_DEFAULT
If set to 1, a specified module version is matched against starting portion of
existing module versions, where portion is a substring separated from the rest of
the version string by a . character. For example specified modules mod/1 and
mod/1.2 will match existing modulefile mod/1.2.3.

In case multiple modulefiles match the specified module version and a single module
has to be selected, the explicitly set default version is returned if it is part of
matching modulefiles. Otherwise the implicit default among matching modulefiles is
returned if defined (see MODULES_IMPLICIT_DEFAULT section)

This environment variable value supersedes the default value set in the
extended_default configuration option. It can be defined with the config
sub-command.

MODULES_FAMILY_<NAME>
Module name minus version that provides for the name family in currently loaded
environment. This environment variable is defined through the use of the family
modulefile command.

For instance if loading modulefile foo/1.0 defines being member of the bar family,
the MODULES_FAMILY_BAR will be set to the foo value.

This environment variable is generated by module command and should not be modified
externally.

MODULES_ICASE
When module specification are passed as argument to module sub-commands or
modulefile Tcl commands, defines the case sensitiveness to apply to match them.
When MODULES_ICASE is set to never, a case sensitive match is applied in any cases.
When set to search, a case insensitive match is applied to the avail, list, whatis,
paths and savelist sub-commands. When set to always, a case insensitive match is
also applied to the other module sub-commands and modulefile Tcl commands for the
module specification they receive as argument.

This environment variable value supersedes the default value set in the icase
configuration option. It can be defined with the config sub-command. The --icase/-i
command line switches, which correspond to the always mode, override this
environment variable.

MODULES_IMPLICIT_DEFAULT
Defines (if set to 1) or not (if set to 0) an implicit default version for modules
without a default version explicitly defined (see Locating Modulefiles section in
the modulefile(4) man page).

Without either an explicit or implicit default version defined a module must be
fully qualified (version should be specified in addition to its name) to get:

• targeted by module load, switch, display, help, test and path sub-commands.

• restored from a collection, unless already loaded in collection-specified order.

• automatically loaded by automated module handling mechanisms (see
MODULES_AUTO_HANDLING section) when declared as module requirement, with prereq
or module load modulefile commands.

An error is returned in the above situations if either no explicit or implicit
default version is defined.

This environment variable value supersedes the default value set in the
implicit_default configuration option. It can be defined with the config
sub-command. This environment variable is ignored if implicit_default has been
declared locked in locked_configs configuration option.

MODULES_IMPLICIT_REQUIREMENT
Defines (if set to 1) or not (if set to 0) an implicit prereq or conflict
requirement onto modules specified respectively on module load or module unload
commands in modulefile. When enabled an implicit conflict requirement onto
switched-off module and a prereq requirement onto switched-on module are also
defined for module switch commands used in modulefile.

This environment variable value supersedes the default value set in the
implicit_requirement configuration option. It can be defined with the config
sub-command. The --not-req option, applied to a module command in a modulefile,
overrides this environment variable.

MODULES_LIST_OUTPUT
A colon separated list of the elements to report in addition to module names on
list sub-command regular output mode.

Accepted elements that can be set in value list are:

• header: sentence to introduce the list of loaded modules or to state that no
modules are loaded currently.

• idx: index position of each loaded module.

• key: legend appended at the end of the output to explain it.

• variant: variant values selected for loaded modules.

• sym: symbolic versions associated with loaded modules.

• tag: tags associated with loaded modules.

The order of the elements in the list does not matter. Module names are the only
content reported when LIST is set to an empty value.

This environment variable value supersedes the default value set in the list_output
configuration option. It can be defined with the config sub-command. The --output/‐
-o command line switches override this environment variable.

MODULES_LIST_TERSE_OUTPUT
A colon separated list of the elements to report in addition to module names on
list sub-command terse output mode.

See MODULES_LIST_OUTPUT to get the accepted elements that can be set in value list.

The order of the elements in the list does not matter. Module names are the only
content reported when LIST is set to an empty value.

This environment variable value supersedes the default value set in the
list_terse_output configuration option. It can be defined with the config
sub-command. The --output/-o command line switches override this environment
variable.

MODULES_MCOOKIE_CHECK
If set to eval, the Modules magic cookie (i.e., #%Module file signature) is only
checked to determine if a file is a modulefile when evaluating these files. If set
to always, the Modules magic cookie is also checked when searching for modules.

The eval mode is made to significantly reduce file checks when walking through
modulepaths to search for modulefiles. Special care should be given to the content
of modulepaths when this eval mode is set as the following kind of files are
included in search results:

• modulefiles with a magic cookie requiring a higher version of modulecmd.tcl

• files not beginning with the magic cookie #%Module

• read-protected files

This environment variable value supersedes the default value set in the
mcookie_check configuration option. It can be defined with the config sub-command.

MODULES_MCOOKIE_VERSION_CHECK
If set to 1, the version set in the Modules magic cookie in modulefile is checked
against the current version of modulecmd.tcl to determine if the modulefile can be
evaluated.

This environment variable value supersedes the default value set in the
mcookie_version_check configuration option. It can be defined with the config
sub-command.

MODULES_ML
If set to 1, define ml command when initializing Modules (see Package
Initialization section). If set to 0, ml command is not defined.

This environment variable value supersedes the default value set in the ml
configuration option. It can be defined with the config sub-command.

To enable or disable ml command, MODULES_ML should be set prior Modules
initialization or the ml configuration option should be set in the initrc
configuration file.

MODULES_NEARLY_FORBIDDEN_DAYS
Number of days a module is considered nearly forbidden prior reaching its expiry
date set by module-forbid modulefile command. When a nearly forbidden module is
evaluated a warning message is issued to inform module will soon be forbidden. If
set to 0, modules will never be considered nearly forbidden. Accepted values are
integers comprised between 0 and 365.

This environment variable value supersedes the default value set in the
nearly_forbidden_days configuration option. It can be defined with the config
sub-command.

MODULES_PAGER
Text viewer for use to paginate message output if error output stream is attached
to a terminal. The value of this variable is composed of a pager command name or
path eventually followed by command-line options.

This environment variable value supersedes the default value set in the pager
configuration option. It can be defined with the config sub-command.

If MODULES_PAGER variable is set to an empty string or to the value cat, pager will
not be launched.

MODULES_PROTECTED_ENVVARS
A colon separated list of environment variable names that should not be modified by
any modulefile command.

Prevents modifications by append-path, prepend-path, remove-path, setenv and
unsetenv. When these modulefile commands attempt to modify a protected environment
variable, a warning message is emitted and modification is ignored.

This environment variable value supersedes the default value set in the
protected_envvars configuration option. It can be defined with the config
sub-command.

MODULES_QUARANTINE_SUPPORT
If set to 1, produces the shell code for quarantine mechanism when the autoinit
sub-command generates the module shell function.

The generated shell code for quarantine mechanism indirectly passes the environment
variable defined in MODULES_RUN_QUARANTINE to the modulecmd.tcl script to protect
its run-time environment from side-effect coming from the current definition of
these variables.

To enable quarantine support, MODULES_QUARANTINE_SUPPORT should be set to 1 prior
Modules initialization or the quarantine_support configuration should be set to 1
in the initrc configuration file.

Generated code for quarantine mechanism sets the __MODULES_QUARANTINE_SET
environment variable when calling the modulecmd.tcl script to make it restore the
environment variable put in quarantine.

This environment variable value supersedes the default value set in the
quarantine_support configuration option. It can be defined with the config
sub-command.

MODULES_REDIRECT_OUTPUT
If set to 0, the output generated by module command is kept on stderr and not
redirected to stdout channel.

This environment variable value supersedes the default value set in the
redirect_output configuration option. It can be defined with the config
sub-command. The --redirect and --no-redirect command line switches override this
environment variable.

MODULES_RESET_TARGET_STATE
Defines behavior of reset sub-command. When set to __init__, initial environment is
restored. When set to __purge__, reset performs a purge sub-command. Any other
value designates a name collection to restore.

This environment variable value supersedes the default value set in the
reset_target_state configuration option. It can be defined with the config
sub-command.

MODULES_RUN_QUARANTINE
A space separated list of environment variable names that should be passed
indirectly to modulecmd.tcl to protect its run-time environment from side-effect
coming from their current definition.

If the quarantine mechanism has been included in module shell function (see
MODULES_QUARANTINE_SUPPORT), 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 __MODULES_QUAR_<VAR> variables.

This environment variable value supersedes the default value set in the
run_quarantine configuration option. It can be defined with the config sub-command.

MODULES_RUNENV_<VAR>
Value to set to environment variable <VAR> for modulecmd.tcl run-time execution if
<VAR> is referred in MODULES_RUN_QUARANTINE.

MODULES_SEARCH_MATCH
When searching for modules with avail sub-command, defines the way query string
should match against available module names. With starts_with value, returned
modules are those whose name begins by search query string. When set to contains,
any modules whose fully qualified name contains search query string are returned.

This environment variable value supersedes the default value set in the
search_match configuration option. It can be defined with the config sub-command.
The --starts-with and --contains command line switches override this environment
variable.

MODULES_SET_SHELL_STARTUP
If set to 1, defines when module command initializes the shell startup file to
ensure that the module command is still defined in sub-shells. Setting shell
startup file means defining the ENV and BASH_ENV environment variable to the
Modules bourne shell initialization script. If set to 0, shell startup file is not
defined.

This environment variable value supersedes the default value set in the
set_shell_startup configuration option. It can be defined with the config
sub-command.

To enable shell startup file, MODULES_SET_SHELL_STARTUP should be set to 1 prior
Modules initialization or the set_shell_startup configuration option should be set
to 1 in the initrc configuration file.

MODULES_SHELLS_WITH_KSH_FPATH
A list of shell on which the FPATH environment variable should be defined at
initialization time to point to the ksh-functions directory where the ksh
initialization script for module command is located. It enables for the listed
shells to get module function defined when starting ksh as sub-shell from there.

Accepted values are a list of shell among sh, bash, csh, tcsh and fish separated by
colon character (:).

This environment variable value supersedes the default value set in the
shells_with_ksh_fpath configuration option. It can be defined with the config
sub-command.

To enable the setup of FPATH for some shells, MODULES_SHELLS_WITH_KSH_FPATH should
be set to the list of these shells prior Modules initialization or the
shells_with_ksh_fpath configuration option should be set to the list of these
shells in the initrc configuration file.

MODULES_SILENT_SHELL_DEBUG
If set to 1, disable any xtrace or verbose debugging property set on current shell
session for the duration of either the module command or the module shell
initialization script. Only applies to Bourne Shell (sh) and its derivatives.

This environment variable value supersedes the default value set in the
silent_shell_debug configuration option. It can be defined with the config
sub-command.

To generate the code to silence shell debugging property in the module shell
function, MODULES_SILENT_SHELL_DEBUG should be set to 1 prior Modules
initialization or the silent_shell_debug configuration option should be set to 1 in
the initrc configuration file.

MODULES_SITECONFIG
Location of a site-specific configuration script to source into modulecmd.tcl. See
Site-specific configuration section for details.

This environment variable value supersedes the default value set in the
extra_siteconfig configuration option. It can be defined with the config
sub-command. This environment variable is ignored if extra_siteconfig has been
declared locked in locked_configs configuration option.

MODULES_TAG_ABBREV
Specifies the abbreviation strings used to report module tags (see Module tags
section). Its value is a colon-separated list of module tag names associated to an
abbreviation string (e.g. tagname=abbrev).

If a tag is associated to an empty string abbreviation, this tag will not be
reported. In case the whole MODULES_TAG_ABBREV environment variable is set to an
empty string, tags are reported but not abbreviated.

This environment variable value supersedes the default value set in the tag_abbrev
configuration option. It can be defined with the config sub-command.

MODULES_TAG_COLOR_NAME
Specifies the tag names or abbreviations whose graphical rendering should be
applied over themselves instead of being applied over the name of the module they
are attached to. Value of MODULES_TAG_COLOR_NAME is a colon-separated list of
module tag names or abbreviation strings (see Module tags section).

When a select graphic rendition is defined for a tag name or a tag abbreviation
string, it is applied over the module name associated with the tag and tag name or
abbreviation is not displayed. When listed in MODULES_TAG_COLOR_NAME environment
variable, a tag name or abbreviation is displayed and select graphic rendition is
applied over it.

This environment variable value supersedes the default value set in the
tag_color_name configuration option. It can be defined with the config sub-command.

MODULES_TCL_LINTER
Command name or path for use to check syntax of modulefile through the lint
sub-command.

This environment variable value supersedes the default value set in the tcl_linter
configuration option. It can be defined with the config sub-command.

MODULES_TERM_BACKGROUND
Inform Modules of the terminal background color to determine if the color set for
dark background or the color set for light background should be used to color
output in case no specific color set is defined with the MODULES_COLORS variable.
Accepted values are dark and light.

This environment variable value supersedes the default value set in the
term_background configuration option. It can be defined with the config
sub-command.

MODULES_TERM_WIDTH
Specifies the number of columns of the output. If set to 0, the output width will
be the full terminal width, which is automatically detected by the module command.
Accepted values are integers comprised between 0 and 1000.

This environment variable value supersedes the default value set in the term_width
configuration option. It can be defined with the config sub-command. The --width/-w
command line switches override this environment variable.

MODULES_UNLOAD_MATCH_ORDER
When a module unload request matches multiple loaded modules, unload firstly loaded
module or lastly loaded module. Accepted values are returnfirst and returnlast.

This environment variable value supersedes the default value set in the
unload_match_order configuration option. It can be defined with the config
sub-command.

MODULES_VARIANT_SHORTCUT
Specifies the shortcut characters that could be used to specify and report module
variants (see Module variants section). Its value is a colon-separated list of
variant names associated to a shortcut character (e.g., variantname=shortcutchar).

A variant shortcut must be of one character length and must avoid characters used
for other concerns or in module names (i.e., [-+~/@=a-zA-Z0-9]).

If a shortcut is associated to an empty string or an invalid character, this
shortcut definition will be ignored.

This environment variable value supersedes the default value set in the
variant_shortcut configuration option. It can be defined with the config
sub-command.

MODULES_VERBOSITY
Defines the verbosity level of the module command. Available verbosity levels from
the least to the most verbose are:

• silent: turn off error, warning and informational messages but does not affect
module command output result.

• concise: enable error and warning messages but disable informational messages.

• normal: turn on informational messages, like a report of the additional module
evaluations triggered by loading or unloading modules, aborted evaluation issues
or a report of each module evaluation occurring during a restore or source
sub-commands.

• verbose: add additional informational messages, like a systematic report of the
loading or unloading module evaluations.

• verbose2: report loading or unloading module evaluations of hidden-loaded
modules, report if loading module is already loaded or if unloading module is not
loaded.

• trace: provide details on module searches, resolutions, selections and
evaluations.

• debug: print debugging messages about module command execution.

• debug2: report modulecmd.tcl procedure calls in addition to printing debug
messages.

This environment variable value supersedes the default value set in the verbosity
configuration option. It can be defined with the config sub-command. The --silent,
--verbose, --debug and --trace command line switches override this environment
variable.

MODULES_WA_277
If set to 1 prior to Modules package initialization, enables workaround for Tcsh
history issue (see https://github.com/cea-hpc/modules/issues/277). This issue
leads to erroneous history entries under Tcsh shell. When workaround is enabled, an
alternative module alias is defined which fixes the history mechanism issue.
However the alternative definition of the module alias weakens shell evaluation of
the code produced by modulefiles. Characters with a special meaning for Tcsh shell
(like { and }) may not be used anymore in shell alias definition otherwise the
evaluation of the code produced by modulefiles will return a syntax error.

This environment variable value supersedes the default value set in the wa_277
configuration option. It can be defined with the config sub-command.

To enable this workaround, MODULES_WA_277 should be set to 1 prior Modules
initialization or the wa_277 configuration option should be set to 1 in the initrc
configuration file.

MODULESHOME
The location of the main Modules package file directory containing module command
initialization scripts, the executable program modulecmd.tcl, and a directory
containing a collection of main modulefiles.

This environment variable value supersedes the default value set in the home
configuration option. It can be defined with the config sub-command.

FILES

/usr/share/modules
The MODULESHOME directory.

/etc/environment-modules/initrc
The configuration file evaluated by modulecmd.tcl when it initializes to enable the
default modulepaths, load the default modules and set module command configuration.

initrc is a modulefile(4) so it is written as a Tcl script and defines modulepaths to
enable with module use, modules to load with module load and configuration to apply
with module config. As any modulefile initrc must begin with the Modules magic cookie
(i.e., #%Module file signature).

initrc is optional. When this configuration file is present it is evaluated after the
modulespath configuration file. See the Package Initialization section for details.

/etc/environment-modules/modulespath
The configuration file evaluated by modulecmd.tcl when it initializes to enable the
default modulepaths. This file contains the list of modulepaths separated by either
newline or colon characters.

modulespath is optional. When this configuration file is present it is evaluated before
the initrc configuration file. See the Package Initialization section for details.

/etc/environment-modules/siteconfig.tcl
The site-specific configuration script of modulecmd.tcl. An additional configuration
script could be defined using the MODULES_SITECONFIG environment variable. See
Site-specific configuration for detailed information.

/etc/environment-modules/rc
The system-wide modules rc file. The location of this file can be changed using the
MODULERCFILE environment variable as described above.

$HOME/.modulerc
The user specific modules rc file.

$HOME/.module
The user specific collection directory.

/usr/share/modules/modulefiles
The directory for system-wide modulefiles. The location of the directory can be changed
using the MODULEPATH environment variable as described above.

/usr/lib/x86_64-linux-gnu/modulecmd.tcl
The modulefile interpreter that gets executed upon each invocation of module.

/usr/share/modules/init/<shell>
The Modules package initialization file sourced into the user's environment.

COPYRIGHT

       1996-1999 John L. Furlani & Peter W. Osel,  1998-2017  R.K.Owen,  2002-2004  Mark  Lakata,
       2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle

NAME

SYNOPSIS

DESCRIPTION

EXIT STATUS

ENVIRONMENT

FILES

SEE ALSO

COPYRIGHT