FreeBSD Manual Pages

home | help

MODULE(1) Modules MODULE(1)

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 envi-
ronment 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, MAN-
PATH, etc. Modulefiles may be shared by many users on a system and
users may have their own set to supplement or replace the shared mod-
ulefiles.

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-com-
mand 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/local/Modules/5.4.0/libexec 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 un-
set or empty), the modulespath and initrc configuration files located
in /usr/local/Modules/5.4.0/etc 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 mod-
ules.

The module alias or function executes the modulecmd.tcl program and has
the shell evaluate the command's output. The first argument to mod-
ulecmd.tcl specifies the type of shell.

The initialization scripts are kept in /usr/local/Mod-
ules/5.4.0/init/<shell> where <shell> is the name of the sourcing
shell. For example, a C Shell user sources the /usr/local/Mod-
ules/5.4.0/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 for de-
tailed information.

Examples of initialization
C Shell initialization (and derivatives):

source /usr/local/Modules/5.4.0/init/csh
module load modulefile modulefile ...

Bourne Shell (sh) (and derivatives):

. /usr/local/Modules/5.4.0/init/sh
module load modulefile modulefile ...

Perl:

require "/usr/local/Modules/5.4.0/init/perl.pm";
&module('load', 'modulefile', 'modulefile', '...');

Python:

import os
exec(open("/usr/local/Modules/5.4.0/init/python.py").read(), globals())
module("load", "modulefile", "modulefile", "...")

Bourne Shell (sh) (and derivatives) with autoinit sub-command:

eval "$(/usr/local/Modules/5.4.0/libexec/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
/usr/local/Modules/5.4.0/etc/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 module-
files. See modulefile for detailed information.

Upon invocation of modulecmd.tcl module run-command files are sourced
in the following order:

1. Global RC file(s) as specified by MODULERCFILE variable or /usr/lo-
cal/Modules/5.4.0/etc/rc. If a path element in MODULERCFILE points
to a directory, the modulerc file in this directory is used as a
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 ver-
sion number may be placed after this string. The version number re-
flects 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 parame-
ter. These may be used to control output format of all information dis-
played and the module behavior in case of locating and interpreting
modulefiles.

All switches may be entered either in short or long notation. The fol-
lowing 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 col-
lections 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 ver-
sion or also the implicit default version if the configuration
option implicit_default is enabled (see Locating Modulefiles
section in the modulefile man page for further details on im-
plicit default version).

--force, -f
On load, unload, switch, load-any, try-load, mod-to-sh and
source sub-commands by-pass any unsatisfied modulefile con-
straint 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 mod-
ulefile will be unloaded even if it is required as a prereq by
another modulefile.

On load, ml, mod-to-sh, purge, reload, switch, try-load and
unload sub-commands applies continue on error behavior when an
error occurs even if abort_on_error option is enabled.

On ml, purge, reload, reset, restore, stash, stashpop, switch
and unload sub-commands, unloads modulefile anyway even if an
evaluation error occurs.

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

--ignore-cache
Ignore module cache.

--ignore-user-rc
Skip evaluation of user-specific module rc file ($HOME/.mod-
ulerc).

--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 out-
put 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 man page).

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

--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 mod-
ulefiles 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 reg-
ular or terse output modes. Accepted values are a LIST of ele-
ments 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, indesym, sym, tag, key, variant and variantif-
spec.

Accepted elements in LIST for list sub-command are: header, idx,
variant, alias, indesym, 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.

LIST may be prefixed by + or - character to indicate respec-
tively to append it to or subtract it from current configuration
option value.

See also MODULES_AVAIL_OUTPUT and MODULES_LIST_OUTPUT.

--paginate
Pipe all message output into less (or if set, to the command re-
ferred 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 com-
mand output result is not affected by silent mode.

--starts-with, -S
On avail, list and savelist sub-commands, return modules or col-
lections 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 ap-
plied to this module.

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

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

--trace, -T
Trace mode. Report details on module searches, resolutions, se-
lections and evaluations in addition to printing verbose mes-
sages.

--verbose, -v, -vv
Enable verbose messages during module command execution. Multi-
ple -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 recur-
sively searched in the same manner than for the avail sub-com-
mand. Only the symbolic version-names and aliases found in the
search are displayed.

append-path [options] variable value...
Append value to environment variable. The variable is a colon,
or delimiter, separated list. See append-path in the modulefile
man page for options description and further explanation.

When append-path is called as a module sub-command, the refer-
ence 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-in-
depth] [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 applica-
tion can be supported by creating a subdirectory for the appli-
cation containing modulefiles for each version.

Symbolic version-names and aliases found in the search are dis-
played 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 rendi-
tion is defined for module default version, the default symbol
is omitted and instead the defined graphical rendition is ap-
plied 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).

Module variants and their available values may be reported along
the module name they belong to (see Module variants section) if
defined in avail output configuration option (see --output/-o
option). The Extra match search process is triggered to collect
variant information.

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

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

If pattern contains variant specification or Extra specifier,
the Extra match search process is triggered to collect command
information used in modulefiles. Modules are included in results
only if they match pattern variant specification and extra spec-
ifier. pattern may be a bare variant specification or extra
specifier without mention of a module name.

cachebuild [modulepath...]
Build module cache file for designated modulepaths. If no argu-
ment is provided cache file is built for every modulepath cur-
rently enabled. Cache file creation is skipped for modulepaths
where user cannot write in.

The name and content of every readable modulefiles and rc files
are recorded into cache file. Also last modification time of
modulefiles and invalid modulefile error messages are recorded.
With all these information, the sole cache file is evaluated to
know what is available within modulepath.

See Module cache section for more details on module cache mecha-
nism.

cacheclear
Delete module cache file in every modulepath currently enabled.
If user cannot write in a modulepath directory, cache file dele-
tion is skipped for this modulepath.

See Module cache section for more details on module cache mecha-
nism.

clear [-f]
Force the Modules package to believe that no modules are cur-
rently 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 men-
tion 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.

For options whose value is a colon-separated list, value may be
prefixed by + or - character. It indicates respectively to ap-
pend it to or subtract it from current option value.

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

Existing option names are:

abort_on_error
List of module sub-commands that abort evaluation se-
quence when an error is raised by an evaluated module.
Evaluations already performed are withdrawn and remaining
modules to evaluate are skipped.

This configuration option can be changed at installation
time with --with-abort-on-error option. The
MODULES_ABORT_ON_ERROR environment variable is defined by
config sub-command when changing this configuration op-
tion from its default value. See MODULES_ABORT_ON_ERROR
description for details.

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 de-
fined by config sub-command when changing this configura-
tion 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 op-
tion from its default value. The --auto and --no-auto
command line switches change the value of this configura-
tion 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 op-
tion from its default value. The --indepth and
--no-indepth command line switches change the value of
this configuration option. See MODULES_AVAIL_INDEPTH de-
scription 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 en-
vironment 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 de-
fined by config sub-command when changing this configura-
tion option from its default value. The --output/-o com-
mand line switches change the value of this configuration
option. See MODULES_AVAIL_TERSE_OUTPUT description for
details.

cache_buffer_bytes
Size of the buffer used when reading or writing cache
files.

Default value is 32768. Values between 4096 and 1000000
are accepted. The MODULES_CACHE_BUFFER_BYTES environment
variable is defined by config sub-command when changing
this configuration option from its default value.

cache_expiry_secs
Number of seconds a cache file is considered valid after
being generated.

Default value is 0. Values between 0 and 31536000 are ac-
cepted. The MODULES_CACHE_EXPIRY_SECS environment vari-
able is defined by config sub-command when changing this
configuration option from its default value.

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

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

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 envi-
ronment 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 de-
scription 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 envi-
ronment 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 envi-
ronment 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 envi-
ronment 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 op-
tion from its default value. See MODULES_SITECONFIG de-
scription for details.

home Location of Modules package main directory.

Default value is /usr/local/Modules/5.4.0. 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 installa-
tion time with --with-icase option. The MODULES_ICASE en-
vironment 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 de-
scription for details.

ignore_cache
Ignore module cache.

Default is 0. The MODULES_IGNORE_CACHE environment vari-
able is defined by config sub-command when changing this
configuration option from its default value. The
--ignore-cache command line switch changes the value of
this configuration option.

ignore_user_rc
Skip evaluation of user-specific module rc file
($HOME/.modulerc).

Default is 0. The MODULES_IGNORE_USER_RC environment
variable is defined by config sub-command when changing
this configuration option from its default value. The
--ignore-user-rc command line switch changes the value of
this configuration option.

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 de-
fined by config sub-command when changing this configura-
tion 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 configu-
ration option from its default value. The --output/-o
command line switches change the value of this configura-
tion option. See MODULES_LIST_OUTPUT description for de-
tails.

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 installa-
tion 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 op-
tion. See MODULES_LIST_TERSE_OUTPUT description for de-
tails.

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

This configuration option is set to an empty value by de-
fault. 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 envi-
ronment 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 de-
fined by config sub-command when changing this configura-
tion 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 de-
fined by config sub-command when changing this configura-
tion 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 in-
stallation time with --with-pager and --with-pager-opts
options. The MODULES_PAGER environment variable is de-
fined by config sub-command when changing this configura-
tion 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 de-
fined by config sub-command when changing this configura-
tion option from its default value. See
MODULES_QUARANTINE_SUPPORT description for details.

rcfile Location of global run-command file(s).

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

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 environ-
ment 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 environ-
ment 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 de-
tails.

run_quarantine
Environment variables to indirectly pass to mod-
ulecmd.tcl.

This configuration option is set to an empty value by de-
fault. 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 configu-
ration option. See MODULES_RUN_QUARANTINE description for
details.

search_match
Module search match style.

Default value is starts_with. It can be changed at in-
stallation time with --with-search-match option. The
MODULES_SEARCH_MATCH environment variable is defined by
config sub-command when changing this configuration op-
tion from its default value. The --contains and
--starts-with command line switches change the value of
this configuration option. See MODULES_SEARCH_MATCH de-
scription 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 de-
fault. 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 de-
finition.

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 de-
fined by config sub-command when changing this configura-
tion 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 /usr/local/Modules/5.4.0/etc/sitecon-
fig.tcl. It can be changed at installation time with
--prefix or --etcdir options. The value of this option
cannot be altered.

source_cache
Cache content of files evaluated in modulefile through
source(n) Tcl command.

Default value is 0. It can be changed at installation
time with --enable-source-cache option. The
MODULES_SOURCE_CACHE environment variable is defined by
config sub-command when changing this configuration op-
tion from its default value. See MODULES_SOURCE_CACHE de-
scription for details.

sticky_purge
Error behavior when unloading sticky or super-sticky mod-
ule during a module purge.

Raise an error (default) or emit a warning or be silent.
It can be changed at installation time with
--with-sticky-purge option. The MODULES_STICKY_PURGE en-
vironment variable is defined by config sub-command when
changing this configuration option from its default
value. See MODULES_STICKY_PURGE description for details.

tag_abbrev
Abbreviations to use to report module tags.

Default value is auto-loaded=aL:loaded=L:hidden=H:hid-
den-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:su-
per-sticky=sS:keep-loaded=kL. It can be changed at in-
stallation time with --with-tag-abbrev option. The
MODULES_TAG_ABBREV environment variable is defined by
config sub-command when changing this configuration op-
tion from its default value. See MODULES_TAG_ABBREV de-
scription 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 de-
fault. 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 de-
tails.

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

unique_name_loaded
Only one module loaded per module name.

Default value is 0. It can be changed at installation
time with --enable-unique-name-loaded option. The
MODULES_UNIQUE_NAME_LOADED environment variable is de-
fined by config sub-command when changing this configura-
tion option from its default value. See
MODULES_UNIQUE_NAME_LOADED description for details.

unload_match_order
Unload firstly loaded or lastly loaded module matching
request.

Default value is returnlast. It can be changed at instal-
lation time with --with-unload-match-order option. The
MODULES_UNLOAD_MATCH_ORDER environment variable is de-
fined by config sub-command when changing this configura-
tion option from its default value. See
MODULES_UNLOAD_MATCH_ORDER description for details.

variant_shortcut
Shortcut characters that could be used to specify or re-
port module variants.

This configuration option is set to an empty value by de-
fault. 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 installa-
tion time with --with-verbosity option. The
MODULES_VERBOSITY environment variable is defined by
config sub-command when changing this configuration op-
tion 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 en-
vironment 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 condi-
tional 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 speci-
fiers section below).

When several modulefiles are passed, they are evaluated sequen-
tially in the specified order. If one modulefile evaluation
raises an error, display sequence continues.

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.

When several modulefiles are passed, they are evaluated sequen-
tially in the specified order. If one modulefile evaluation
raises an error, help sequence continues.

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 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 mod-
ulefiles 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 initializa-
tion 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 initializa-
tion 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 initializa-
tion 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 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 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. Re-
turns a false value otherwise. See is-saved in the modulefile
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 man page for further explanation.

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

lint [-a] [modulefile...]
Analyze syntax of one or more modulefiles with the linter com-
mand 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 mod-
ules 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 sec-
tion).

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

If pattern contains variant specification, loaded modules are
included in results only if they match it. pattern may be a bare
variant specification without mention of a module name.

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 mod-
ule, the auto-loaded tag is associated instead (see Module tags
section).

When several modulefiles are passed, they are loaded sequen-
tially in the specified order. If one modulefile evaluation
raises an error, load sequence continues: loaded modules prior
the evaluation error are kept loaded and sequence is resumed
with the load of remaining modulefile in list. Conversely, load
sequence is aborted and already loaded modulefiles are withdrawn
if load sub-command is defined in abort_on_error configuration
option and --force option is not set.

The --tag option accepts a list of module tags to apply to mod-
ulefile 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 evalua-
tion fails, an error is reported and next modulefile in list is
evaluated.

load-any command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

The --tag option accepts a list of module tags to apply to mod-
ulefile 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 envi-
ronment. Like for load sub-command, no evaluation occurs if mod-
ulefile is found loaded in current environment.

Changes made on environment variable intended for Modules pri-
vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig-
nored.

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.

When several modulefiles are passed, they are evaluated sequen-
tially in the specified order. If one modulefile evaluation
raises an error, mod-to-sh sequence continues: environment
change from modules evaluated prior the error are preserved and
sequence is resumed with the evaluation of remaining modulefile
in list. Conversely, mod-to-sh sequence is aborted and changes
from already evaluated modules are withdrawn if mod-to-sh
sub-command is defined in abort_on_error configuration option
and --force option is not set.

path modulefile
Print path to modulefile.

paths pattern
Print path of available modulefiles matching pattern.

The parameter pattern 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 speci-
fiers section below).

prepend-path [options] variable value...
Prepend value to environment variable. The variable is a colon,
or delimiter, separated list. See prepend-path in the modulefile
man page for options description and further explanation.

When prepend-path is called as a module sub-command, the refer-
ence 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, mod-
ulefiles that are depended by non-unloadable modules and module-
files raising an evaluation error.

If one modulefile unload evaluation raises an error, purge se-
quence continues: unloaded modules prior the evaluation error
are kept unloaded and sequence is resumed with the unload of re-
maining modulefiles. Conversely, purge sequence is aborted and
already unloaded modulefiles are restored if purge sub-command
is defined in abort_on_error configuration option and --force
option is not set.

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, set-function and puts modulefile commands will pro-
duce 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.

If one modulefile evaluation raises an error, refresh sequence
continues: environment changes from refreshed modules prior the
evaluation error are preserved and sequence is resumed with the
refresh of remaining modulefiles.

reload [-f]
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.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

If one modulefile load or unload evaluation raises an error, re-
load sequence aborts: environment changes coming from already
evaluated modulefiles are withdrawn and remaining modulefile
evaluations are skipped. Conversely, if reload is removed from
abort_on_error configuration option list or if --force option is
set, reload sequence continues: already achieved module evalua-
tions are kept and reload sequence is resumed with the remaining
modulefiles.

remove-path [options] variable value...
Remove value from the colon, or delimiter, separated list in en-
vironment variable. See remove-path in the modulefile man page
for options description and further explanation.

When remove-path is called as a module sub-command, the refer-
ence 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 [-f]
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.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

reset behavior can be changed with reset_target_state. This
configuration option is set by default to __init__, which corre-
sponds 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 collec-
tion.

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

If collection name is __init__, initial environment state de-
fined in __MODULES_LMINIT environment variable is restored.

When restoring a collection, the currently set MODULEPATH direc-
tory 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 pre-
served 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 op-
tion implicit_default is disabled.

If one modulefile load or unload evaluation raises an error, re-
store sequence continues: environment changes from modules un-
loaded or loaded prior the evaluation error are preserved and
sequence is resumed with the unload or load of remaining module-
files.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

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

save [collection]
Record the currently set MODULEPATH directory list and the cur-
rently 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 loca-
tion 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 en-
abled, 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 de-
fault 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 col-
lection 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 wild-
card characters. pattern is matched in a case insensitive man-
ner 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-com-
mand.

saverm [collection]
Delete the collection file under the user's collection direc-
tory. 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 ap-
pended 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 de-
fined 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 func-
tions, shell completions and current working directory are
tracked.

Changes made on environment variable intended for Modules pri-
vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig-
nored.

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.

Shell could also be set to bash-eval. In this mode, bash shell
script is not sourced but the output resulting from its execu-
tion is evaluated to determine the environment changes it does.

show modulefile...
See display.

source [options] modulefile...
Execute modulefile into the shell environment. Once executed
modulefile is not marked loaded in shell environment which dif-
fer 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 avail-
able modulefiles.

When several modulefiles are passed, they are evaluated sequen-
tially in the specified order. If one modulefile evaluation
raises an error, source sequence continues: environment changes
from modules sourced prior the evaluation error are preserved
and sequence is resumed with the source of remaining modulefile
in list.

stash [-f]
Save current environment in a stash collection then reset to
initial environment.

A collection is created only if current environment state dif-
fers 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 com-
mand 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.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

stashclear
Remove all stash collection files of current collection_target.
If no collection target is currently set, remove stash collec-
tion 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 [-f] [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.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

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 mod-
ulefile once loaded. If module is already loaded, tags from
taglist are added to the list of tags already applied to this
module.

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

If unload evaluation of modulefile1 raises an error, switch se-
quence aborts: no environment change from modulefile1 unload is
applied and load of modulefile2 is skipped. Conversely, if
switch_unload value is removed from abort_on_error configuration
option list (and switch value is not set there) or if --force
option is set, switch sequence continues. If modulefile1 is
tagged super-sticky, switch sequence aborts in any case.

If load evaluation of modulefile2 raises an error, switch se-
quence continues: environment changes from modulefile1 unload
are applied but not those from failed modulefile2 load. Con-
versely, whole switch sequence is aborted and unloaded module-
file1 is restored if switch sub-command is defined in
abort_on_error configuration option and --force option is not
set.

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

When several modulefiles are passed, they are evaluated sequen-
tially in the specified order. If one modulefile evaluation
raises an error, test sequence continues.

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

try-load [options] modulefile...
Like load sub-command, load modulefile into the shell environ-
ment, but do not complain if modulefile cannot be found. If mod-
ulefile is found but its evaluation fails, error is still re-
ported.

try-load command accepts the following options:

• --auto|--no-auto

• -f|--force

• --tag=taglist

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

When several modulefiles are passed, they are try-loaded sequen-
tially in the specified order. If one modulefile evaluation
raises an error, try-load sequence continues: loaded modules
prior the evaluation error are kept loaded and sequence is re-
sumed with the load of remaining modulefile in list. Con-
versely, try-load sequence is aborted and already loaded module-
files are withdrawn if try-load sub-command is defined in
abort_on_error configuration option and --force option is not
set.

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

When the --force option is set, unload modulefiles anyway even
if an evaluation error occurs.

When several modulefiles are passed, they are unloaded sequen-
tially in the specified order. If one modulefile evaluation
raises an error, unload sequence continues: unloaded modules
prior the evaluation error are kept unloaded and sequence is re-
sumed with the unload of remaining modulefile in list. Con-
versely, unload sequence is aborted and already unloaded module-
files are restored if unload sub-command is defined in
abort_on_error configuration option and --force option is not
set.

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. Oth-
erwise 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 what-
ever 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 ref-
erence 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 initial-
ization modulefile script.

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

whatis [-a] [-j] [pattern...]
Display the information set up by the module-whatis commands in-
side modulefiles matching pattern. pattern may contain wildcard
characters. If no pattern is specified, all module-whatis lines
will be shown.

Modulefiles
modulefiles are written in the Tool Command Language (Tcl) and are in-
terpreted 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 con-
straint 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 sepa-
rated 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 in-
stance 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 @ver-
sion1:version2 syntaxes, for instance foo@1.2: will select all ver-
sions of module foo greater than or equal to 1.2, foo@:1.3 will se-
lect 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 bene-
fit from the activation of the extended default mechanism (see
MODULES_EXTENDED_DEFAULT) to use an abbreviated notation like @1 to re-
fer 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 de-
fined unless a symbolic version, alias, or regular module version al-
ready 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 des-
ignate the loaded version of the module with associated selected vari-
ants. This version symbol should be specified using the @ prefix nota-
tion (e.g., foo@loaded). An error is returned if no version of desig-
nated 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 trans-
mitted 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 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 vari-
ant.

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

Extra specifier
After the module name, extra specifiers can be defined in module search
context. Extra specifiers are an extra query to list available module-
files based on their content definition. They rely on the Extra match
search mechanism that collects content of available modulefiles.

Extra specifier can be set with the element:name[,name,...] syntax
where element is a Tcl modulefile command and name an item defined by
this command. Depending on the kind of Tcl modulefile command, name can
refer to an environment variable, a shell alias, a module specifica-
tion, etc.

Supported extra specifier elements are:

• variant, complete, uncomplete, set-alias, unset-alias, set-function,
unset-function, chdir, family, tag

• setenv, unsetenv, append-path, prepend-path, remove-path and pushenv:
these elements related to environment variable handling may also be
aliased envvar

• prereq, prereq-any, prereq-all, depends-on, always-load, load,
load-any, try-load, switch and switch-on: these elements related to
module requirement definition accept a module specification as value
name and may be aliased require

• conflict, unload, switch and switch-off: these elements related to
module incompatibility definition accept a module specification as
value name and may be aliased incompat

Each of the above supported elements corresponds to a Tcl modulefile
command. load, load-any, try-load, switch and unload match correspond-
ing module sub-commands. prereq-any is an alias on prereq and vice
versa as both Tcl modulefile commands are the same. Following the same
trend prereq-all is an alias on depends-on and vice versa. Regarding
switch-off and switch-on elements they correspond respectively to the
module to unload (if specified) and the module to load on a module
switch command. switch is an alias that matches both switch-off and
switch-on elements. require and incompat elements do not match module
commands where --not-req option is set.

When several names are set on one element criterion (e.g.,
env:PATH,LD_LIBRARY_PATH), they act as an OR operation. Which means
modules listed in result are those matching any of the element names
defined.

When several extra specifiers are set on a module search query (e.g.,
env:PATH env:LD_LIBRARY_PATH), they act as an AND operation. Which
means modules listed in result are those matching all extra specifiers
defined.

Module specification used as name value for some extra specifier ele-
ments may leverage Advanced module version specifiers syntax. However
if a module version range or list is implied, it is currently resolved
to existing modules. Thus it may not match modulefile definitions tar-
geting modules that do not exist. In addition, module aliases and sym-
bolic versions are not resolved to their target either if set in extra
specifier query or in modulefile definition.

Extra specifier can only be set in a module search context (avail,
whatis and paths sub-commands). An error is raised if used on a module
specification query in another context. An error is also raised if an
unknown extra specifier element is defined in search query.

Module tags
Module tags are piece of information that can be associated to individ-
ual modulefiles. Tags could be purely informational or may lead to spe-
cific 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 module-
file command. Among tags that could be set this way, some have a spe-
cial 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 re-
loaded (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 mod-
ulefile 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, un-
loading, 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 ren-
dering 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 col-
lection.

• super-sticky module: cannot be unloaded unless if the module is re-
loaded 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 su-
per-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. Su-
per-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 designat-
ing module. Variant specification relies on the Advanced module ver-
sion specifiers mechanism.

Once specified, variant's value is transmitted to the evaluating mod-
ulefile which instantiates the variant in the ModuleVariant array vari-
able when reaching the variant modulefile command declaring this vari-
ant. For instance the module load foo/1.2 bar=value1 command leads to
the evaluation of foo/1.2 modulefile with bar=value1 variant specifica-
tion. 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 vari-
ant 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.
Variants specified on module designation are ignored by the is-avail or
path sub-commands. On search sub-commands (avail, whatis and paths),
variants are interpreted and trigger the Extra match search process to
filter results.

When modulefile is evaluated a value should be specified for each vari-
ant this modulefile declares. When reaching the variant modulefile com-
mand 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.

When searching for modules with variants specified in search query, the
Extra match search process triggers a specific scan modulefile evalua-
tion. Variants defined in modulefile are collected during this evalua-
tion then compared to the variants specified in search query. If there
is a match, module is included in search results otherwise it is with-
drawn.

When searching for available modules, if one variant is specified mul-
tiple times, matching modules are those providing all specified variant
values. For instance bar=value1 bar=value2 will return modules defining
a bar variant with value1 and value2 as available values. On a module
selection context, only the last specified value is retained. Which
means on previous example that bar variant is set to value2.

When searching for available modules, multiple values may be set on one
variant criterion, which matches modules that provides any of these
variant values. For instance bar=value1,value2 will return modules
defining a bar variant with either value1 or value2 as available value.

Module variants are reported along the module they are associated to on
list sub-command results. They are also reported on avail sub-command
if specified in search query or added to the element to report in
sub-command output (see --output/-o option).

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 re-
ported with the +name or -name syntaxes on list sub-command or with the
name=on,off syntax on avail sub-command. 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 re-
ported 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.

Extra match search
Extra match search is a mechanism that evaluates available modulefiles
during a module search to find those matching an extra query or to re-
port additional information. After selecting modulefiles that match the
module name and version specified in search query, these remaining mod-
ulefiles are evaluated to collect their content.

Extra match search is available on the following module search sub-com-
mands: avail, whatis and paths.

Extra match search is triggered when:

• Module variants and their available values have to be reported in
avail output (see --output/-o option): extra match search is trig-
gered to collect variant information

• Module variant is specified in search query: extra match search is
triggered to collect variant information then match them against
variant specified in query

• Extra specifier is specified in search query: extra match search is
triggered to collect commands used in modulefiles or modulercs then
match them against extra specifier query

If search query does not contain an extra query and if variant informa-
tion should not be reported, no extra match search is performed. If
search query does not contain any module name and version but contains
an extra query or if variant information should be reported, extra
match search is applied to all available modulefiles.

During this specific evaluation, modulefiles are interpreted in scan
mode. This mode aims to collect the different Tcl modulefile commands
used. Special care should be given when writing modulefiles to ensure
they cope with such evaluation mode.

Modulefiles tagged forbidden are excluded from extra match search eval-
uation. Thus they are excluded from result when this mechanism is trig-
gered.

No scan modulefile evaluation is performed if search query is only com-
posed of tag extra specifier. Module tags are defined in modulercs thus
no modulefile evaluation is required to get tags applying to a module-
file.

As extra match search implies additional modulefile evaluations, it is
advised to build and use Module cache to improve search speed.

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 cur-
rent user environment state in terms of module paths and loaded mod-
ules. By default collections are saved under the $HOME/.module direc-
tory.

$ 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 be-
tween 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 cur-
rent 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-com-
mands 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-com-
mand. This sub-command behavior can be changed with reset_target_state
configuration option to choose to just purge loaded modules or to re-
store a specific collection.

Collection targets
A collection target can be defined for current environment session with
the collection_target configuration option. When set, available collec-
tions 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 col-
lections 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 collec-
tion 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 collec-
tion. 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 collec-
tion 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 /usr/lo-
cal/Modules/5.4.0/etc/siteconfig.tcl.

When modulecmd.tcl is invoked it sources siteconfig script if it ex-
ists. Any global variable or procedure of modulecmd.tcl can be rede-
fined in siteconfig.

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

Hooks
Siteconfig relies on the ability of the Tcl language to overwrite pre-
viously 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 mod-
ulefile 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 proce-
dure by first renaming its original version then creating a new proce-
dure that will add specific code and rely on the renamed original pro-
cedure 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 module-
file 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 module-
file 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 module-
file.

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 con-
text with respectively 1 and some text as value.

modulefile_extra_cmds
List of command and associated local procedure to setup in mod-
ulefile evaluation context. These commands can be called from
the modulefile to execute associated procedure. In case a mod-
ulefile 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 proce-
dures defined in siteconfig script.

modulerc_extra_vars
List of variable names and associated values to setup in mod-
ulerc 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 mod-
ulerc 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 proce-
dures defined in siteconfig script.

Module cache
To improve module search efficiency, a module cache can be setup in
each modulepath. A module cache is represented by a .modulecache file
stored at the root of modulepath directory. This file aggregates con-
tents of all valid modulercs and modulefiles and issue description of
all non-modulefiles stored in modulepath directory.

When cache file is available, a module search analyzes this file rather
walking through the content of modulepath directory to check if files
are modulefiles or not. Cache file reduces module search processing
time especially when hundreds of modulefiles are available and if these
files are located on busy storage systems. Having one file to read per
modulepath rather walking through a whole directory content extremely
reduces the number of required I/O operations.

When modulefiles or directories in the modulepath are not accessible
for everyone, a limited access indication is recorded in cache file
rather content of these modulefiles and content of these directories.
When cache file containing such indication is processed, the limited
access modulefiles are tested to check if they are available to the
current running user. Limited access directories are walked down to
find all available modulefiles and modulercs.

Cache files are generated with cachebuild sub-command. This command has
to be run by someone who owns write access in modulepath directory to
create cache file.

Cache files are used any time a module search occurs in modulepaths.
They are analyzed for instance during avail, load, display or whatis
sub-commands.

Cache files are removed with cacheclear sub-command. This command has
to be run by someone who own write access in modulepath directory to
effectively delete cache file.

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-com-
mand after checking it is not set. It ensures no nested initial-
ization 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 re-
solving 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 pre-
fixed by the as| string if it corresponds to an automatic ver-
sion symbol. These prefixes help to distinguish the different
kind of alternative name.

This environment variable is intended for module command inter-
nal 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 associ-
ated 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 sepa-
rated by the ampersand character.

This environment variable is intended for module command inter-
nal use to get knowledge of the conflicts declared by the loaded
modulefiles in order to keep environment consistent when a con-
flicting module is asked for load afterward.

__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 charac-
ter.

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

__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 inter-
nal use to get knowledge of the initial loaded state after ini-
tialization.

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 collec-
tion 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 sepa-
rated 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 inter-
nal 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 com-
pletion, 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 fol-
lowed 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 mod-
ulefile command (corresponding to the environment changes done
by sourced script) are separated by the pipe character.

This environment variable is intended for module command inter-
nal 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_LMSTICKYRULE
A colon separated list of the sticky or super-sticky tag defini-
tions applying to loaded modulefiles. Each element in this list
starts by the name of the loaded modulefile followed by the
sticky tag name and the module specifications on which the tag
applies. These loaded modulefiles and sticky tag definitions are
separated by the ampersand character. Tag name and module speci-
fications on which it applies are separated by the pipe charac-
ter.

When stickiness applies specifically to the loaded module name
and version, sticky rule is not recorded in __MODULES_LMSTICK-
YRULE.

This environment variable is intended for module command inter-
nal use to get knowledge of the stickiness scope when sticky
module is changed.

__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 am-
persand character.

This environment variable is intended for module command inter-
nal use to get knowledge of the tags applying to loaded module-
files 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 vari-
ants 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 vari-
ant 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 inter-
nal 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 charac-
ter 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 initial-
ization 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 vari-
able and a path-like variable containing an empty string as sin-
gle element.

_LMFILES_
A colon separated list of the full pathname for all loaded mod-
ulefiles.

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 in-
terpretation 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 mod-
ulefiles. Typically, it is set to the main modulefiles direc-
tory, /usr/local/Modules/5.4.0/modulefiles, by the initializa-
tion script. MODULEPATH can be set using module use or by the
module initialization script to search group or personal module-
file directories before or after the main modulefile directory.

Path elements registered in the MODULEPATH environment variable
may contain reference to environment variables which are con-
verted to their corresponding value by module command each time
it looks at the MODULEPATH value. If an environment variable re-
ferred in a path element is not defined, its reference is con-
verted to an empty string.

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

Several global run-command files may be defined in this environ-
ment variable by separating each of them by colon character.

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

MODULES_ABORT_ON_ERROR
A colon separated list of the module sub-commands that abort
their evaluation sequence when an error is raised by an evalu-
ated module. When error occurs, evaluations already done are
withdrawn and the remaining modules to evaluate are skipped.

Accepted sub-commands that can be set in value list are:

• load

• ml

• mod-to-sh

• purge

• reload

• switch

• switch_unload

• try-load

• unload

Module sub-commands not configured to follow the abort on error
behavior, apply the continue on error behavior. In this case if
one modulefile evaluation fails, sequence continues with remain-
ing modulefiles. When --force option is used, continue on error
behavior applies.

This environment variable value supersedes the default value set
in the abort_on_error 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, dis-
able advanced module version specifiers.

This environment variable value supersedes the default value set
in the advanced_version_spec configuration option. It can be de-
fined 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 ig-
nored.

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 re-
quired 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 mod-
ulefile, an unloaded dependent or an unloaded useless require-
ment or declaring a prereq onto a modulefile part of this re-
loading 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 ex-
cluded from the automatic reload actions described above.

For the specific case of the switch sub-command, where a module-
file is unloaded to then load another modulefile. Dependent mod-
ulefiles to Unload are merged into the Dependent modulefiles to
Reload that are reloaded after the load of the switched-to mod-
ulefile.

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-com-
mand. If set to 0 disable avail sub-command in depth mode. Other
values are ignored.

When in depth mode is enabled, modulefiles and directories con-
tained 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 com-
mand 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.

• indesym: symbolic versions reported independently from the
module or directory they are attached to.

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

• variant: variants and their possible values associated with
available modules.

• variantifspec: like variant but only if a variant has been
specified in search query.

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 mod-
ulepaths are reported as a single list.

When indesym element is set, dirwsym and sym elements are dis-
abled.

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 de-
fined with the config sub-command. The --output/-o command line
switches override this environment variable.

MODULES_CACHE_BUFFER_BYTES
Size of the buffer used when reading or writing cache files. Ac-
cepted values are integers comprised between 4096 and 1000000.

MODULES_CACHE_EXPIRY_SECS
Number of seconds a cache file is considered valid after being
generated. For example, if set to 3600 it means a cache file ex-
pires one hour after being generated and is then ignored.

When set to 0 cache file never expires. Accepted values are in-
tegers comprised between 0 (cache files never expire) and
31536000 (equivalent to one year duration).

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 sav-
ing 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 collec-
tion. 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 de-
fined 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 ma-
chines which may use different modules setup. For instance mod-
ules users may access with the same HOME directory multiple sys-
tems 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 col-
lection 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, dnsdo-
mainname, 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 en-
vironment variable or with --color command line switch..

MODULES_COLORS
Specifies the colors and other attributes used to highlight var-
ious 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 in-
formation (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 ap-
plied to a tag name is ignored if an abbreviation is set for
this tag thus the SGR code should be defined for this abbrevia-
tion 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 documenta-
tion 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 con-
catenate include 1 for bold, 4 for underline, 30 to 37 for fore-
ground 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 overrid-
den 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 de-
fault version is returned if it is part of matching modulefiles.
Otherwise the implicit default among matching modulefiles is re-
turned 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 de-
fined 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 sensi-
tiveness 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 al-
ways, a case insensitive match is also applied to the other mod-
ule 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 vari-
able.

MODULES_IGNORE_CACHE
Ignore (if set to 1) or not (if set to 0) module cache.

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

MODULES_IGNORE_USER_RC
Skip evaluation (if set to 1) or not (if set to 0) of user-spe-
cific module rc file ($HOME/.modulerc).

This environment variable value supersedes the default value set
in the ignore_user_rc configuration option. It can be defined
with the config sub-command. The --ignore-user-rc command line
switch overrides 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 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 collec-
tion-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 ex-
plicit 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 ig-
nored 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 en-
abled an implicit conflict requirement onto switched-off module
and a prereq requirement onto switched-on module are also de-
fined 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 de-
fined 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:

• alias: module aliases targeting loaded modules.

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

• indesym: symbolic versions reported independently from the
loaded module they are attached to.

• 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 module-
file 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

When a module cache file is available for a given modulepath,
eval mode is not applied as cache content is generated in always
mode.

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 mod-
ulefile is checked against the current version of modulecmd.tcl
to determine if the modulefile can be evaluated.

When a module cache file is available for a given modulepath,
version check is considered enabled as cache content is gener-
ated in this mode.

This environment variable value supersedes the default value set
in the mcookie_version_check configuration option. It can be de-
fined 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 com-
mand. When a nearly forbidden module is evaluated a warning mes-
sage is issued to inform module will soon be forbidden. If set
to 0, modules will never be considered nearly forbidden. Ac-
cepted 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 de-
fined 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 func-
tion.

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 cur-
rent 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 ini-
trc 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 de-
fined 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 de-
fined 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 defini-
tion.

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

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 de-
fined 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 mod-
ule command or the module shell initialization script. Only ap-
plies 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 de-
fined 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 con-
figuration 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 de-
tails.

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 ig-
nored if extra_siteconfig has been declared locked in
locked_configs configuration option.

MODULES_SOURCE_CACHE
If set to 1, cache content of files evaluated in modulefile
through source(n) Tcl command. When same file is sourced multi-
ple times, cached content is reused rather reading file again.

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

MODULES_STICKY_PURGE
When unloading a sticky or super-sticky module during a module
purge, raise an error or emit a warning message or be silent.

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

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 envi-
ronment 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 render-
ing 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 as-
sociated with the tag and tag name or abbreviation is not dis-
played. When listed in MODULES_TAG_COLOR_NAME environment vari-
able, 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 automati-
cally detected by the module command. Accepted values are inte-
gers 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_UNIQUE_NAME_LOADED
If set to 1, allows only one module loaded per module name. A
conflict is raised when loading a module whose name or alterna-
tive names are shared by an already loaded module.

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

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 de-
fined 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 infor-
mational messages.

• normal: turn on informational messages, like a report of the
additional module evaluations triggered by loading or unload-
ing 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 system-
atic 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, selec-
tions and evaluations.

• debug: print debugging messages about module command execu-
tion.

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

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 contain-
ing module command initialization scripts, the executable pro-
gram 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/local/Modules/5.4.0
The MODULESHOME directory.

/usr/local/Modules/5.4.0/etc/initrc
The configuration file evaluated by modulecmd.tcl when it initial-
izes to enable the default modulepaths, load the default modules and
set module command configuration.

initrc is a modulefile 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 module-
file 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.

/usr/local/Modules/5.4.0/etc/modulespath
The configuration file evaluated by modulecmd.tcl when it initial-
izes 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.

/usr/local/Modules/5.4.0/etc/siteconfig.tcl
The site-specific configuration script of modulecmd.tcl. An addi-
tional configuration script could be defined using the
MODULES_SITECONFIG environment variable. See Site-specific configu-
ration for detailed information.

/usr/local/Modules/5.4.0/etc/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/local/Modules/5.4.0/modulefiles
The directory for system-wide modulefiles. The location of the di-
rectory can be changed using the MODULEPATH environment variable as
described above.

<modulepath>/.modulerc
Modulepath-specific module rc file.

<modulepath>/.modulecache
Modulepath-specific module cache file.

/usr/local/Modules/5.4.0/libexec/modulecmd.tcl
The modulefile interpreter that gets executed upon each invocation
of module.

/usr/local/Modules/5.4.0/init/<shell>
The Modules package initialization file sourced into the user's en-
vironment.

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages