1MODULE(1) Modules MODULE(1)
2
6 module - command interface to the Modules package
7
9 module [switches] [sub-command [sub-command-args]]
10
12 module is a user interface to the Modules package. The Modules package
13 provides for the dynamic modification of the user's environment via
14 modulefiles.
15 Each modulefile contains the information needed to configure the shell
17 for an application. Once the Modules package is initialized, the envi‐
18 ronment can be modified on a per-module basis using the module command
19 which interprets modulefiles. Typically modulefiles instruct the module
20 command to alter or set shell environment variables such as PATH, MAN‐
21 PATH, etc. Modulefiles may be shared by many users on a system and
22 users may have their own set to supplement or replace the shared mod‐
23 ulefiles.
24 The modulefiles are added to and removed from the current environment
26 by the user. The environment changes contained in a modulefile can be
27 summarized through the module command as well. If no arguments are
28 given, a summary of the module usage and sub-commands are shown.
29 The action for the module command to take is described by the sub-com‐
31 mand and its associated arguments.
32 Package Initialization
34 The Modules package and the module command are initialized when a
35 shell-specific initialization script is sourced into the shell. The
36 script executes the autoinit sub-command of the modulecmd.tcl program
37 located in /usr/share/Modules/libexec for the corresponding shell. The
38 output of this execution is evaluated by shell which creates the module
39 command as either an alias or function and creates Modules environment
40 variables.
41 During this initialization process, if the Modules environment is found
43 undefined (when both MODULEPATH and LOADEDMODULES are found either un‐
44 set or empty), the modulespath and initrc configuration files located
45 in /etc/environment-modules are evaluated if present and following this
46 order. modulespath file contains the list of modulepaths to enable dur‐
47 ing initialization. In this file, the modulepaths are separated by new‐
48 line or colon characters. initrc is a modulefile that defines during
49 initialization the modulepaths to enable, the modules to load and the
50 module configuration to apply.
51 During the initialization process, if the Modules environment is found
53 defined a module refresh is automatically applied to restore in the
54 current environment all non-persistent components set by loaded mod‐
55 ules.
56 The module alias or function executes the modulecmd.tcl program and has
58 the shell evaluate the command's output. The first argument to mod‐
59 ulecmd.tcl specifies the type of shell.
60 The initialization scripts are kept in /usr/share/Modules/init/<shell>
62 where <shell> is the name of the sourcing shell. For example, a C Shell
63 user sources the /usr/share/Modules/init/csh script. The sh, csh, tcsh,
64 bash, ksh, zsh, fish and cmd shells are supported by modulecmd.tcl. In
65 addition, python, perl, ruby, tcl, cmake, r and lisp "shells" are sup‐
66 ported which writes the environment changes to stdout as python, perl,
67 ruby, tcl, lisp, r or cmake code.
68 Initialization may also be performed by directly calling the autoinit
70 sub-command of the modulecmd.tcl program.
71 A ml alias or function may also be defined at initialization time if
73 enabled (see MODULES_ML section). ml is a handy frontend leveraging all
74 module command capabilities with less character typed. See ml(1) for
75 detailed information.
76 Examples of initialization
78 C Shell initialization (and derivatives):
79 source /usr/share/Modules/init/csh
81 module load modulefile modulefile ...
82 Bourne Shell (sh) (and derivatives):
84 . /usr/share/Modules/init/sh
86 module load modulefile modulefile ...
87 Perl:
89 require "/usr/share/Modules/init/perl.pm";
91 &module('load', 'modulefile', 'modulefile', '...');
92 Python:
94 import os
96 exec(open('/usr/share/Modules/init/python.py').read())
97 module('load', 'modulefile', 'modulefile', '...')
98 Bourne Shell (sh) (and derivatives) with autoinit sub-command:
100 eval "$(/usr/share/Modules/libexec/modulecmd.tcl sh autoinit)"
102 Modulecmd startup
104 Upon invocation modulecmd.tcl sources a site-specific configuration
105 script if it exists. Siteconfig script is a Tcl script located at
106 /etc/environment-modules/siteconfig.tcl. It enables to supersede any
107 global variable or procedure definition of modulecmd.tcl. See
108 Site-specific configuration for detailed information.
109 Afterward, modulecmd.tcl sources rc files which contain global, user
111 and modulefile specific setups. These files are interpreted as module‐
112 files. See modulefile(4) for detailed information.
113 Upon invocation of modulecmd.tcl module run-command files are sourced
115 in the following order:
116 1. Global RC file as specified by MODULERCFILE variable or /etc/envi‐
118 ronment-modules/rc. If MODULERCFILE points to a directory, the mod‐
119 ulerc file in this directory is used as global RC file.
120 2. User specific module RC file $HOME/.modulerc
122 3. All .modulerc and .version files found during modulefile seeking.
124 These module run-command files must begins like modulefiles with the
126 #%Module file signature, also called the Modules magic cookie. A ver‐
127 sion number may be placed after this string. The version number re‐
128 flects the minimum version of modulecmd.tcl required to interpret the
129 run-command file. If a version number doesn't exist, then modulecmd.tcl
130 will assume the run-command file is compatible. Files without the magic
131 cookie or with a version number greater than the current version of
132 modulecmd.tcl will not be interpreted and an error is reported. Such
133 error does not abort the whole module evaluation. If the
134 mcookie_version_check configuration is disabled the version number set
135 is not checked.
136 NOTE:
138 Run-command files are intended to set parameters for modulefiles,
139 not to configure the module command itself.
140 Command line switches
142 The module command accepts command line switches as its first parame‐
143 ter. These may be used to control output format of all information dis‐
144 played and the module behavior in case of locating and interpreting
145 modulefiles.
146 All switches may be entered either in short or long notation. The fol‐
148 lowing switches are accepted:
149 --all, -a
151 Include hidden modules in search performed with avail, aliases,
152 list, lint, savelist, search or whatis sub-commands. Hard-hidden
153 modules are not affected by this option.
154 --auto Enable automated module handling mode on sub-commands that load
156 or unload modulefiles. See also MODULES_AUTO_HANDLING section.
157 --color=<WHEN>
159 Colorize the output. WHEN defaults to always or can be never or
160 auto. See also MODULES_COLOR section.
161 --contains, -C
163 On avail, list and savelist sub-commands, return modules or col‐
164 lections whose fully qualified name contains search query
165 string.
166 --debug, -D, -DD
168 Debug mode. Causes module to print debugging messages about its
169 progress. Multiple -D options increase the debug verbosity. The
170 maximum is 2.
171 --default, -d
173 On avail sub-command, display only the default version of each
174 module name. Default version is the explicitly set default ver‐
175 sion or also the implicit default version if the configuration
176 option implicit_default is enabled (see Locating Modulefiles
177 section in the modulefile(4) man page for further details on im‐
178 plicit default version).
179 --force, -f
181 On load, unload, switch, load-any, try-load, mod-to-sh and
182 source sub-commands by-pass any unsatisfied modulefile con‐
183 straint corresponding to the declared prereq and conflict. Which
184 means for instance that a modulefile will be loaded even if it
185 comes in conflict with another loaded modulefile or that a mod‐
186 ulefile will be unloaded even if it is required as a prereq by
187 another modulefile.
188 On clear sub-command, skip the confirmation dialog and proceed.
190 On purge sub-command also unload sticky modules and modulefiles
192 that are depended by non-unloadable modules.
193 --help, -h
195 Give some helpful usage information, and terminates the command.
196 --icase, -i
198 Match module specification arguments in a case insensitive man‐
199 ner.
200 --indepth
202 On avail sub-command, include in search results the matching
203 modulefiles and directories and recursively the modulefiles and
204 directories contained in these matching directories.
205 --json, -j
207 Display avail, list, savelist, stashlist, whatis and search out‐
208 put in JSON format.
209 --latest, -L
211 On avail sub-command, display only the highest numerically
212 sorted version of each module name (see Locating Modulefiles
213 section in the modulefile(4) man page).
214 --long, -l
216 Display avail, list, savelist and stashlist output in long for‐
217 mat.
218 --no-auto
220 Disable automated module handling mode on sub-commands that load
221 or unload modulefiles. See also MODULES_AUTO_HANDLING section.
222 --no-indepth
224 On avail sub-command, limit search results to the matching mod‐
225 ulefiles and directories found at the depth level expressed by
226 the search query. Thus modulefiles contained in directories part
227 of the result are excluded.
228 --no-pager
230 Do not pipe message output into a pager.
231 --no-redirect
233 Do not send message output to stdout. Keep it on stderr.
234 --output=LIST, -o LIST
236 Define the content to report in addition to module names. This
237 option is supported by avail and list sub-commands on their reg‐
238 ular or terse output modes. Accepted values are a LIST of ele‐
239 ments to report separated by colon character (:). The order of
240 the elements in LIST does not matter.
241 Accepted elements in LIST for avail sub-command are: modulepath,
243 alias, dirwsym, sym, tag and key.
244 Accepted elements in LIST for list sub-command are: header, idx,
246 variant, sym, tag and key.
247 The order of the elements in LIST does not matter. Module names
249 are the only content reported when LIST is set to an empty
250 value.
251 See also MODULES_AVAIL_OUTPUT and MODULES_LIST_OUTPUT.
253 --paginate
255 Pipe all message output into less (or if set, to the command re‐
256 ferred in MODULES_PAGER variable) if error output stream is a
257 terminal. See also MODULES_PAGER section.
258 --redirect
260 Send message output to stdout instead of stderr. Only supported
261 on sh, bash, ksh, zsh and fish shells.
262 --silent, -s
264 Turn off error, warning and informational messages. module com‐
265 mand output result is not affected by silent mode.
266 --starts-with, -S
268 On avail, list and savelist sub-commands, return modules or col‐
269 lections whose name starts with search query string.
270 --tag=LIST
272 On load, load-any, switch and try-load sub-commands, apply LIST
273 of module tags to the loading modulefile. LIST corresponds to
274 the concatenation of multiple tags separated by colon character
275 (:). LIST should not contain tags inherited from modulefile
276 state or from other modulefile commands. If module is already
277 loaded, tags from LIST are added to the list of tags already ap‐
278 plied to this module.
279 --terse, -t
281 Display avail, list, savelist and stashlist output in short for‐
282 mat.
283 --timer
285 Prints at the end of the output an evaluation of the total exe‐
286 cution time of the module command. When mixed with a single or
287 multiple --debug options, replaces regular debug messages by re‐
288 ports of the execution time of every internal procedure calls.
289 --trace, -T
291 Trace mode. Report details on module searches, resolutions, se‐
292 lections and evaluations in addition to printing verbose mes‐
293 sages.
294 --verbose, -v, -vv
296 Enable verbose messages during module command execution. Multi‐
297 ple -v options increase the verbosity level. The maximum is 2.
298 --version, -V
300 Lists the current version of the module command. The command
301 then terminates without further processing.
302 --width=COLS, -w COLS
304 Set the width of the output to COLS columns. See also
305 MODULES_TERM_WIDTH section.
306 Module Sub-Commands
308 add [options] modulefile...
309 See load.
310 add-any [options] modulefile...
312 See load-any.
313 aliases [-a]
315 List all available symbolic version-names and aliases in the
316 current MODULEPATH. All directories in the MODULEPATH are re‐
317 cursively searched in the same manner than for the avail
318 sub-command. Only the symbolic version-names and aliases found
319 in the search are displayed.
320 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
322 Append value to environment variable. The variable is a colon,
323 or delimiter, separated list. See append-path in the module‐
324 file(4) man page for further explanation.
325 When append-path is called as a module sub-command, the refer‐
327 ence counter variable, which denotes the number of times value
328 has been added to environment variable, is not updated unless if
329 the --duplicates option is set.
330 apropos [-a] [-j] string
332 See search.
333 avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-in‐
335 depth] [pattern...]
336 List all available modulefiles in the current MODULEPATH. All
337 directories in the MODULEPATH are recursively searched for files
338 containing the Modules magic cookie. If a pattern argument is
339 given, then each directory in the MODULEPATH is searched for
340 modulefiles whose pathname, symbolic version-name or alias match
341 pattern in a case insensitive manner by default. pattern may
342 contain wildcard characters. Multiple versions of an applica‐
343 tion can be supported by creating a subdirectory for the appli‐
344 cation containing modulefiles for each version.
345 Symbolic version-names and aliases found in the search are dis‐
347 played in the result of this sub-command. Symbolic version-names
348 are displayed next to the modulefile they are assigned to within
349 parenthesis. Aliases are listed in the MODULEPATH section where
350 they have been defined. To distinguish aliases from modulefiles
351 a @ symbol is added within parenthesis next to their name.
352 Aliases defined through a global or user specific module RC file
353 are listed under the global/user modulerc section.
354 When colored output is enabled and a specific graphical rendi‐
356 tion is defined for module default version, the default symbol
357 is omitted and instead the defined graphical rendition is ap‐
358 plied to the relative modulefile. When colored output is enabled
359 and a specific graphical rendition is defined for module alias,
360 the @ symbol is omitted. The defined graphical rendition applies
361 to the module alias name. See MODULES_COLOR and MODULES_COLORS
362 sections for details on colored output.
363 Module tags applying to the available modulefiles returned by
365 the avail sub-command are reported along the module name they
366 are associated to (see Module tags section).
367 A Key section is added at the end of the output in case some el‐
369 ements are reported in parentheses or chevrons along module name
370 or if some graphical rendition is made over some output ele‐
371 ments. This Key section gives hints on the meaning of such ele‐
372 ments.
373 The parameter pattern may also refer to a symbolic modulefile
375 name or a modulefile alias. It may also leverage a specific syn‐
376 tax to finely select module version (see Advanced module version
377 specifiers section below).
378 clear [-f]
380 Force the Modules package to believe that no modules are cur‐
381 rently loaded. A confirmation is requested if command-line
382 switch -f (or --force) is not passed. Typed confirmation should
383 equal to yes or y in order to proceed.
384 config [--dump-state|name [value]|--reset name]
386 Gets or sets modulecmd.tcl options. Reports the currently set
387 value of passed option name or all existing options if no name
388 passed. If a name and a value are provided, the value of option
389 name is set to value. If command-line switch --reset is passed
390 in addition to a name, overridden value for option name is
391 cleared.
392 When a reported option value differs from default value a men‐
394 tion is added to indicate whether the overridden value is coming
395 from a command-line switch (cmd-line) or from an environment
396 variable (env-var). When a reported option value is locked and
397 cannot be altered a (locked) mention is added.
398 If no value is currently set for an option name, the mention
400 <undef> is reported.
401 When command-line switch --dump-state is passed, current mod‐
403 ulecmd.tcl state and Modules-related environment variables are
404 reported in addition to currently set modulecmd.tcl options.
405 Existing option names are:
407 advanced_version_spec
409 Advanced module version specification to finely select
410 modulefiles.
411 Default value is 1. It can be changed at installation
413 time with --disable-advanced-version-spec option. The
414 MODULES_ADVANCED_VERSION_SPEC environment variable is de‐
415 fined by config sub-command when changing this configura‐
416 tion option from its default value. See
417 MODULES_ADVANCED_VERSION_SPEC description for details.
418 auto_handling
420 Automated module handling mode.
421 Default value is 1. It can be changed at installation
423 time with --disable-auto-handling option. The
424 MODULES_AUTO_HANDLING environment variable is defined by
425 config sub-command when changing this configuration op‐
426 tion from its default value. The --auto and --no-auto
427 command line switches change the value of this configura‐
428 tion option. See MODULES_AUTO_HANDLING description for
429 details.
430 avail_indepth
432 avail sub-command in depth search mode.
433 Default value is 1. It can be changed at installation
435 time with --disable-avail-indepth option. The
436 MODULES_AVAIL_INDEPTH environment variable is defined by
437 config sub-command when changing this configuration op‐
438 tion from its default value. The --indepth and
439 --no-indepth command line switches change the value of
440 this configuration option. See MODULES_AVAIL_INDEPTH de‐
441 scription for details.
442 avail_output
444 Content to report in addition to module names on avail
445 sub-command regular output mode.
446 Default value is modulepath:alias:dirwsym:sym:tag:key. It
448 can be changed at installation time with
449 --with-avail-output option. The MODULES_AVAIL_OUTPUT en‐
450 vironment variable is defined by config sub-command when
451 changing this configuration option from its default
452 value. The --output/-o command line switches change the
453 value of this configuration option. See
454 MODULES_AVAIL_OUTPUT description for details.
455 avail_terse_output
457 Content to report in addition to module names on avail
458 sub-command terse output mode.
459 Default value is modulepath:alias:dirwsym:sym:tag. It can
461 be changed at installation time with
462 --with-avail-terse-output option. The
463 MODULES_AVAIL_TERSE_OUTPUT environment variable is de‐
464 fined by config sub-command when changing this configura‐
465 tion option from its default value. The --output/-o com‐
466 mand line switches change the value of this configuration
467 option. See MODULES_AVAIL_TERSE_OUTPUT description for
468 details.
469 collection_pin_version
471 Register exact modulefile version in collection.
472 Default value is 0. The MODULES_COLLECTION_PIN_VERSION
474 environment variable is defined by config sub-command
475 when changing this configuration option from its default
476 value. See MODULES_COLLECTION_PIN_VERSION description for
477 details.
478 collection_pin_tag
480 Register full tag list applying to modulefiles in collec‐
481 tion.
482 Default value is 0. The MODULES_COLLECTION_PIN_TAG envi‐
484 ronment variable is defined by config sub-command when
485 changing this configuration option from its default
486 value. See MODULES_COLLECTION_PIN_TAG description for de‐
487 tails.
488 collection_target
490 Collection target which is valid for current system.
491 This configuration option is unset by default. The
493 MODULES_COLLECTION_TARGET environment variable is defined
494 by config sub-command when changing this configuration
495 option from its default value. See
496 MODULES_COLLECTION_TARGET description for details.
497 color Colored output mode.
499 Default value is auto. It can be changed at installation
501 time with --disable-color option. The MODULES_COLOR envi‐
502 ronment variable is defined by config sub-command when
503 changing this configuration option from its default
504 value. The --color command line switches changes the
505 value of this configuration option. See MODULES_COLOR de‐
506 scription for details.
507 colors Chosen colors to highlight output items.
509 Default value is
511 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.
512 It can be changed at installation time with
513 --with-dark-background-colors or --with-light-back‐
514 ground-colors options in conjunction with --with-termi‐
515 nal-background. The MODULES_COLORS environment variable
516 is defined by config sub-command when changing this con‐
517 figuration option from its default value. See
518 MODULES_COLORS description for details.
519 contact
521 Modulefile contact address.
522 Default value is root@localhost. The MODULECONTACT envi‐
524 ronment variable is defined by config sub-command when
525 changing this configuration option from its default
526 value. See MODULECONTACT description for details.
527 extended_default
529 Allow partial module version specification.
530 Default value is 1. It can be changed at installation
532 time with --disable-extended-default option. The
533 MODULES_EXTENDED_DEFAULT environment variable is defined
534 by config sub-command when changing this configuration
535 option from its default value. See
536 MODULES_EXTENDED_DEFAULT description for details.
537 editor Text editor command to open modulefile with through edit
539 sub-command.
540 Default value is vi. It can be changed at installation
542 time with --with-editor option. The MODULES_EDITOR envi‐
543 ronment variable is defined by config sub-command when
544 changing this configuration option from its default
545 value. See MODULES_EDITOR description for details.
546 extra_siteconfig
548 Additional site-specific configuration script location.
549 See Site-specific configuration section for details.
550 This configuration option is unset by default. The
552 MODULES_SITECONFIG environment variable is defined by
553 config sub-command when changing this configuration op‐
554 tion from its default value. See MODULES_SITECONFIG de‐
555 scription for details.
556 home Location of Modules package main directory.
558 Default value is /usr/share/Modules. It can be changed at
560 installation time with --prefix or --with-moduleshome op‐
561 tions. The MODULESHOME environment variable is defined by
562 config sub-command when changing this configuration op‐
563 tion from its default value. See MODULESHOME description
564 for details.
565 icase Enable case insensitive match.
567 Default value is search. It can be changed at installa‐
569 tion time with --with-icase option. The MODULES_ICASE en‐
570 vironment variable is defined by config sub-command when
571 changing this configuration option from its default
572 value. The --icase/-i command line switches change the
573 value of this configuration option. See MODULES_ICASE de‐
574 scription for details.
575 ignored_dirs
577 Directories ignored when looking for modulefiles.
578 Default value is CVS RCS SCCS .svn .git .SYNC .sos. The
580 value of this option cannot be altered.
581 implicit_default
583 Set an implicit default version for modules.
584 Default value is 1. It can be changed at installation
586 time with --disable-implicit-default option. The
587 MODULES_IMPLICIT_DEFAULT environment variable is defined
588 by config sub-command when changing this configuration
589 option from its default value. See
590 MODULES_IMPLICIT_DEFAULT description for details.
591 implicit_requirement
593 Implicitly define a requirement onto modules specified on
594 module commands in modulefile.
595 Default value is 1. It can be changed at installation
597 time with --disable-implicit-requirement option. The
598 MODULES_IMPLICIT_REQUIREMENT environment variable is de‐
599 fined by config sub-command when changing this configura‐
600 tion option from its default value. See
601 MODULES_IMPLICIT_REQUIREMENT description for details.
602 list_output
604 Content to report in addition to module names on list
605 sub-command regular output mode.
606 Default value is header:idx:variant:sym:tag:key. It can
608 be changed at installation time with --with-list-output
609 option. The MODULES_LIST_OUTPUT environment variable is
610 defined by config sub-command when changing this configu‐
611 ration option from its default value. The --output/-o
612 command line switches change the value of this configura‐
613 tion option. See MODULES_LIST_OUTPUT description for de‐
614 tails.
615 list_terse_output
617 Content to report in addition to module names on list
618 sub-command terse output mode.
619 Default value is header. It can be changed at installa‐
621 tion time with --with-list-terse-output option. The
622 MODULES_LIST_TERSE_OUTPUT environment variable is defined
623 by config sub-command when changing this configuration
624 option from its default value. The --output/-o command
625 line switches change the value of this configuration op‐
626 tion. See MODULES_LIST_TERSE_OUTPUT description for de‐
627 tails.
628 locked_configs
630 Configuration options that cannot be superseded. All op‐
631 tions referred in locked_configs value are locked, thus
632 their value cannot be altered.
633 This configuration option is set to an empty value by de‐
635 fault. It can be changed at installation time with
636 --with-locked-configs option. The value of this option
637 cannot be altered.
638 mcookie_check
640 Defines if the Modules magic cookie (i.e., #%Module file
641 signature) should be checked to determine if a file is a
642 modulefile.
643 Default value is always. The MODULES_MCOOKIE_CHECK envi‐
645 ronment variable is defined by config sub-command when
646 changing this configuration option from its default
647 value. See MODULES_MCOOKIE_CHECK description for details.
648 mcookie_version_check
650 Defines if the version set in the Modules magic cookie
651 used in modulefile should be checked against the version
652 of modulecmd.tcl to determine if the modulefile could be
653 evaluated or not.
654 Default value is 1. It can be changed at installation
656 time with --disable-mcookie-version-check option. The
657 MODULES_MCOOKIE_VERSION_CHECK environment variable is de‐
658 fined by config sub-command when changing this configura‐
659 tion option from its default value. See
660 MODULES_MCOOKIE_VERSION_CHECK description for details.
661 ml Define ml command at initialization time.
663 Default value is 1. It can be changed at installation
665 time with --disable-ml option. The MODULES_ML environment
666 variable is defined by config sub-command when changing
667 this configuration option from its default value. See
668 MODULES_ML description for details.
669 nearly_forbidden_days
671 Set the number of days a module should be considered
672 nearly forbidden prior reaching its expiry date.
673 Default value is 14. It can be changed at installation
675 time with --with-nearly-forbidden-days option. The
676 MODULES_NEARLY_FORBIDDEN_DAYS environment variable is de‐
677 fined by config sub-command when changing this configura‐
678 tion option from its default value. See
679 MODULES_NEARLY_FORBIDDEN_DAYS description for details.
680 pager Text viewer to paginate message output.
682 Default value is less -eFKRX. It can be changed at in‐
684 stallation time with --with-pager and --with-pager-opts
685 options. The MODULES_PAGER environment variable is de‐
686 fined by config sub-command when changing this configura‐
687 tion option from its default value. See MODULES_PAGER
688 description for details.
689 protected_envvars
691 Prevents any modification of listed environment variables
692 (colon : separator).
693 This configuration option is unset by default. The
695 MODULES_PROTECTED_ENVVARS environment variable is defined
696 by config sub-command when changing this configuration
697 option from its default value. See
698 MODULES_PROTECTED_ENVVARS description for details.
699 quarantine_support
701 Defines if code for quarantine mechanism support should
702 be generated in module shell function definition.
703 Default value is 0. It can be changed at installation
705 time with --enable-quarantine-support option. The
706 MODULES_QUARANTINE_SUPPORT environment variable is de‐
707 fined by config sub-command when changing this configura‐
708 tion option from its default value. See
709 MODULES_QUARANTINE_SUPPORT description for details.
710 rcfile Global run-command file location.
712 This configuration option is unset by default. The
714 MODULERCFILE environment variable is defined by config
715 sub-command when changing this configuration option from
716 its default value. See MODULERCFILE description for de‐
717 tails.
718 redirect_output
720 Control whether or not the output of module command
721 should be redirected from stderr to stdout.
722 Default value is 1. The MODULES_REDIRECT_OUTPUT environ‐
724 ment variable is defined by config sub-command when
725 changing this configuration option from its default
726 value. The --redirect and --no-redirect command line
727 switches change the value of this configuration option.
728 See MODULES_REDIRECT_OUTPUT description for details.
729 reset_target_state
731 Control behavior of reset sub-command. Whether environ‐
732 ment should be purged (__purge__), initial environment
733 (__init__) or a named collection (any other value) should
734 restored.
735 Default value is __init__. The MODULES_RESET_TARGET_STATE
737 environment variable is defined by config sub-command
738 when changing this configuration option from its default
739 value. See MODULES_RESET_TARGET_STATE description for de‐
740 tails.
741 run_quarantine
743 Environment variables to indirectly pass to mod‐
744 ulecmd.tcl.
745 This configuration option is set to an empty value by de‐
747 fault. It can be changed at installation time with
748 --with-quarantine-vars option that sets
749 MODULES_RUN_QUARANTINE. This environment variable is also
750 defined by config sub-command when changing this configu‐
751 ration option. See MODULES_RUN_QUARANTINE description for
752 details.
753 search_match
755 Module search match style.
756 Default value is starts_with. It can be changed at in‐
758 stallation time with --with-search-match option. The
759 MODULES_SEARCH_MATCH environment variable is defined by
760 config sub-command when changing this configuration op‐
761 tion from its default value. The --contains and
762 --starts-with command line switches change the value of
763 this configuration option. See MODULES_SEARCH_MATCH de‐
764 scription for details.
765 set_shell_startup
767 Ensure module command definition by setting shell startup
768 file.
769 Default value is 0. It can be changed at installation
771 time with --enable-set-shell-startup option. The
772 MODULES_SET_SHELL_STARTUP environment variable is defined
773 by config sub-command when changing this configuration
774 option from its default value. See
775 MODULES_SET_SHELL_STARTUP description for details.
776 shells_with_ksh_fpath
778 Ensure module command is defined in ksh when it is
779 started as a sub-shell from the listed shells.
780 This configuration option is set to an empty value by de‐
782 fault. The MODULES_SHELLS_WITH_KSH_FPATH environment
783 variable is defined by config sub-command when changing
784 this configuration option from its default value. See
785 MODULES_SHELLS_WITH_KSH_FPATH description for details.
786 silent_shell_debug
788 Disablement of shell debugging property for the module
789 command. Also defines if code to silence shell debugging
790 property should be generated in module shell function
791 definition.
792 Default value is 0. It can be changed at installation
794 time with --enable-silent-shell-debug-support option. The
795 MODULES_SILENT_SHELL_DEBUG environment variable is de‐
796 fined by config sub-command when changing this configura‐
797 tion option from its default value. See
798 MODULES_SILENT_SHELL_DEBUG description for details.
799 siteconfig
801 Primary site-specific configuration script location. See
802 Site-specific configuration section for details.
803 Default value is /etc/environment-modules/siteconfig.tcl.
805 It can be changed at installation time with --prefix or
806 --etcdir options. The value of this option cannot be al‐
807 tered.
808 tag_abbrev
810 Abbreviations to use to report module tags.
811 Default value is auto-loaded=aL:loaded=L:hidden=H:hid‐
813 den-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:su‐
814 per-sticky=sS:keep-loaded=kL. It can be changed at in‐
815 stallation time with --with-tag-abbrev option. The
816 MODULES_TAG_ABBREV environment variable is defined by
817 config sub-command when changing this configuration op‐
818 tion from its default value. See MODULES_TAG_ABBREV de‐
819 scription for details.
820 tag_color_name
822 Tags whose name should be colored instead of module name.
823 This configuration option is set to an empty value by de‐
825 fault. It can be changed at installation time with
826 --with-tag-color-name option. The MODULES_TAG_COLOR_NAME
827 environment variable is defined by config sub-command
828 when changing this configuration option from its default
829 value. See MODULES_TAG_COLOR_NAME description for de‐
830 tails.
831 tcl_ext_lib
833 Modules Tcl extension library location.
834 Default value is @libdir@/libtclenvmodules.so. It can be
836 changed at installation time with --prefix or --libdir
837 options. The value of this option cannot be altered.
838 tcl_linter
840 Command to check syntax of modulefiles with through lint
841 sub-command.
842 Default value is nagelfar.tcl. It can be changed at in‐
844 stallation time with --with-tcl-linter and
845 --with-tcl-linter-opts options. The MODULES_TCL_LINTER
846 environment variable is defined by config sub-command
847 when changing this configuration option from its default
848 value. See MODULES_TCL_LINTER description for details.
849 term_background
851 Terminal background color kind.
852 Default value is dark. It can be changed at installation
854 time with --with-terminal-background option. The
855 MODULES_TERM_BACKGROUND environment variable is defined
856 by config sub-command when changing this configuration
857 option from its default value. See
858 MODULES_TERM_BACKGROUND description for details.
859 term_width
861 Set the width of the output.
862 Default value is 0. The MODULES_TERM_WIDTH environment
864 variable is defined by config sub-command when changing
865 this configuration option from its default value. The
866 --width/-w command line switches change the value of this
867 configuration option. See MODULES_TERM_WIDTH description
868 for details.
869 unload_match_order
871 Unload firstly loaded or lastly loaded module matching
872 request.
873 Default value is returnlast. It can be changed at instal‐
875 lation time with --with-unload-match-order option. The
876 MODULES_UNLOAD_MATCH_ORDER environment variable is de‐
877 fined by config sub-command when changing this configura‐
878 tion option from its default value. See
879 MODULES_UNLOAD_MATCH_ORDER description for details.
880 variant_shortcut
882 Shortcut characters that could be used to specify or re‐
883 port module variants.
884 This configuration option is set to an empty value by de‐
886 fault. It can be changed at installation time with
887 --with-variant-shortcut option. The
888 MODULES_VARIANT_SHORTCUT environment variable is defined
889 by config sub-command when changing this configuration
890 option from its default value. See
891 MODULES_VARIANT_SHORTCUT description for details.
892 verbosity
894 Module command verbosity level.
895 Default value is normal. It can be changed at installa‐
897 tion time with --with-verbosity option. The
898 MODULES_VERBOSITY environment variable is defined by
899 config sub-command when changing this configuration op‐
900 tion from its default value. The --debug/-D, --silent/-s,
901 --trace/-T and --verbose/-v command line switches change
902 the value of this configuration option. See
903 MODULES_VERBOSITY description for details.
904 wa_277 Workaround for Tcsh history issue.
906 Default value is 0. It can be changed at installation
908 time with --enable-wa-277 option. The MODULES_WA_277 en‐
909 vironment variable is defined by config sub-command when
910 changing this configuration option from its default
911 value. See MODULES_WA_277 description for details.
912 display modulefile...
914 Display information about one or more modulefiles. The display
915 sub-command will list the full path of the modulefile and the
916 environment changes the modulefile will make if loaded. (Note:
917 It will not display any environment changes found within condi‐
918 tional statements.)
919 The parameter modulefile may also be a symbolic modulefile name
921 or a modulefile alias. It may also leverage a specific syntax to
922 finely select module version (see Advanced module version speci‐
923 fiers section below).
924 edit modulefile
926 Open modulefile for edition with text editor command designated
927 by the editor configuration option.
928 The parameter modulefile may also be a symbolic modulefile name
930 or a modulefile alias. It may also leverage a specific syntax to
931 finely select module version (see Advanced module version speci‐
932 fiers section below).
933 help [modulefile...]
935 Print the usage of each sub-command. If an argument is given,
936 print the Module-specific help information for the modulefile.
937 The parameter modulefile may also be a symbolic modulefile name
939 or a modulefile alias. It may also leverage a specific syntax to
940 finely select module version (see Advanced module version speci‐
941 fiers section below).
942 info-loaded modulefile
944 Returns the names of currently loaded modules matching passed
945 modulefile. Returns an empty string if passed modulefile does
946 not match any loaded modules. See module-info loaded in the mod‐
947 ulefile(4) man page for further explanation.
948 initadd modulefile...
950 Add modulefile to the shell's initialization file in the user's
951 home directory. The startup files checked (in order) are:
952 C Shell
954 .modules, .cshrc, .csh_variables and .login
955 TENEX C Shell
957 .modules, .tcshrc, .cshrc, .csh_variables and .login
958 Bourne and Korn Shells
960 .modules, .profile
961 GNU Bourne Again Shell
963 .modules, .bash_profile, .bash_login, .profile and .bashrc
964 Z Shell
966 .modules, .zshrc, .zshenv and .zlogin
967 Friendly Interactive Shell
969 .modules, .config/fish/config.fish
970 If a module load line is found in any of these files, the mod‐
972 ulefiles are appended to any existing list of modulefiles. The
973 module load line must be located in at least one of the files
974 listed above for any of the init sub-commands to work properly.
975 If the module load line is found in multiple shell initializa‐
976 tion files, all of the lines are changed.
977 initclear
979 Clear all of the modulefiles from the shell's initialization
980 files.
981 initlist
983 List all of the modulefiles loaded from the shell's initializa‐
984 tion file.
985 initprepend modulefile...
987 Does the same as initadd but prepends the given modules to the
988 beginning of the list.
989 initrm modulefile...
991 Remove modulefile from the shell's initialization files.
992 initswitch modulefile1 modulefile2
994 Switch modulefile1 with modulefile2 in the shell's initializa‐
995 tion files.
996 is-avail modulefile...
998 Returns a true value if any of the listed modulefiles exists in
999 enabled MODULEPATH. Returns a false value otherwise. See
1000 is-avail in the modulefile(4) man page for further explanation.
1001 The parameter modulefile may also be a symbolic modulefile name
1003 or a modulefile alias. It may also leverage a specific syntax to
1004 finely select module version (see Advanced module version speci‐
1005 fiers section below).
1006 is-loaded [modulefile...]
1008 Returns a true value if any of the listed modulefiles has been
1009 loaded or if any modulefile is loaded in case no argument is
1010 provided. Returns a false value otherwise. See is-loaded in the
1011 modulefile(4) man page for further explanation.
1012 The parameter modulefile may also be a symbolic modulefile name
1014 or a modulefile alias. It may also leverage a specific syntax to
1015 finely select module version (see Advanced module version speci‐
1016 fiers section below).
1017 is-saved [collection...]
1019 Returns a true value if any of the listed collections exists or
1020 if any collection exists in case no argument is provided. Re‐
1021 turns a false value otherwise. See is-saved in the modulefile(4)
1022 man page for further explanation.
1023 is-used [directory...]
1025 Returns a true value if any of the listed directories has been
1026 enabled in MODULEPATH or if any directory is enabled in case no
1027 argument is provided. Returns a false value otherwise. See
1028 is-used in the modulefile(4) man page for further explanation.
1029 keyword [-a] [-j] string
1031 See search.
1032 lint [-a] [modulefile...]
1034 Analyze syntax of one or more modulefiles with the linter com‐
1035 mand designated by the tcl_linter configuration option.
1036 The parameter modulefile may also be a symbolic modulefile name
1038 or a modulefile alias. It may also leverage a specific syntax to
1039 finely select module version (see Advanced module version speci‐
1040 fiers section below).
1041 If no modulefile is specified, all the modulefiles and modulerc
1043 available in enabled modulepaths are analyzed as well as global
1044 and user rc files. Hidden modulefiles are also analyzed when
1045 --all/-a option is set.
1046 When nagelfar.tcl is the selected linter command, a static Tcl
1048 syntax analysis is performed. In addition, syntax of modulefile
1049 commands are checked in these files based on their kind
1050 (global/user rc, modulerc or modulefile).
1051 list [-t|-l|-j] [-a] [-o LIST] [-S|-C] [pattern...]
1053 List loaded modules. If a pattern is given, then the loaded mod‐
1054 ules are filtered to only list those whose name matches this
1055 pattern. It may contain wildcard characters. pattern is matched
1056 in a case insensitive manner by default. If multiple patterns
1057 are given, loaded module has to match at least one of them to be
1058 listed.
1059 Module tags applying to the loaded modules are reported along
1061 the module name they are associated to (see Module tags sec‐
1062 tion).
1063 Module variants selected on the loaded modules are reported
1065 along the module name they belong to (see Module variants sec‐
1066 tion).
1067 A Key section is added at the end of the output in case some el‐
1069 ements are reported in parentheses or chevrons along module name
1070 or if some graphical rendition is made over some output ele‐
1071 ments. This Key section gives hints on the meaning of such ele‐
1072 ments.
1073 The parameter pattern may also refer to a symbolic modulefile
1075 name or a modulefile alias. It may also leverage a specific syn‐
1076 tax to finely select module version (see Advanced module version
1077 specifiers section below).
1078 load [options] modulefile...
1080 Load modulefile into the shell environment.
1081 load command accepts the following options:
1083 • --auto|--no-auto
1085 • -f|--force
1087 • --tag=taglist
1089 Once loaded, the loaded module tag is associated to the loaded
1091 module. If module has been automatically loaded by another mod‐
1092 ule, the auto-loaded tag is associated instead (see Module tags
1093 section).
1094 The parameter modulefile may also be a symbolic modulefile name
1096 or a modulefile alias. It may also leverage a specific syntax to
1097 finely select module version (see Advanced module version speci‐
1098 fiers section below).
1099 The --tag option accepts a list of module tags to apply to mod‐
1101 ulefile once loaded. If module is already loaded, tags from
1102 taglist are added to the list of tags already applied to this
1103 module.
1104 load-any [options] modulefile...
1106 Load into the shell environment one of the modulefile specified.
1107 Try to load each modulefile specified in list from the left to
1108 the right until one got loaded or is found already loaded. Do
1109 not complain if modulefile cannot be found but if its evaluation
1110 fails an error is reported.
1111 load-any command accepts the following options:
1113 • --auto|--no-auto
1115 • -f|--force
1117 • --tag=taglist
1119 Once loaded, the loaded module tag is associated to the loaded
1121 module. If module has been automatically loaded by another mod‐
1122 ule, the auto-loaded tag is associated instead (see Module tags
1123 section).
1124 The parameter modulefile may also be a symbolic modulefile name
1126 or a modulefile alias. It may also leverage a specific syntax to
1127 finely select module version (see Advanced module version speci‐
1128 fiers section below).
1129 The --tag option accepts a list of module tags to apply to mod‐
1131 ulefile once loaded. If module is already loaded, tags from
1132 taglist are added to the list of tags already applied to this
1133 module.
1134 mod-to-sh [options] shell modulefile...
1136 Evaluate modulefile and report resulting environment changes as
1137 code for shell.
1138 mod-to-sh command accepts the following options:
1140 • --auto|--no-auto
1142 • -f|--force
1144 An attempt to load modulefile is made to get its environment
1146 changes. This evaluation does not change the current shell envi‐
1147 ronment. Like for load sub-command, no evaluation occurs if mod‐
1148 ulefile is found loaded in current environment.
1149 Changes made on environment variable intended for Modules pri‐
1151 vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig‐
1152 nored.
1153 Shell could be any shell name supported by modulecmd.tcl.
1155 Produced shell code is returned on the message output channel by
1157 modulecmd.tcl. Thus it is not rendered in current environment by
1158 the module shell function.
1159 mod-to-sh automatically set verbosity to the silent mode, to
1161 avoid messages to mix with the produced shell code. Verbosity is
1162 not changed if set to the trace mode or any higher debugging
1163 level.
1164 The parameter modulefile may also be a symbolic modulefile name
1166 or a modulefile alias. It may also leverage a specific syntax to
1167 finely select module version (see Advanced module version speci‐
1168 fiers section below).
1169 path modulefile
1171 Print path to modulefile.
1172 The parameter modulefile may also be a symbolic modulefile name
1174 or a modulefile alias. It may also leverage a specific syntax to
1175 finely select module version (see Advanced module version speci‐
1176 fiers section below).
1177 paths modulefile
1179 Print path of available modulefiles matching argument.
1180 The parameter modulefile may also be a symbolic modulefile name
1182 or a modulefile alias. It may also leverage a specific syntax to
1183 finely select module version (see Advanced module version speci‐
1184 fiers section below).
1185 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
1187 value...
1188 Prepend value to environment variable. The variable is a colon,
1189 or delimiter, separated list. See prepend-path in the module‐
1190 file(4) man page for further explanation.
1191 When prepend-path is called as a module sub-command, the refer‐
1193 ence counter variable, which denotes the number of times value
1194 has been added to environment variable, is not updated unless if
1195 the --duplicates option is set.
1196 purge [-f]
1198 Unload all loaded modulefiles.
1199 When the --force option is set, also unload sticky modules and
1201 modulefiles that are depended by non-unloadable modules.
1202 refresh
1204 Force a refresh of all non-persistent components of currently
1205 loaded modules. This should be used on derived shells where
1206 shell completions, shell aliases or shell functions need to be
1207 reinitialized but the environment variables have already been
1208 set by the currently loaded modules.
1209 Loaded modules are evaluated in refresh mode following their
1211 load order. In this evaluation mode only the complete,
1212 set-alias and set-function modulefile commands will produce en‐
1213 vironment changes. Other modulefile commands that produce envi‐
1214 ronment changes (like setenv or append-path) are ignored during
1215 a refresh evaluation as their changes should already be applied.
1216 Only the loaded modules defining non-persistent environment
1218 changes are evaluated in refresh mode. Such loaded modules are
1219 listed in the __MODULES_LMREFRESH environment variable.
1220 reload Unload then load all loaded modulefiles.
1222 No unload then load is performed and an error is returned if the
1224 loaded modulefiles have unsatisfied constraint corresponding to
1225 the prereq and conflict they declare.
1226 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
1228 Remove value from the colon, or delimiter, separated list in en‐
1229 vironment variable. See remove-path in the modulefile(4) man
1230 page for further explanation.
1231 When remove-path is called as a module sub-command, the refer‐
1233 ence counter variable, which denotes the number of times value
1234 has been added to environment variable, is ignored and value is
1235 removed whatever the reference counter value set.
1236 reset Restore initial environment, which corresponds to the loaded
1238 state after Modules initialization.
1239 reset sub-command restores the environment definition found in
1241 __MODULES_LMINIT environment variable.
1242 reset behavior can be changed with reset_target_state. This
1244 configuration option is set by default to __init__, which corre‐
1245 sponds to the above behavior description. When set to __purge__,
1246 reset performs a purge of the environment. When set to any other
1247 value, reset performs a restore of corresponding name collec‐
1248 tion.
1249 restore [collection]
1251 Restore the environment state as defined in collection. If col‐
1252 lection name is not specified, then it is assumed to be the de‐
1253 fault collection if it exists, __init__ special collection oth‐
1254 erwise. If collection is a fully qualified path, it is restored
1255 from this location rather than from a file under the user's col‐
1256 lection directory. If MODULES_COLLECTION_TARGET is set, a suffix
1257 equivalent to the value of this variable is appended to the col‐
1258 lection file name to restore.
1259 If collection name is __init__, initial environment state de‐
1261 fined in __MODULES_LMINIT environment variable is restored.
1262 When restoring a collection, the currently set MODULEPATH direc‐
1264 tory list and the currently loaded modulefiles are unused and
1265 unloaded then used and loaded to exactly match the MODULEPATH
1266 and loaded modulefiles lists saved in this collection file. The
1267 order of the paths and modulefiles set in collection is pre‐
1268 served when restoring. It means that currently loaded modules
1269 are unloaded to get the same LOADEDMODULES root than collection
1270 and currently used module paths are unused to get the same
1271 MODULEPATH root. Then missing module paths are used and missing
1272 modulefiles are loaded.
1273 If a module, without a default version explicitly defined, is
1275 recorded in a collection by its bare name: loading this module
1276 when restoring the collection will fail if the configuration op‐
1277 tion implicit_default is disabled.
1278 rm [--auto|--no-auto] [-f] modulefile...
1280 See unload.
1281 save [collection]
1283 Record the currently set MODULEPATH directory list and the cur‐
1284 rently loaded modulefiles in a collection file under the user's
1285 collection directory $HOME/.module. If collection name is not
1286 specified, then it is assumed to be the default collection. If
1287 collection is a fully qualified path, it is saved at this loca‐
1288 tion rather than under the user's collection directory.
1289 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1291 value of this variable will be appended to the collection file
1292 name.
1293 By default, if a loaded modulefile corresponds to the explicitly
1295 defined default module version, the bare module name is
1296 recorded. If the configuration option implicit_default is en‐
1297 abled, the bare module name is also recorded for the implicit
1298 default module version. If MODULES_COLLECTION_PIN_VERSION is set
1299 to 1, module version is always recorded even if it is the de‐
1300 fault version.
1301 By default, only the module tags specifically set with the --tag
1303 option or resulting from a specific module state (like
1304 auto-loaded and keep-loaded tags) are recorded in collection. If
1305 MODULES_COLLECTION_PIN_TAG is set to 1, all tags are recorded in
1306 collection except nearly-forbidden tag.
1307 No collection is recorded and an error is returned if the loaded
1309 modulefiles have unsatisfied constraint corresponding to the
1310 prereq and conflict they declare.
1311 savelist [-t|-l|-j] [-a] [-S|-C] [pattern...]
1313 List collections that are currently saved under the user's col‐
1314 lection directory. If MODULES_COLLECTION_TARGET is set, only
1315 collections matching the target suffix will be displayed unless
1316 if the --all/-a option is set.
1317 If a pattern is given, then the collections are filtered to only
1319 list those whose name matches this pattern. It may contain wild‐
1320 card characters. pattern is matched in a case insensitive man‐
1321 ner by default. If multiple patterns are given, collection has
1322 to match at least one of them to be listed.
1323 Stash collections are not listed unless if the --all/-a option
1325 is set. Stash collections can be listed with stashlist sub-com‐
1326 mand.
1327 saverm [collection]
1329 Delete the collection file under the user's collection direc‐
1330 tory. If collection name is not specified, then it is assumed to
1331 be the default collection. If MODULES_COLLECTION_TARGET is set,
1332 a suffix equivalent to the value of this variable will be ap‐
1333 pended to the collection file name.
1334 saveshow [collection]
1336 Display the content of collection. If collection name is not
1337 specified, then it is assumed to be the default collection if it
1338 exists, __init__ special collection otherwise. If collection is
1339 a fully qualified path, this location is displayed rather than a
1340 collection file under the user's collection directory. If
1341 MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1342 value of this variable will be appended to the collection file
1343 name.
1344 If collection name is __init__, initial environment content de‐
1346 fined in __MODULES_LMINIT environment variable is displayed.
1347 search [-a] [-j] string
1349 Seeks through the module-whatis information of all modulefiles
1350 for the specified string. All module-whatis information matching
1351 the string in a case insensitive manner will be displayed.
1352 string may contain wildcard characters.
1353 sh-to-mod shell script [arg...]
1355 Evaluate with shell the designated script with defined arguments
1356 to find out the environment changes it does. Environment prior
1357 and after script evaluation are compared to determine these
1358 changes. They are translated into modulefile commands to output
1359 the modulefile content equivalent to the evaluation of shell
1360 script.
1361 Changes on environment variables, shell aliases, shell func‐
1363 tions, shell completions and current working directory are
1364 tracked.
1365 Changes made on environment variable intended for Modules pri‐
1367 vate use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ig‐
1368 nored.
1369 Shell could be specified as a command name or a fully qualified
1371 pathname. The following shells are supported: sh, dash, csh,
1372 tcsh, bash, ksh, ksh93, zsh and fish.
1373 show modulefile...
1375 See display.
1376 source [options] modulefile...
1378 Execute modulefile into the shell environment. Once executed
1379 modulefile is not marked loaded in shell environment which dif‐
1380 fer from load sub-command.
1381 source command accepts the following options:
1383 • --auto|--no-auto
1385 • -f|--force
1387 If modulefile corresponds to a fully qualified path, this file
1389 is executed. Otherwise modulefile is searched among the avail‐
1390 able modulefiles.
1391 The parameter modulefile may also be a symbolic modulefile name
1393 or a modulefile alias. It may also leverage a specific syntax to
1394 finely select module version (see Advanced module version speci‐
1395 fiers section below).
1396 stash Save current environment in a stash collection then reset to
1398 initial environment.
1399 A collection is created only if current environment state dif‐
1401 fers from initial environment. Stash collection is named
1402 stash-<unix_millis_timestamp> where <unix_millis_timestamp> is
1403 the number of milliseconds between Unix Epoch and when this com‐
1404 mand is run.
1405 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1407 value of this variable will be appended to the stash collection
1408 file name.
1409 stashclear
1411 Remove all stash collection files of current collection_target.
1412 If no collection target is currently set, remove stash collec‐
1413 tion files without a target suffix.
1414 stashlist [-t|-l|-j]
1416 List all stash collection files of current collection_target. If
1417 no collection target is currently set, list stash collection
1418 files without a target suffix.
1419 stashpop [stash]
1421 Restore stash collection then delete corresponding collection
1422 file.
1423 stash is either a full stash collection name (i.e.,
1425 stash-<unix_millis_timestamp>) or a stash index. Most recent
1426 stash collection has index 0, 1 is the one before it. When no
1427 stash is given the latest stash collection is assumed (that is
1428 stash index 0).
1429 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1431 value of this variable will be appended to the stash collection
1432 file name to restore.
1433 stashrm [stash]
1435 Remove stash collection file.
1436 stash is either a full stash collection name (i.e.,
1438 stash-<unix_millis_timestamp>) or a stash index. Most recent
1439 stash collection has index 0, 1 is the one before it. When no
1440 stash is given the latest stash collection is assumed (that is
1441 stash index 0).
1442 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1444 value of this variable will be appended to the stash collection
1445 file name to delete.
1446 stashshow [stash]
1448 Display the content of stash collection file.
1449 stash is either a full stash collection name (i.e.,
1451 stash-<unix_millis_timestamp>) or a stash index. Most recent
1452 stash collection has index 0, 1 is the one before it. When no
1453 stash is given the latest stash collection is assumed (that is
1454 stash index 0).
1455 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
1457 value of this variable will be appended to the stash collection
1458 file name to display.
1459 state [name]
1461 Gets modulecmd.tcl states. Reports the currently set value of
1462 passed state name or all existing states if no name passed.
1463 swap [options] [modulefile1] modulefile2
1465 See switch.
1466 switch [options] [modulefile1] modulefile2
1468 Switch loaded modulefile1 with modulefile2. If modulefile1 is
1469 not specified, then it is assumed to be the currently loaded
1470 module with the same root name as modulefile2.
1471 switch command accepts the following options:
1473 • --auto|--no-auto
1475 • -f|--force
1477 • --tag=taglist
1479 The parameter modulefile may also be a symbolic modulefile name
1481 or a modulefile alias. It may also leverage a specific syntax to
1482 finely select module version (see Advanced module version speci‐
1483 fiers section below).
1484 The --tag option accepts a list of module tags to apply to mod‐
1486 ulefile once loaded. If module is already loaded, tags from
1487 taglist are added to the list of tags already applied to this
1488 module.
1489 test modulefile...
1491 Execute and display results of the Module-specific tests for the
1492 modulefile.
1493 The parameter modulefile may also be a symbolic modulefile name
1495 or a modulefile alias. It may also leverage a specific syntax to
1496 finely select module version (see Advanced module version speci‐
1497 fiers section below).
1498 try-add [options] modulefile...
1500 See try-load.
1501 try-load [options] modulefile...
1503 Like load sub-command, load modulefile into the shell environ‐
1504 ment, but do not complain if modulefile cannot be found. If mod‐
1505 ulefile is found but its evaluation fails, error is still re‐
1506 ported.
1507 try-load command accepts the following options:
1509 • --auto|--no-auto
1511 • -f|--force
1513 • --tag=taglist
1515 Once loaded, the loaded module tag is associated to the loaded
1517 module. If module has been automatically loaded by another mod‐
1518 ule, the auto-loaded tag is associated instead (see Module tags
1519 section).
1520 The parameter modulefile may also be a symbolic modulefile name
1522 or a modulefile alias. It may also leverage a specific syntax to
1523 finely select module version (see Advanced module version speci‐
1524 fiers section below).
1525 The --tag option accepts a list of module tags to apply to mod‐
1527 ulefile once loaded. If module is already loaded, tags from
1528 taglist are added to the list of tags already applied to this
1529 module.
1530 unload [--auto|--no-auto] [-f] modulefile...
1532 Remove modulefile from the shell environment.
1533 The parameter modulefile may also be a symbolic modulefile name
1535 or a modulefile alias. It may also leverage a specific syntax to
1536 finely select module version (see Advanced module version speci‐
1537 fiers section below).
1538 unuse directory...
1540 Remove one or more directories from the MODULEPATH environment
1541 variable.
1542 If module unuse is called during a modulefile evaluation, the
1544 reference counter environment variable
1545 __MODULES_SHARE_MODULEPATH, which denotes the number of times
1546 directory has been enabled, is checked and directory is removed
1547 only if its relative counter is equal to 1 or not defined. Oth‐
1548 erwise directory is kept and reference counter is decreased by
1549 1. When module unuse is called from the command-line or within
1550 an initialization modulefile script directory is removed what‐
1551 ever the reference counter value set.
1552 If directory corresponds to the concatenation of multiple paths
1554 separated by colon character, each path is treated separately.
1555 use [-a|--append] directory...
1557 Prepend one or more directories to the MODULEPATH environment
1558 variable. The --append flag will append the directory to
1559 MODULEPATH.
1560 When directory is already defined in MODULEPATH, it is not added
1562 again or moved at the end or at the beginning of the environment
1563 variable.
1564 If module use is called during a modulefile evaluation, the ref‐
1566 erence counter environment variable __MODULES_SHARE_MODULEPATH
1567 is also set to increase the number of times directory has been
1568 added to MODULEPATH. Reference counter is not updated when
1569 module use is called from the command-line or within an initial‐
1570 ization modulefile script.
1571 A directory that does not exist yet can be specified as argument
1573 and then be added to MODULEPATH.
1574 whatis [-a] [-j] [modulefile...]
1576 Display the information set up by the module-whatis commands in‐
1577 side the specified modulefiles. These specified modulefiles may
1578 be expressed using wildcard characters. If no modulefile is
1579 specified, all module-whatis lines will be shown.
1580 The parameter modulefile may also be a symbolic modulefile name
1582 or a modulefile alias. It may also leverage a specific syntax to
1583 finely select module version (see Advanced module version speci‐
1584 fiers section below).
1585 Modulefiles
1587 modulefiles are written in the Tool Command Language (Tcl) and are in‐
1588 terpreted by modulecmd.tcl. modulefiles can use conditional statements.
1589 Thus the effect a modulefile will have on the environment may change
1590 depending upon the current state of the environment.
1591 Environment variables are unset when unloading a modulefile. Thus, it
1593 is possible to load a modulefile and then unload it without having the
1594 environment variables return to their prior state.
1595 Advanced module version specifiers
1597 When the advanced module version specifiers mechanism is enabled (see
1598 MODULES_ADVANCED_VERSION_SPEC), the specification of modulefile passed
1599 on Modules sub-commands changes. After the module name a version con‐
1600 straint and variants may be added.
1601 Version specifiers
1603 After the module name a version constraint prefixed by the @ character
1604 may be added. It could be directly appended to the module name or sepa‐
1605 rated from it with a space character.
1606 Constraints can be expressed to refine the selection of module version
1608 to:
1609 • a single version with the @version syntax, for instance foo@1.2.3
1611 syntax will select module foo/1.2.3
1612 • a list of versions with the @version1,version2,... syntax, for in‐
1614 stance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
1615 • a range of versions with the @version1:, @:version2 and @ver‐
1617 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
1618 sions of module foo greater than or equal to 1.2, foo@:1.3 will se‐
1619 lect all versions less than or equal to 1.3 and foo@1.2:1.3 matches
1620 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
1621 Advanced specification of single version or list of versions may bene‐
1623 fit from the activation of the extended default mechanism (see
1624 MODULES_EXTENDED_DEFAULT) to use an abbreviated notation like @1 to re‐
1625 fer to more precise version numbers like 1.2.3. Range of versions on
1626 its side natively handles abbreviated versions.
1627 In order to be specified in a range of versions or compared to a range
1629 of versions, the version major element should corresponds to a number.
1630 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
1631 whereas default or foo.2 versions are invalid for range comparison.
1632 Range of versions can be specified in version list, for instance
1634 foo@:1.2,1.4:1.6,1.8:. Such specification helps to exclude specific
1635 versions, like versions 1.3 and 1.7 in previous example.
1636 If the implicit default mechanism is also enabled (see
1638 MODULES_IMPLICIT_DEFAULT), a default and latest symbolic versions are
1639 automatically defined for each module name (also at each directory
1640 level for deep modulefiles). These automatic version symbols are de‐
1641 fined unless a symbolic version, alias, or regular module version al‐
1642 ready exists for these default or latest version names. Using the
1643 mod@latest (or mod/latest) syntax ensures highest available version
1644 will be selected.
1645 The symbolic version loaded may be used over loaded module name to des‐
1647 ignate the loaded version of the module with associated selected vari‐
1648 ants. This version symbol should be specified using the @ prefix nota‐
1649 tion (e.g., foo@loaded). An error is returned if no version of desig‐
1650 nated module is currently loaded.
1651 Variants
1653 After the module name, variants can be specified. Module variants are
1654 alternative evaluation of the same modulefile. A variant is specified
1655 by associating a value to its name. This specification is then trans‐
1656 mitted to the evaluating modulefile which instantiates the variant in
1657 the ModuleVariant array variable when reaching the variant modulefile
1658 command declaring this variant.
1659 Variant can be specified with the name=value syntax where name is the
1661 declared variant name and value, the value this variant is set to when
1662 evaluating the modulefile.
1663 Boolean variants can be specified with the +name syntax to set this
1665 variant on and with the -name or ~name syntaxes to set this variant
1666 off. The -name syntax is not supported on ml(1) command as the minus
1667 sign already means to unload designated module. The ~name and +name
1668 syntaxes could also be defined appended to another specification word
1669 (e.g., the module name, version or another variant specification),
1670 whereas -name syntax must be the start of a new specification word.
1671 Boolean variants may also be specified with the name=value syntax.
1673 value should be set to 1, true, t, yes, y or on to enable the variant
1674 or it should be set to 0, false, f, no, n or off to disable the vari‐
1675 ant.
1676 Shortcuts may be used to abbreviate variant specification. The
1678 variant_shortcut configuration option associates shortcut character to
1679 variant name. With a shortcut defined, variant could be specified with
1680 the <shortcut>value syntax. For instance if character % is set as a
1681 shortcut for variant foo, the %value syntax is equivalent to the
1682 foo=value syntax.
1683 Specific characters used in variant specification syntax cannot be used
1685 as part of the name of a module. These specific characters are +, ~, =
1686 and all characters set as variant shortcut. Exception is made for +
1687 character which could be set one or several consecutive times at the
1688 end of module name (e.g., name+ or name++).
1689 Module tags
1691 Module tags are piece of information that can be associated to individ‐
1692 ual modulefiles. Tags could be purely informational or may lead to spe‐
1693 cific behaviors.
1694 Module tags may be inherited from the module state set by a modulefile
1696 command or consequence of a module action. The inherited tags are:
1697 • auto-loaded: module has been automatically loaded by another module
1699 • forbidden: module has been set forbidden through the use of the mod‐
1701 ule-forbid command and thus this module cannot be loaded.
1702 • hidden: module has been set hidden through the use of the module-hide
1704 command and thus it is not reported by default among the result of an
1705 avail sub-command.
1706 • hidden-loaded: module has been set hidden once loaded through the use
1708 of the module-hide --hidden-loaded command thus it is not reported bu
1709 default among the result of a list sub-command.
1710 • loaded: module is currently loaded
1712 • nearly-forbidden: module will soon be forbidden, which has been set
1714 through the use of the module-forbid command. Thus this module will
1715 soon not be able to load anymore.
1716 Tags may also be associated to modules by using the module-tag module‐
1718 file command. Among tags that could be set this way, some have a spe‐
1719 cial meaning:
1720 • keep-loaded: auto-loaded module cannot be automatically unloaded.
1722 This tag is also set through the use of the always-load command.
1723 • sticky: module once loaded cannot be unloaded unless forced or
1725 reloaded (see Sticky modules section)
1726 • super-sticky: module once loaded cannot be unloaded unless reloaded,
1728 module cannot be unloaded even if forced (see Sticky modules section)
1729 The --tag option helps to apply additional tags to modules. It is
1731 available on load, load-any, switch and try-load sub-commands and on
1732 always-load, depends-on, module, prereq, prereq-all and prereq-any mod‐
1733 ulefile commands. In case the designated module is already loaded, the
1734 additional tags are added to the list of tags already applied to this
1735 module.
1736 Module tags are reported along the module they are associated to on
1738 avail and list sub-command results and also when module's loading, un‐
1739 loading, refreshing or tagging evaluation is mentioned. Tags could be
1740 reported either:
1741 • along the module name, all tags set within angle brackets, each tag
1743 separated from the others with a colon character (e.g., foo/1.2
1744 <tag1:tag2>).
1745 • graphically rendered over the module name for each tag associated to
1747 a Select Graphic Rendition (SGR) code in the color palette (see
1748 MODULES_COLORS)
1749 When an abbreviated string is associated to a tag name (see
1751 MODULES_TAG_ABBREV), this abbreviation is used to report tag along the
1752 module name or the tag is graphically rendered over the module name if
1753 a SGR code is associated with tag abbreviation in the color palette.
1754 With an abbreviation set, the SGR code associated to the tag full name
1755 is ignored thus an SGR code should be associated to the abbreviation to
1756 get a graphical rendering of tag. If the abbreviation associated to a
1757 tag corresponds to the empty string, tag is not reported.
1758 Graphical rendering is made over the tag name or abbreviation instead
1760 of over the module name for each tag name or abbreviation set in the
1761 MODULES_TAG_COLOR_NAME environment variable.
1762 When several tags have to be rendered graphically over the same module
1764 name, each tag is rendered over a sub-part of the module name. In case
1765 more tags need to be rendered than the total number of characters in
1766 the module name, the remaining tags are graphically rendered over the
1767 tag name instead of over the module name.
1768 When the JSON output mode is enabled (with --json), tags are reported
1770 by their name under the tags attribute. Tag abbreviation and color ren‐
1771 dering do not apply on JSON output.
1772 Module tags cannot be used in search query to designate a modulefile.
1774 Sticky modules
1776 Modules are said sticky when they cannot be unloaded (they stick to the
1777 loaded environment). Two kind of stickiness can be distinguished:
1778 • sticky module: cannot be unloaded unless if the unload is forced or
1780 if the module is reloaded after being unloaded or if restoring a col‐
1781 lection.
1782 • super-sticky module: cannot be unloaded unless if the module is
1784 reloaded after being unloaded; super-sticky modules cannot be un‐
1785 loaded even if the unload is forced.
1786 Modules are designated sticky by associating them the sticky or the su‐
1788 per-sticky module tag with the module-tag modulefile command.
1789 When stickiness is defined over the generic module name (and not over a
1791 specific module version, a version list or a version range), sticky or
1792 super-sticky module can be swapped by another version of module. For
1793 instance if the sticky tag is defined over foo module, loaded module
1794 foo/1.2 can be swapped by foo/2.0. Such stickiness definition means one
1795 version of module should stay loaded whatever version it is.
1796 When restoring a collection or resetting to the initial environment,
1798 sticky modules are unloaded to ensure restore or reset sub-commands
1799 fully set the environment in target collection or initial state. Su‐
1800 per-sticky modules still cannot be unloaded with restore and reset
1801 sub-commands.
1802 Module variants
1804 Module variants are alternative evaluation of the same modulefile. A
1805 variant is specified by associating a value to its name when designat‐
1806 ing module. Variant specification relies on the Advanced module ver‐
1807 sion specifiers mechanism.
1808 Once specified, variant's value is transmitted to the evaluating mod‐
1810 ulefile which instantiates the variant in the ModuleVariant array vari‐
1811 able when reaching the variant modulefile command declaring this vari‐
1812 ant. For instance the module load foo/1.2 bar=value1 command leads to
1813 the evaluation of foo/1.2 modulefile with bar=value1 variant specifica‐
1814 tion. When reaching the variant bar value1 value2 value3 command in
1815 modulefile during its evaluation, the ModuleVariant(bar) array element
1816 is set to the value1 string.
1817 Once variants are instantiated, modulefile's code could check the vari‐
1819 ant values to adapt the evaluation and define for instance different
1820 module requirements or produce different environment variable setup.
1821 Variants are interpreted in contexts where modulefiles are evaluated.
1823 Thus the variants specified on module designation are ignored by the
1824 avail, whatis, is-avail, path or paths sub-commands.
1825 When modulefile is evaluated a value should be specified for each vari‐
1827 ant this modulefile declares. When reaching the variant modulefile com‐
1828 mand declaring a variant, an error is raised if no value is specified
1829 for this variant and if no default value is declared. Specified variant
1830 value should match a value from the declared accepted value list if
1831 such list is defined otherwise an error is raised. Additionally if a
1832 variant is specified but does not correspond to a variant declared in
1833 modulefile, an error is raised.
1834 Module variants are reported along the module they are associated to on
1836 list sub-command results. Variants are reported within curly braces
1837 next to module name, each variant definition separated from the others
1838 with a colon character (e.g., foo/1.2{variant1=value:+variant2}). Bool‐
1839 ean variants are reported with the +name or -name syntaxes. When a
1840 shortcut character is defined for a variant (see
1841 MODULES_VARIANT_SHORTCUT) it is reported with the <shortcut>value syn‐
1842 tax. For instance if % character is defined as a shortcut for variant1:
1843 foo/1.2{%value:+variant2}.
1844 When the JSON output mode is enabled (with --json), variants are re‐
1846 ported under the variants JSON object as name/value pairs. Values of
1847 Boolean variant are set as JSON Boolean. Other values are set as JSON
1848 strings. Variant shortcut and color rendering do not apply on JSON
1849 output.
1850 Collections
1852 Collections describe a sequence of module use then module load commands
1853 that are interpreted by modulecmd.tcl to set the user environment as
1854 described by this sequence.
1855 Collections are generated by the save sub-command that dumps the cur‐
1857 rent user environment state in terms of module paths and loaded mod‐
1858 ules. By default collections are saved under the $HOME/.module direc‐
1859 tory.
1860 $ module list
1862 Currently Loaded Modulefiles:
1863 1) foo/1.2 2) bar/2.0 3) qux/3.5
1864 $ module save foo
1865 $ cat $HOME/.module/foo
1866 module use --append /path/to/modulefiles
1867 module load foo
1868 module load bar/2.0
1869 module load qux/3.5
1870 The content of a collection can also be displayed with the saveshow
1872 sub-command. Note that in the above example, bare module name is
1873 recorded for foo modulefile as loaded version is the implicit default.
1874 Loaded version recording can be enforced by enabling
1875 collection_pin_version configuration option.
1876 $ module config collection_pin_version 1
1878 $ module save foo
1879 $ module saveshow foo
1880 -------------------------------------------------------------------
1881 /home/user/.module/foo:
1882 module use --append /path/to/modulefiles
1884 module load foo/1.2
1885 module load bar/2.0
1886 module load qux/3.5
1887 -------------------------------------------------------------------
1889 When a collection is activated, with the restore sub-command, module
1891 paths and loaded modules are unused or unloaded if they are not part or
1892 if they are not ordered the same way as in the collection.
1893 $ module list
1895 Currently Loaded Modulefiles:
1896 1) foo/1.2 2) bar/2.1 3) qux/3.5
1897 $ module restore foo
1898 Unloading qux/3.5
1899 Unloading bar/2.1
1900 Loading bar/2.0
1901 Loading qux/3.5
1902 $ module list
1903 Currently Loaded Modulefiles:
1904 1) foo/1.2 2) bar/2.0 3) qux/3.5
1905 In the above example, second and third module loaded are changed. First
1907 loaded module is not changed or reloaded as it is the same module be‐
1908 tween current environment and collection. As second loaded module was
1909 different, this module and all those loaded afterward are unloaded to
1910 then load the sequence described by collection. As a result, third
1911 loaded module is reloaded, even if is was the same module between cur‐
1912 rent environment and collection.
1913 Existing collections can be listed with savelist sub-command. They can
1915 be deleted with saverm sub-command.
1916 $ module savelist
1918 Named collection list:
1919 1) default 2) foo
1920 $ module saverm default
1921 $ module savelist
1922 Named collection list:
1923 1) foo
1924 When no argument is provided to save, restore, saveshow or saverm
1926 sub-commands, the default collection is assumed.
1927 Collection can also be specified as a full pathname:
1929 $ module save /path/to/collections/bar
1931 $ module saveshow /path/to/collections/bar
1932 -------------------------------------------------------------------
1933 /path/to/collections/bar:
1934 module use --append /path/to/modulefiles
1936 module load foo/1.2
1937 module load bar/2.0
1938 module load qux/3.5
1939 -------------------------------------------------------------------
1941 Initial environment
1943 Initial environment state, which corresponds to modulepaths enabled and
1944 modules loaded during Modules initialization, is referred as the
1945 __init__ collection. This collection is virtual as its content is
1946 stored in the __MODULES_LMINIT and not in a file. It can be displayed
1947 with saveshow and restored with restore sub-command.
1948 $ module saveshow __init__
1950 -------------------------------------------------------------------
1951 initial environment:
1952 module use --append /path/to/modulefiles
1954 module load foo/1.2
1955 -------------------------------------------------------------------
1957 If the default collection does not exist, saveshow and restore sub-com‐
1959 mands assume __init__ collection when no argument provided to them.
1960 $ module list
1962 Currently Loaded Modulefiles:
1963 1) foo/1.2 2) bar/2.1 3) qux/3.5
1964 $ module savelist
1965 Named collection list:
1966 1) foo
1967 $ module restore
1968 Unloading qux/3.5
1969 Unloading bar/2.1
1970 Initial environment state can also be restored with the reset sub-com‐
1972 mand. This sub-command behavior can be changed with reset_target_state
1973 configuration option to choose to just purge loaded modules or to re‐
1974 store a specific collection.
1975 Collection targets
1977 A collection target can be defined for current environment session with
1978 the collection_target configuration option. When set, available collec‐
1979 tions are reduced to those suffixed with target name. Which means
1980 restore, saveshow, savelist and saverm only find collections matching
1981 currently set target.
1982 $ module savelist
1984 Named collection list:
1985 1) foo
1986 $ module config collection_target mytarget
1987 $ module savelist
1988 No named collection (for target "mytarget").
1989 $ module restore foo
1990 ERROR: Collection foo (for target "mytarget") cannot be found
1991 When saving a new collection, generated file is suffixed with currently
1993 set target name.
1994 $ module save bar
1996 $ module savelist
1997 Named collection list (for target "mytarget"):
1998 1) bar
1999 $ ls $HOME/.module
2000 bar.mytarget foo
2001 Collection targets help to distinguish contexts and make collection
2003 reachable only from the context they have been made for. For instance
2004 the same user account may be used to access different OSes or machine
2005 architectures. With a target set, users are ensured to only access col‐
2006 lections built for the context they are currently connected to. See
2007 also MODULES_COLLECTION_TARGET section.
2008 Stash collections
2010 Current user environment can be stashed with stash sub-command. When
2011 this sub-command is called, current module environment is saved in a
2012 stash collection then initial environment is restored.
2013 $ module list
2015 Currently Loaded Modulefiles:
2016 1) foo/1.2 2) qux/4.2
2017 $ module stash
2018 Unloading qux/4.2
2019 Specific sub-commands are available to handle stash collections:
2021 stashpop, stashlist, stashshow, stashrm and stashclear. A stash collec‐
2022 tion is restored with stashpop which also deletes the collection once
2023 restored.
2024 $ module stashlist
2026 Stash collection list (for target "mytarget"):
2027 0) stash-1667669750191
2028 $ module stashpop
2029 Loading qux/4.2
2030 $ module stashlist
2031 No stash collection (for target "mytarget").
2032 Stash collections have same format and are saved in the same location
2034 than other collections. Collection target also applies to stash collec‐
2035 tion. Creation timestamp is saved in stash collection name.
2036 Stash collection can be designated by their full collection name (i.e.,
2038 stash-<creation_timestamp>) or a stash index. Most recent stash collec‐
2039 tion has index 0, 1 is the one before it. When no argument is provided
2040 on stash sub-commands, the latest stash collection is assumed (that is
2041 stash index 0).
2042 $ module stashlist
2044 Stash collection list (for target "mytarget"):
2045 0) stash-1667669750783 1) stash-1667669750253
2046 $ module stashshow 1
2047 -------------------------------------------------------------------
2048 /home/user/.module/stash-1667669750253.mytarget:
2049 module use --append /path/to/modulefiles
2051 module load foo/1.2
2052 module load bar/2.0
2053 -------------------------------------------------------------------
2055 Site-specific configuration
2057 Siteconfig, the site-specific configuration script, is a way to extend
2058 modulecmd.tcl. Siteconfig is a Tcl script. Its location is /etc/envi‐
2059 ronment-modules/siteconfig.tcl.
2060 When modulecmd.tcl is invoked it sources siteconfig script if it ex‐
2062 ists. Any global variable or procedure of modulecmd.tcl can be rede‐
2063 fined in siteconfig.
2064 An additional siteconfig script may be specified through the
2066 extra_siteconfig configuration option. The MODULES_SITECONFIG environ‐
2067 ment variable is defined by config sub-command when setting
2068 extra_siteconfig. If it exists the extra siteconfig is sourced by mod‐
2069 ulecmd.tcl right after main siteconfig script.
2070 Hooks
2072 Siteconfig relies on the ability of the Tcl language to overwrite pre‐
2073 viously defined variables and procedures. Sites may deploy their own
2074 Tcl code in siteconfig to adapt modulecmd.tcl to their specific needs.
2075 The trace Tcl command may especially be used to define hooks that are
2076 run when entering or leaving a given procedure, or when a variable is
2077 read or written. See trace(n) man page for detailed information. The
2078 following example setup a procedure that is executed before each mod‐
2079 ulefile evaluation:
2080 proc beforeEval {cmdstring code result op} {
2082 # code to run right before each modulefile evaluation
2083 }
2084 trace add execution execute-modulefile enter beforeEval
2085 Another possibility is to override the definition of an existing proce‐
2087 dure by first renaming its original version then creating a new proce‐
2088 dure that will add specific code and rely on the renamed original pro‐
2089 cedure for the rest. See rename(n) man page for details. As an example,
2090 the following code adds a new query option to the module-info module‐
2091 file command:
2092 rename module-info __module-info
2094 proc module-info {what {more {}}} {
2095 switch -- $what {
2096 platform { return myhost-$::tcl_platform(machine) }
2097 default { return [__module-info $what $more] }
2098 }
2099 }
2100 Siteconfig hook variables
2102 Some Tcl variables can be defined in siteconfig script with special
2103 hook meaning. The following variables are recognized:
2104 modulefile_extra_vars
2106 List of variable names and associated values to setup in module‐
2107 file evaluation context. These variables can be accessed when
2108 modulefile is executed. In case code in a modulefile changes the
2109 value of such variable, its value is reset to the one defined in
2110 modulefile_extra_vars prior the evaluation of the next module‐
2111 file.
2112 set modulefile_extra_vars {myvar 1 othervar {some text}}
2114 In the above siteconfig example, modulefile_extra_vars sets the
2116 myvar and othervar variables in the modulefile evaluation con‐
2117 text with respectively 1 and some text as value.
2118 modulefile_extra_cmds
2120 List of command and associated local procedure to setup in mod‐
2121 ulefile evaluation context. These commands can be called from
2122 the modulefile to execute associated procedure. In case a mod‐
2123 ulefile changes the definition of such command, its definition
2124 is bound again on the procedure defined in modulefile_extra_cmds
2125 prior the evaluation of the next modulefile.
2126 proc mycmd {} {
2128 # Tcl code
2129 }
2130 proc anotherproc {args} {
2131 # Tcl code
2132 }
2133 set modulefile_extra_cmds {mycmd mycmd othercmd anotherproc}
2134 In the above siteconfig example, modulefile_extra_cmds sets the
2136 mycmd and othercmd commands in the modulefile evaluation context
2137 and bind them respectively to the mycmd and anotherproc proce‐
2138 dures defined in siteconfig script.
2139 modulerc_extra_vars
2141 List of variable names and associated values to setup in mod‐
2142 ulerc evaluation context. These variables can be accessed when
2143 modulerc is executed. In case code in a modulerc changes the
2144 value of such variable, its value is reset to the one defined in
2145 modulerc_extra_vars prior the evaluation of the next modulerc.
2146 set modulerc_extra_vars {myvar 1 othervar {some text}}
2148 In the above siteconfig example, modulerc_extra_vars sets the
2150 myvar and othervar variables in the modulerc evaluation context
2151 with respectively 1 and some text as value.
2152 modulerc_extra_cmds
2154 List of command and associated local procedure to setup in mod‐
2155 ulerc evaluation context. These commands can be called from the
2156 modulerc to execute associated procedure. In case a modulerc
2157 changes the definition of such command, its definition is bound
2158 again on the procedure defined in modulerc_extra_cmds prior the
2159 evaluation of the next modulerc.
2160 proc mycmd {} {
2162 # Tcl code
2163 }
2164 proc anotherproc {args} {
2165 # Tcl code
2166 }
2167 set modulerc_extra_cmds {mycmd mycmd othercmd anotherproc}
2168 In the above siteconfig example, modulerc_extra_cmds sets the
2170 mycmd and othercmd commands in the modulerc evaluation context
2171 and bind them respectively to the mycmd and anotherproc proce‐
2172 dures defined in siteconfig script.
2173
2175 The module command exits with 0 if its execution succeed. Otherwise 1
2176 is returned.
2177
2179 __MODULES_AUTOINIT_INPROGRESS
2180 If set to 1, the autoinit sub-command process is skipped.
2181 This environment variable is set to 1 by the autoinit sub-com‐
2183 mand after checking it is not set. It ensures no nested initial‐
2184 ization of Modules occur. At the end of the processing of the
2185 autoinit sub-command, __MODULES_AUTOINIT_INPROGRESS is unset.
2186 __MODULES_LMALTNAME
2188 A colon separated list of the alternative names set through mod‐
2189 ule-version and module-alias statements corresponding to all
2190 loaded modulefiles. Each element in this list starts by the name
2191 of the loaded modulefile followed by all alternative names re‐
2192 solving to it. The loaded modulefile and its alternative names
2193 are separated by the ampersand character.
2194 Each alternative name stored in __MODULES_LMALTNAME is prefixed
2196 by the al| string if it corresponds to a module alias or pre‐
2197 fixed by the as| string if it corresponds to an automatic ver‐
2198 sion symbol. These prefixes help to distinguish the different
2199 kind of alternative name.
2200 This environment variable is intended for module command inter‐
2202 nal use to get knowledge of the alternative names matching
2203 loaded modulefiles in order to keep environment consistent when
2204 conflicts or pre-requirements are set over these alternative
2205 designations. It also helps to find a match after modulefiles
2206 being loaded when unload, is-loaded or info-loaded actions are
2207 run over these names.
2208 Starting version 4.7 of Modules, __MODULES_LMALTNAME is also
2210 used on list sub-command to report the symbolic versions associ‐
2211 ated with the loaded modules.
2212 __MODULES_LMCONFLICT
2214 A colon separated list of the conflict statements defined by all
2215 loaded modulefiles. Each element in this list starts by the name
2216 of the loaded modulefile declaring the conflict followed by the
2217 name of all modulefiles it declares a conflict with. These
2218 loaded modulefiles and conflicting modulefile names are sepa‐
2219 rated by the ampersand character.
2220 This environment variable is intended for module command inter‐
2222 nal use to get knowledge of the conflicts declared by the loaded
2223 modulefiles in order to keep environment consistent when a con‐
2224 flicting module is asked for load afterward.
2225 __MODULES_LMINIT
2227 A colon separated list describing the modulepaths that have been
2228 enabled and the modulefiles that have been loaded with their
2229 tags during Modules initialization. Each element in this list
2230 corresponds to a collection definition line.
2231 This environment variable is intended for module command inter‐
2233 nal use to get knowledge of the initial loaded state after ini‐
2234 tialization.
2235 This initial environment state can then be restored with reset
2237 sub-command. It can also be restored with restore sub-command
2238 when __init__ collection name is specified or when no collection
2239 name is specified and no default collection exists.
2240 The content of the initial environment can be displayed with
2242 saveshow sub-command when __init__ collection name is specified
2243 or when no collection name is specified and no default collec‐
2244 tion exists.
2245 __MODULES_LMPREREQ
2247 A colon separated list of the prereq statements defined by all
2248 loaded modulefiles. Each element in this list starts by the name
2249 of the loaded modulefile declaring the pre-requirement followed
2250 by the name of all modulefiles it declares a prereq with. These
2251 loaded modulefiles and pre-required modulefile names are sepa‐
2252 rated by the ampersand character. When a prereq statement is
2253 composed of multiple modulefiles, these modulefile names are
2254 separated by the pipe character.
2255 This environment variable is intended for module command inter‐
2257 nal use to get knowledge of the pre-requirement declared by the
2258 loaded modulefiles in order to keep environment consistent when
2259 a pre-required module is asked for unload afterward.
2260 __MODULES_LMREFRESH
2262 A colon separated list of the loaded modules that are qualified
2263 for refresh evaluation. Loaded modules listed in this variable
2264 are those defining volatile environment changes like shell com‐
2265 pletion, alias and function.
2266 __MODULES_LMSOURCESH
2268 A colon separated list of the source-sh statements defined by
2269 all loaded modulefiles. Each element in this list starts by the
2270 name of the loaded modulefile declaring the environment changes
2271 made by the evaluation of source-sh scripts. This name is fol‐
2272 lowed by each source-sh statement call and corresponding result
2273 achieved in modulefile. The loaded modulefile name and each
2274 source-sh statement description are separated by the ampersand
2275 character. The source-sh statement call and each resulting mod‐
2276 ulefile command (corresponding to the environment changes done
2277 by sourced script) are separated by the pipe character.
2278 This environment variable is intended for module command inter‐
2280 nal use to get knowledge of the modulefile commands applied for
2281 each source-sh command when loading the modulefile. In order to
2282 reverse these modulefile commands when modulefile is unloaded to
2283 undo the environment changes.
2284 __MODULES_LMEXTRATAG
2286 A colon separated list of the tags corresponding to all loaded
2287 modulefiles that have been set through the --tag option. Each
2288 element in this list starts by the name of the loaded modulefile
2289 followed by all explicitly set tags applying to it. The loaded
2290 modulefile and its tags are separated by the ampersand charac‐
2291 ter.
2292 This environment variable is intended for module command inter‐
2294 nal use to distinguish from all tags those that have been
2295 specifically set with --tag option.
2296 __MODULES_LMTAG
2298 A colon separated list of the tags corresponding to all loaded
2299 modulefiles that have been set through module-tag statements or
2300 from other modulefile statements like module-forbid (that may
2301 apply the nearly-forbidden tag in specific situation) (see
2302 Module tags section). Each element in this list starts by the
2303 name of the loaded modulefile followed by all tags applying to
2304 it. The loaded modulefile and its tags are separated by the am‐
2305 persand character.
2306 This environment variable is intended for module command inter‐
2308 nal use to get knowledge of the tags applying to loaded module‐
2309 files in order to report these tags on list sub-command output
2310 or to apply specific behavior when unloading modulefile.
2311 __MODULES_LMVARIANT
2313 A colon separated list of the variant instantiated through vari‐
2314 ant statements by all loaded modulefiles (see Module variants
2315 section). Each element in this list starts by the name of the
2316 loaded modulefile followed by all the variant definitions set
2317 during the load of this module. The loaded modulefile and each
2318 of its variant definition are separated by the ampersand charac‐
2319 ter. Each variant definition starts with the variant name, fol‐
2320 lowed by the variant value set, then a flag to know if variant
2321 is of the Boolean type and last element in this definition is a
2322 flag to know if the chosen value is the default one for this
2323 variant and if it has been automatically set or not. These four
2324 elements composing the variant definition are separated by the
2325 pipe character.
2326 This environment variable is intended for module command inter‐
2328 nal use to get knowledge of the variant value defined by the
2329 loaded modulefiles in order to keep environment consistent when
2330 requirements are set over a specific variant value or just to
2331 report these variant values when listing loaded modules.
2332 __MODULES_PUSHENV_<VAR>
2334 Stack of saved values for <VAR> environment variable. A
2335 colon-separated list containing pairs of elements. A pair is
2336 formed by a loaded module name followed by the value set to
2337 <VAR> in this module with pushenv command. An ampersand charac‐
2338 ter separates the two parts of the pair.
2339 First element in list corresponds to the lastly set value of
2341 <VAR>. If a value were set to <VAR> prior the first evaluated
2342 pushenv command, this value is associated to an empty module
2343 name to record it as a pair element in __MODULES_PUSHENV_<VAR>.
2344 __MODULES_QUAR_<VAR>
2346 Value of environment variable <VAR> passed to modulecmd.tcl in
2347 order to restore <VAR> to this value once started.
2348 __MODULES_QUARANTINE_SET
2350 If set to 1, restore the environment variables set on hold by
2351 the quarantine mechanism when starting modulecmd.tcl script.
2352 This variable is automatically defined by Modules shell initial‐
2353 ization scripts or module shell function when they apply the
2354 quarantine mechanism. (see MODULES_QUARANTINE_SUPPORT).
2355 __MODULES_SHARE_<VAR>
2357 Reference counter variable for path-like variable <VAR>. A colon
2358 separated list containing pairs of elements. A pair is formed by
2359 a path element followed its usage counter which represents the
2360 number of times this path has been enabled in variable <VAR>. A
2361 colon separates the two parts of the pair.
2362 An element of a path-like variable is added to the reference
2364 counter variable as soon as it is added more than one time. When
2365 an element of a path-like variable is not found in the reference
2366 counter variable, it means this element has only be added once
2367 to the path-like variable.
2368 When an empty string is added as an element in the path-like
2370 variable, it is added to the reference counter variable even if
2371 added only once to distinguish between an empty path-like vari‐
2372 able and a path-like variable containing an empty string as sin‐
2373 gle element.
2374 _LMFILES_
2376 A colon separated list of the full pathname for all loaded mod‐
2377 ulefiles.
2378 This environment variable is generated by module command and
2380 should not be modified externally.
2381 LOADEDMODULES
2383 A colon separated list of all loaded modulefiles.
2384 This environment variable is generated by module command and
2386 should not be modified externally.
2387 MODULECONTACT
2389 Email address to contact in case any issue occurs during the in‐
2390 terpretation of modulefiles.
2391 This environment variable value supersedes the default value set
2393 in the contact configuration option. It can be defined with the
2394 config sub-command.
2395 MODULEPATH
2397 The path that the module command searches when looking for mod‐
2398 ulefiles. Typically, it is set to the main modulefiles direc‐
2399 tory, /usr/share/Modules/modulefiles, by the initialization
2400 script. MODULEPATH can be set using module use or by the module
2401 initialization script to search group or personal modulefile di‐
2402 rectories before or after the main modulefile directory.
2403 Path elements registered in the MODULEPATH environment variable
2405 may contain reference to environment variables which are con‐
2406 verted to their corresponding value by module command each time
2407 it looks at the MODULEPATH value. If an environment variable re‐
2408 ferred in a path element is not defined, its reference is con‐
2409 verted to an empty string.
2410 MODULERCFILE
2412 The location of a global run-command file containing modulefile
2413 specific setup. See Modulecmd startup section for detailed in‐
2414 formation.
2415 This environment variable value supersedes the default value set
2417 in the rcfile configuration option. It can be defined with the
2418 config sub-command.
2419 MODULES_ADVANCED_VERSION_SPEC
2421 If set to 1, enable advanced module version specifiers (see
2422 Advanced module version specifiers section). If set to 0, dis‐
2423 able advanced module version specifiers.
2424 This environment variable value supersedes the default value set
2426 in the advanced_version_spec configuration option. It can be de‐
2427 fined with the config sub-command.
2428 MODULES_AUTO_HANDLING
2430 If set to 1, enable automated module handling mode. If set to 0
2431 disable automated module handling mode. Other values are ig‐
2432 nored.
2433 Automated module handling mode consists in additional actions
2435 triggered when loading or unloading a modulefile to satisfy the
2436 constraints it declares. When loading a modulefile, following
2437 actions are triggered:
2438 • Requirement Load: load of the modulefiles declared as a prereq
2440 of the loading modulefile.
2441 • Dependent Reload: reload of the modulefiles declaring a prereq
2443 onto loaded modulefile or declaring a prereq onto a modulefile
2444 part of this reloading batch.
2445 When unloading a modulefile, following actions are triggered:
2447 • Dependent Unload: unload of the modulefiles declaring a
2449 non-optional prereq onto unloaded modulefile or declaring a
2450 non-optional prereq onto a modulefile part of this unloading
2451 batch. A prereq modulefile is considered optional if the pre‐
2452 req definition order is made of multiple modulefiles and at
2453 least one alternative modulefile is loaded.
2454 • Useless Requirement Unload: unload of the prereq modulefiles
2456 that have been automatically loaded for either the unloaded
2457 modulefile, an unloaded dependent modulefile or a modulefile
2458 part of this useless requirement unloading batch. Modulefiles
2459 are added to this unloading batch only if they are not re‐
2460 quired by any other loaded modulefiles and if they are not
2461 tagged keep-loaded.
2462 • Dependent Reload: reload of the modulefiles declaring a con‐
2464 flict or an optional prereq onto either the unloaded module‐
2465 file, an unloaded dependent or an unloaded useless requirement
2466 or declaring a prereq onto a modulefile part of this reloading
2467 batch.
2468 In case a loaded modulefile has some of its declared constraints
2470 unsatisfied (pre-required modulefile not loaded or conflicting
2471 modulefile loaded for instance), this loaded modulefile is ex‐
2472 cluded from the automatic reload actions described above.
2473 For the specific case of the switch sub-command, where a module‐
2475 file is unloaded to then load another modulefile. Dependent mod‐
2476 ulefiles to Unload are merged into the Dependent modulefiles to
2477 Reload that are reloaded after the load of the switched-to mod‐
2478 ulefile.
2479 This environment variable value supersedes the default value set
2481 on the auto_handling configuration option. It can be defined
2482 with the config sub-command. The --auto and --no-auto command
2483 line switches override this environment variable.
2484 MODULES_AVAIL_INDEPTH
2486 If set to 1, enable in depth search results for avail sub-com‐
2487 mand. If set to 0 disable avail sub-command in depth mode. Other
2488 values are ignored.
2489 When in depth mode is enabled, modulefiles and directories con‐
2491 tained in directories matching search query are also included in
2492 search results. When disabled these modulefiles and directories
2493 contained in matching directories are excluded.
2494 This environment variable value supersedes the default value set
2496 in the avail_indepth configuration option. It can be defined
2497 with the config sub-command. The --indepth and --no-indepth com‐
2498 mand line switches override this environment variable.
2499 MODULES_AVAIL_OUTPUT
2501 A colon separated list of the elements to report in addition to
2502 module names on avail sub-command regular output mode.
2503 Accepted elements that can be set in value list are:
2505 • alias: module aliases.
2507 • dirwsym: directories associated with symbolic versions.
2509 • key: legend appended at the end of the output to explain it.
2511 • modulepath: modulepath names set as header prior the list of
2513 available modules found in them.
2514 • sym: symbolic versions associated with available modules.
2516 • tag: tags associated with available modules.
2518 The order of the elements in the list does not matter. Module
2520 names are the only content reported when LIST is set to an empty
2521 value.
2522 In case the modulepath element is missing from value list, the
2524 available modules from global/user rc and all enabled mod‐
2525 ulepaths are reported as a single list.
2526 This environment variable value supersedes the default value set
2528 in the avail_output configuration option. It can be defined with
2529 the config sub-command. The --output/-o command line switches
2530 override this environment variable.
2531 MODULES_AVAIL_TERSE_OUTPUT
2533 A colon separated list of the elements to report in addition to
2534 module names on avail sub-command terse output mode.
2535 See MODULES_AVAIL_OUTPUT to get the accepted elements that can
2537 be set in value list.
2538 The order of the elements in the list does not matter. Module
2540 names are the only content reported when LIST is set to an empty
2541 value.
2542 This environment variable value supersedes the default value set
2544 in the avail_terse_output configuration option. It can be de‐
2545 fined with the config sub-command. The --output/-o command line
2546 switches override this environment variable.
2547 MODULES_CMD
2549 The location of the active module command script.
2550 This environment variable is generated by module command and
2552 should not be modified externally.
2553 MODULES_COLLECTION_PIN_VERSION
2555 If set to 1, register exact version number of modulefiles when
2556 saving a collection. Otherwise modulefile version number is
2557 omitted if it corresponds to the explicitly set default version
2558 and also to the implicit default when the configuration option
2559 implicit_default is enabled.
2560 This environment variable value supersedes the default value set
2562 in the collection_pin_version configuration option. It can be
2563 defined with the config sub-command.
2564 MODULES_COLLECTION_PIN_TAG
2566 If set to 1, register all tags applying to modulefiles when sav‐
2567 ing a collection. Otherwise only the extra tags set through the
2568 --tag option and tags resulting from specific module states
2569 (like auto-loaded and keep-loaded tags) are recorded in collec‐
2570 tion. Note that the nearly-forbidden tag due to its temporal
2571 meaning is not saved in collection even when this configuration
2572 option is enabled.
2573 This environment variable value supersedes the default value set
2575 in the collection_pin_tag configuration option. It can be de‐
2576 fined with the config sub-command.
2577 MODULES_COLLECTION_TARGET
2579 The collection target that determines what collections are valid
2580 thus reachable on the current system.
2581 Collection directory may sometimes be shared on multiple ma‐
2583 chines which may use different modules setup. For instance mod‐
2584 ules users may access with the same HOME directory multiple sys‐
2585 tems using different OS versions. When it happens a collection
2586 made on machine 1 may be erroneous on machine 2.
2587 When a target is set, only the collections made for that target
2589 are available to the restore, savelist, saveshow, saverm, stash,
2590 stashpop, stashlist, stashshow, and stashrm sub-commands. Saving
2591 a collection registers the target footprint by suffixing the
2592 collection filename with .$MODULES_COLLECTION_TARGET. The col‐
2593 lection target is not involved when collection is specified as
2594 file path on the saveshow, restore and save sub-commands.
2595 For example, the MODULES_COLLECTION_TARGET variable may be set
2597 with results from commands like lsb_release, hostname, dnsdo‐
2598 mainname, etc.
2599 This environment variable value supersedes the default value set
2601 in the collection_target configuration option. It can be defined
2602 with the config sub-command.
2603 MODULES_COLOR
2605 Defines if output should be colored or not. Accepted values are
2606 never, auto and always.
2607 When color mode is set to auto, output is colored only if the
2609 standard error output channel is attached to a terminal.
2610 This environment variable value supersedes the default value set
2612 in the color configuration option. It can be defined with the
2613 config sub-command. The --color command line switch overrides
2614 this environment variable.
2615 NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables are
2617 also honored to define color mode. The never mode is set if
2618 NO_COLOR is defined (regardless of its value) or if CLICOLOR
2619 equals to 0. If CLICOLOR is set to another value, it corresponds
2620 to the auto mode. The always mode is set if CLICOLOR_FORCE is
2621 set to a value different than 0. NO_COLOR variable prevails
2622 over CLICOLOR and CLICOLOR_FORCE. Color mode set with these
2623 three variables is superseded by mode set with MODULES_COLOR en‐
2624 vironment variable or with --color command line switch..
2625 MODULES_COLORS
2627 Specifies the colors and other attributes used to highlight var‐
2628 ious parts of the output. Its value is a colon-separated list of
2629 output items associated to a Select Graphic Rendition (SGR)
2630 code. It follows the same syntax than LS_COLORS.
2631 Output items are designated by keys. Items able to be colorized
2633 are: highlighted element (hi), debug information (db), trace in‐
2634 formation (tr), tag separator (se); Error (er), warning (wa),
2635 module error (me) and info (in) message prefixes; Modulepath
2636 (mp), directory (di), module alias (al), module variant (va),
2637 module symbolic version (sy), module default version (de) and
2638 modulefile command (cm).
2639 Module tags can also be colorized. The key to set in the color
2641 palette to get a graphical rendering of a tag is the tag name or
2642 the tag abbreviation if one is defined for tag. The SGR code ap‐
2643 plied to a tag name is ignored if an abbreviation is set for
2644 this tag thus the SGR code should be defined for this abbrevia‐
2645 tion to get a graphical rendering. Each basic tag has by default
2646 a key set in the color palette, based on its abbreviated string:
2647 auto-loaded (aL), forbidden (F), hidden and hidden-loaded (H),
2648 loaded (L), nearly-forbidden (nF), sticky (S), super-sticky (sS)
2649 and keep-loaded (kL).
2650 See the Select Graphic Rendition (SGR) section in the documenta‐
2652 tion of the text terminal that is used for permitted values and
2653 their meaning as character attributes. These substring values
2654 are integers in decimal representation and can be concatenated
2655 with semicolons. Modules takes care of assembling the result
2656 into a complete SGR sequence (\33[...m). Common values to con‐
2657 catenate include 1 for bold, 4 for underline, 30 to 37 for fore‐
2658 ground colors and 90 to 97 for 16-color mode foreground colors.
2659 See also
2660 https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
2661 for a complete SGR code reference.
2662 No graphical rendition will be applied to an output item that
2664 could normally be colored but which is not defined in the color
2665 set. Thus if MODULES_COLORS is defined empty, no output will be
2666 colored at all.
2667 This environment variable value supersedes the default value set
2669 in the colors configuration option. It can be defined with the
2670 config sub-command.
2671 MODULES_EDITOR
2673 Text editor command name or path for use to open modulefile
2674 through the edit sub-command.
2675 This environment variable value supersedes the default value set
2677 in the editor configuration option. It can be defined with the
2678 config sub-command.
2679 Text editor could also be defined through the VISUAL or EDITOR
2681 environment variables. These environment variables are overrid‐
2682 den by MODULES_EDITOR.
2683 MODULES_EXTENDED_DEFAULT
2685 If set to 1, a specified module version is matched against
2686 starting portion of existing module versions, where portion is a
2687 substring separated from the rest of the version string by a .
2688 character. For example specified modules mod/1 and mod/1.2 will
2689 match existing modulefile mod/1.2.3.
2690 In case multiple modulefiles match the specified module version
2692 and a single module has to be selected, the explicitly set de‐
2693 fault version is returned if it is part of matching modulefiles.
2694 Otherwise the implicit default among matching modulefiles is re‐
2695 turned if defined (see MODULES_IMPLICIT_DEFAULT section)
2696 This environment variable value supersedes the default value set
2698 in the extended_default configuration option. It can be defined
2699 with the config sub-command.
2700 MODULES_FAMILY_<NAME>
2702 Module name minus version that provides for the name family in
2703 currently loaded environment. This environment variable is de‐
2704 fined through the use of the family modulefile command.
2705 For instance if loading modulefile foo/1.0 defines being member
2707 of the bar family, the MODULES_FAMILY_BAR will be set to the foo
2708 value.
2709 This environment variable is generated by module command and
2711 should not be modified externally.
2712 MODULES_ICASE
2714 When module specification are passed as argument to module
2715 sub-commands or modulefile Tcl commands, defines the case sensi‐
2716 tiveness to apply to match them. When MODULES_ICASE is set to
2717 never, a case sensitive match is applied in any cases. When set
2718 to search, a case insensitive match is applied to the avail,
2719 list, whatis, paths and savelist sub-commands. When set to al‐
2720 ways, a case insensitive match is also applied to the other mod‐
2721 ule sub-commands and modulefile Tcl commands for the module
2722 specification they receive as argument.
2723 This environment variable value supersedes the default value set
2725 in the icase configuration option. It can be defined with the
2726 config sub-command. The --icase/-i command line switches, which
2727 correspond to the always mode, override this environment vari‐
2728 able.
2729 MODULES_IMPLICIT_DEFAULT
2731 Defines (if set to 1) or not (if set to 0) an implicit default
2732 version for modules without a default version explicitly defined
2733 (see Locating Modulefiles section in the modulefile(4) man
2734 page).
2735 Without either an explicit or implicit default version defined a
2737 module must be fully qualified (version should be specified in
2738 addition to its name) to get:
2739 • targeted by module load, switch, display, help, test and path
2741 sub-commands.
2742 • restored from a collection, unless already loaded in collec‐
2744 tion-specified order.
2745 • automatically loaded by automated module handling mechanisms
2747 (see MODULES_AUTO_HANDLING section) when declared as module
2748 requirement, with prereq or module load modulefile commands.
2749 An error is returned in the above situations if either no ex‐
2751 plicit or implicit default version is defined.
2752 This environment variable value supersedes the default value set
2754 in the implicit_default configuration option. It can be defined
2755 with the config sub-command. This environment variable is ig‐
2756 nored if implicit_default has been declared locked in
2757 locked_configs configuration option.
2758 MODULES_IMPLICIT_REQUIREMENT
2760 Defines (if set to 1) or not (if set to 0) an implicit prereq or
2761 conflict requirement onto modules specified respectively on mod‐
2762 ule load or module unload commands in modulefile. When enabled
2763 an implicit conflict requirement onto switched-off module and a
2764 prereq requirement onto switched-on module are also defined for
2765 module switch commands used in modulefile.
2766 This environment variable value supersedes the default value set
2768 in the implicit_requirement configuration option. It can be de‐
2769 fined with the config sub-command. The --not-req option, applied
2770 to a module command in a modulefile, overrides this environment
2771 variable.
2772 MODULES_LIST_OUTPUT
2774 A colon separated list of the elements to report in addition to
2775 module names on list sub-command regular output mode.
2776 Accepted elements that can be set in value list are:
2778 • header: sentence to introduce the list of loaded modules or to
2780 state that no modules are loaded currently.
2781 • idx: index position of each loaded module.
2783 • key: legend appended at the end of the output to explain it.
2785 • variant: variant values selected for loaded modules.
2787 • sym: symbolic versions associated with loaded modules.
2789 • tag: tags associated with loaded modules.
2791 The order of the elements in the list does not matter. Module
2793 names are the only content reported when LIST is set to an empty
2794 value.
2795 This environment variable value supersedes the default value set
2797 in the list_output configuration option. It can be defined with
2798 the config sub-command. The --output/-o command line switches
2799 override this environment variable.
2800 MODULES_LIST_TERSE_OUTPUT
2802 A colon separated list of the elements to report in addition to
2803 module names on list sub-command terse output mode.
2804 See MODULES_LIST_OUTPUT to get the accepted elements that can be
2806 set in value list.
2807 The order of the elements in the list does not matter. Module
2809 names are the only content reported when LIST is set to an empty
2810 value.
2811 This environment variable value supersedes the default value set
2813 in the list_terse_output configuration option. It can be defined
2814 with the config sub-command. The --output/-o command line
2815 switches override this environment variable.
2816 MODULES_MCOOKIE_CHECK
2818 If set to eval, the Modules magic cookie (i.e., #%Module file
2819 signature) is only checked to determine if a file is a module‐
2820 file when evaluating these files. If set to always, the Modules
2821 magic cookie is also checked when searching for modules.
2822 The eval mode is made to significantly reduce file checks when
2824 walking through modulepaths to search for modulefiles. Special
2825 care should be given to the content of modulepaths when this
2826 eval mode is set as the following kind of files are included in
2827 search results:
2828 • modulefiles with a magic cookie requiring a higher version of
2830 modulecmd.tcl
2831 • files not beginning with the magic cookie #%Module
2833 • read-protected files
2835 This environment variable value supersedes the default value set
2837 in the mcookie_check configuration option. It can be defined
2838 with the config sub-command.
2839 MODULES_MCOOKIE_VERSION_CHECK
2841 If set to 1, the version set in the Modules magic cookie in mod‐
2842 ulefile is checked against the current version of modulecmd.tcl
2843 to determine if the modulefile can be evaluated.
2844 This environment variable value supersedes the default value set
2846 in the mcookie_version_check configuration option. It can be de‐
2847 fined with the config sub-command.
2848 MODULES_ML
2850 If set to 1, define ml command when initializing Modules (see
2851 Package Initialization section). If set to 0, ml command is not
2852 defined.
2853 This environment variable value supersedes the default value set
2855 in the ml configuration option. It can be defined with the
2856 config sub-command.
2857 To enable or disable ml command, MODULES_ML should be set prior
2859 Modules initialization or the ml configuration option should be
2860 set in the initrc configuration file.
2861 MODULES_NEARLY_FORBIDDEN_DAYS
2863 Number of days a module is considered nearly forbidden prior
2864 reaching its expiry date set by module-forbid modulefile com‐
2865 mand. When a nearly forbidden module is evaluated a warning mes‐
2866 sage is issued to inform module will soon be forbidden. If set
2867 to 0, modules will never be considered nearly forbidden. Ac‐
2868 cepted values are integers comprised between 0 and 365.
2869 This environment variable value supersedes the default value set
2871 in the nearly_forbidden_days configuration option. It can be de‐
2872 fined with the config sub-command.
2873 MODULES_PAGER
2875 Text viewer for use to paginate message output if error output
2876 stream is attached to a terminal. The value of this variable is
2877 composed of a pager command name or path eventually followed by
2878 command-line options.
2879 This environment variable value supersedes the default value set
2881 in the pager configuration option. It can be defined with the
2882 config sub-command.
2883 If MODULES_PAGER variable is set to an empty string or to the
2885 value cat, pager will not be launched.
2886 MODULES_PROTECTED_ENVVARS
2888 A colon separated list of environment variable names that should
2889 not be modified by any modulefile command.
2890 Prevents modifications by append-path, prepend-path, re‐
2892 move-path, setenv and unsetenv. When these modulefile commands
2893 attempt to modify a protected environment variable, a warning
2894 message is emitted and modification is ignored.
2895 This environment variable value supersedes the default value set
2897 in the protected_envvars configuration option. It can be defined
2898 with the config sub-command.
2899 MODULES_QUARANTINE_SUPPORT
2901 If set to 1, produces the shell code for quarantine mechanism
2902 when the autoinit sub-command generates the module shell func‐
2903 tion.
2904 The generated shell code for quarantine mechanism indirectly
2906 passes the environment variable defined in
2907 MODULES_RUN_QUARANTINE to the modulecmd.tcl script to protect
2908 its run-time environment from side-effect coming from the cur‐
2909 rent definition of these variables.
2910 To enable quarantine support, MODULES_QUARANTINE_SUPPORT should
2912 be set to 1 prior Modules initialization or the
2913 quarantine_support configuration should be set to 1 in the ini‐
2914 trc configuration file.
2915 Generated code for quarantine mechanism sets the
2917 __MODULES_QUARANTINE_SET environment variable when calling the
2918 modulecmd.tcl script to make it restore the environment variable
2919 put in quarantine.
2920 This environment variable value supersedes the default value set
2922 in the quarantine_support configuration option. It can be de‐
2923 fined with the config sub-command.
2924 MODULES_REDIRECT_OUTPUT
2926 If set to 0, the output generated by module command is kept on
2927 stderr and not redirected to stdout channel.
2928 This environment variable value supersedes the default value set
2930 in the redirect_output configuration option. It can be defined
2931 with the config sub-command. The --redirect and --no-redirect
2932 command line switches override this environment variable.
2933 MODULES_RESET_TARGET_STATE
2935 Defines behavior of reset sub-command. When set to __init__,
2936 initial environment is restored. When set to __purge__, reset
2937 performs a purge sub-command. Any other value designates a name
2938 collection to restore.
2939 This environment variable value supersedes the default value set
2941 in the reset_target_state configuration option. It can be de‐
2942 fined with the config sub-command.
2943 MODULES_RUN_QUARANTINE
2945 A space separated list of environment variable names that should
2946 be passed indirectly to modulecmd.tcl to protect its run-time
2947 environment from side-effect coming from their current defini‐
2948 tion.
2949 If the quarantine mechanism has been included in module shell
2951 function (see MODULES_QUARANTINE_SUPPORT), each variable found
2952 in MODULES_RUN_QUARANTINE will have its value emptied or set to
2953 the value of the corresponding MODULES_RUNENV_<VAR> variable
2954 when defining modulecmd.tcl run-time environment.
2955 Original values of these environment variables set in quarantine
2957 are passed to modulecmd.tcl via __MODULES_QUAR_<VAR> variables.
2958 This environment variable value supersedes the default value set
2960 in the run_quarantine configuration option. It can be defined
2961 with the config sub-command.
2962 MODULES_RUNENV_<VAR>
2964 Value to set to environment variable <VAR> for modulecmd.tcl
2965 run-time execution if <VAR> is referred in
2966 MODULES_RUN_QUARANTINE.
2967 MODULES_SEARCH_MATCH
2969 When searching for modules with avail sub-command, defines the
2970 way query string should match against available module names.
2971 With starts_with value, returned modules are those whose name
2972 begins by search query string. When set to contains, any modules
2973 whose fully qualified name contains search query string are re‐
2974 turned.
2975 This environment variable value supersedes the default value set
2977 in the search_match configuration option. It can be defined with
2978 the config sub-command. The --starts-with and --contains command
2979 line switches override this environment variable.
2980 MODULES_SET_SHELL_STARTUP
2982 If set to 1, defines when module command initializes the shell
2983 startup file to ensure that the module command is still defined
2984 in sub-shells. Setting shell startup file means defining the ENV
2985 and BASH_ENV environment variable to the Modules bourne shell
2986 initialization script. If set to 0, shell startup file is not
2987 defined.
2988 This environment variable value supersedes the default value set
2990 in the set_shell_startup configuration option. It can be defined
2991 with the config sub-command.
2992 To enable shell startup file, MODULES_SET_SHELL_STARTUP should
2994 be set to 1 prior Modules initialization or the
2995 set_shell_startup configuration option should be set to 1 in the
2996 initrc configuration file.
2997 MODULES_SHELLS_WITH_KSH_FPATH
2999 A list of shell on which the FPATH environment variable should
3000 be defined at initialization time to point to the ksh-functions
3001 directory where the ksh initialization script for module command
3002 is located. It enables for the listed shells to get module
3003 function defined when starting ksh as sub-shell from there.
3004 Accepted values are a list of shell among sh, bash, csh, tcsh
3006 and fish separated by colon character (:).
3007 This environment variable value supersedes the default value set
3009 in the shells_with_ksh_fpath configuration option. It can be de‐
3010 fined with the config sub-command.
3011 To enable the setup of FPATH for some shells,
3013 MODULES_SHELLS_WITH_KSH_FPATH should be set to the list of these
3014 shells prior Modules initialization or the shells_with_ksh_fpath
3015 configuration option should be set to the list of these shells
3016 in the initrc configuration file.
3017 MODULES_SILENT_SHELL_DEBUG
3019 If set to 1, disable any xtrace or verbose debugging property
3020 set on current shell session for the duration of either the mod‐
3021 ule command or the module shell initialization script. Only ap‐
3022 plies to Bourne Shell (sh) and its derivatives.
3023 This environment variable value supersedes the default value set
3025 in the silent_shell_debug configuration option. It can be de‐
3026 fined with the config sub-command.
3027 To generate the code to silence shell debugging property in the
3029 module shell function, MODULES_SILENT_SHELL_DEBUG should be set
3030 to 1 prior Modules initialization or the silent_shell_debug con‐
3031 figuration option should be set to 1 in the initrc configuration
3032 file.
3033 MODULES_SITECONFIG
3035 Location of a site-specific configuration script to source into
3036 modulecmd.tcl. See Site-specific configuration section for de‐
3037 tails.
3038 This environment variable value supersedes the default value set
3040 in the extra_siteconfig configuration option. It can be defined
3041 with the config sub-command. This environment variable is ig‐
3042 nored if extra_siteconfig has been declared locked in
3043 locked_configs configuration option.
3044 MODULES_TAG_ABBREV
3046 Specifies the abbreviation strings used to report module tags
3047 (see Module tags section). Its value is a colon-separated list
3048 of module tag names associated to an abbreviation string (e.g.
3049 tagname=abbrev).
3050 If a tag is associated to an empty string abbreviation, this tag
3052 will not be reported. In case the whole MODULES_TAG_ABBREV envi‐
3053 ronment variable is set to an empty string, tags are reported
3054 but not abbreviated.
3055 This environment variable value supersedes the default value set
3057 in the tag_abbrev configuration option. It can be defined with
3058 the config sub-command.
3059 MODULES_TAG_COLOR_NAME
3061 Specifies the tag names or abbreviations whose graphical render‐
3062 ing should be applied over themselves instead of being applied
3063 over the name of the module they are attached to. Value of
3064 MODULES_TAG_COLOR_NAME is a colon-separated list of module tag
3065 names or abbreviation strings (see Module tags section).
3066 When a select graphic rendition is defined for a tag name or a
3068 tag abbreviation string, it is applied over the module name as‐
3069 sociated with the tag and tag name or abbreviation is not dis‐
3070 played. When listed in MODULES_TAG_COLOR_NAME environment vari‐
3071 able, a tag name or abbreviation is displayed and select graphic
3072 rendition is applied over it.
3073 This environment variable value supersedes the default value set
3075 in the tag_color_name configuration option. It can be defined
3076 with the config sub-command.
3077 MODULES_TCL_LINTER
3079 Command name or path for use to check syntax of modulefile
3080 through the lint sub-command.
3081 This environment variable value supersedes the default value set
3083 in the tcl_linter configuration option. It can be defined with
3084 the config sub-command.
3085 MODULES_TERM_BACKGROUND
3087 Inform Modules of the terminal background color to determine if
3088 the color set for dark background or the color set for light
3089 background should be used to color output in case no specific
3090 color set is defined with the MODULES_COLORS variable. Accepted
3091 values are dark and light.
3092 This environment variable value supersedes the default value set
3094 in the term_background configuration option. It can be defined
3095 with the config sub-command.
3096 MODULES_TERM_WIDTH
3098 Specifies the number of columns of the output. If set to 0, the
3099 output width will be the full terminal width, which is automati‐
3100 cally detected by the module command. Accepted values are inte‐
3101 gers comprised between 0 and 1000.
3102 This environment variable value supersedes the default value set
3104 in the term_width configuration option. It can be defined with
3105 the config sub-command. The --width/-w command line switches
3106 override this environment variable.
3107 MODULES_UNLOAD_MATCH_ORDER
3109 When a module unload request matches multiple loaded modules,
3110 unload firstly loaded module or lastly loaded module. Accepted
3111 values are returnfirst and returnlast.
3112 This environment variable value supersedes the default value set
3114 in the unload_match_order configuration option. It can be de‐
3115 fined with the config sub-command.
3116 MODULES_VARIANT_SHORTCUT
3118 Specifies the shortcut characters that could be used to specify
3119 and report module variants (see Module variants section). Its
3120 value is a colon-separated list of variant names associated to a
3121 shortcut character (e.g., variantname=shortcutchar).
3122 A variant shortcut must be of one character length and must
3124 avoid characters used for other concerns or in module names
3125 (i.e., [-+~/@=a-zA-Z0-9]).
3126 If a shortcut is associated to an empty string or an invalid
3128 character, this shortcut definition will be ignored.
3129 This environment variable value supersedes the default value set
3131 in the variant_shortcut configuration option. It can be defined
3132 with the config sub-command.
3133 MODULES_VERBOSITY
3135 Defines the verbosity level of the module command. Available
3136 verbosity levels from the least to the most verbose are:
3137 • silent: turn off error, warning and informational messages but
3139 does not affect module command output result.
3140 • concise: enable error and warning messages but disable infor‐
3142 mational messages.
3143 • normal: turn on informational messages, like a report of the
3145 additional module evaluations triggered by loading or unload‐
3146 ing modules, aborted evaluation issues or a report of each
3147 module evaluation occurring during a restore or source
3148 sub-commands.
3149 • verbose: add additional informational messages, like a system‐
3151 atic report of the loading or unloading module evaluations.
3152 • verbose2: report loading or unloading module evaluations of
3154 hidden-loaded modules, report if loading module is already
3155 loaded or if unloading module is not loaded.
3156 • trace: provide details on module searches, resolutions, selec‐
3158 tions and evaluations.
3159 • debug: print debugging messages about module command execu‐
3161 tion.
3162 • debug2: report modulecmd.tcl procedure calls in addition to
3164 printing debug messages.
3165 This environment variable value supersedes the default value set
3167 in the verbosity configuration option. It can be defined with
3168 the config sub-command. The --silent, --verbose, --debug and
3169 --trace command line switches override this environment vari‐
3170 able.
3171 MODULES_WA_277
3173 If set to 1 prior to Modules package initialization, enables
3174 workaround for Tcsh history issue (see
3175 https://github.com/cea-hpc/modules/issues/277). This issue
3176 leads to erroneous history entries under Tcsh shell. When work‐
3177 around is enabled, an alternative module alias is defined which
3178 fixes the history mechanism issue. However the alternative defi‐
3179 nition of the module alias weakens shell evaluation of the code
3180 produced by modulefiles. Characters with a special meaning for
3181 Tcsh shell (like { and }) may not be used anymore in shell alias
3182 definition otherwise the evaluation of the code produced by mod‐
3183 ulefiles will return a syntax error.
3184 This environment variable value supersedes the default value set
3186 in the wa_277 configuration option. It can be defined with the
3187 config sub-command.
3188 To enable this workaround, MODULES_WA_277 should be set to 1
3190 prior Modules initialization or the wa_277 configuration option
3191 should be set to 1 in the initrc configuration file.
3192 MODULESHOME
3194 The location of the main Modules package file directory contain‐
3195 ing module command initialization scripts, the executable pro‐
3196 gram modulecmd.tcl, and a directory containing a collection of
3197 main modulefiles.
3198 This environment variable value supersedes the default value set
3200 in the home configuration option. It can be defined with the
3201 config sub-command.
3202
3204 /usr/share/Modules
3205 The MODULESHOME directory.
3206 /etc/environment-modules/initrc
3208 The configuration file evaluated by modulecmd.tcl when it initial‐
3209 izes to enable the default modulepaths, load the default modules and
3210 set module command configuration.
3211 initrc is a modulefile(4) so it is written as a Tcl script and de‐
3213 fines modulepaths to enable with module use, modules to load with
3214 module load and configuration to apply with module config. As any
3215 modulefile initrc must begin with the Modules magic cookie (i.e.,
3216 #%Module file signature).
3217 initrc is optional. When this configuration file is present it is
3219 evaluated after the modulespath configuration file. See the Package
3220 Initialization section for details.
3221 /etc/environment-modules/modulespath
3223 The configuration file evaluated by modulecmd.tcl when it initial‐
3224 izes to enable the default modulepaths. This file contains the list
3225 of modulepaths separated by either newline or colon characters.
3226 modulespath is optional. When this configuration file is present it
3228 is evaluated before the initrc configuration file. See the Package
3229 Initialization section for details.
3230 /etc/environment-modules/siteconfig.tcl
3232 The site-specific configuration script of modulecmd.tcl. An addi‐
3233 tional configuration script could be defined using the
3234 MODULES_SITECONFIG environment variable. See Site-specific configu‐
3235 ration for detailed information.
3236 /etc/environment-modules/rc
3238 The system-wide modules rc file. The location of this file can be
3239 changed using the MODULERCFILE environment variable as described
3240 above.
3241 $HOME/.modulerc
3243 The user specific modules rc file.
3244 $HOME/.module
3246 The user specific collection directory.
3247 /usr/share/Modules/modulefiles
3249 The directory for system-wide modulefiles. The location of the di‐
3250 rectory can be changed using the MODULEPATH environment variable as
3251 described above.
3252 /usr/share/Modules/libexec/modulecmd.tcl
3254 The modulefile interpreter that gets executed upon each invocation
3255 of module.
3256 /usr/share/Modules/init/<shell>
3258 The Modules package initialization file sourced into the user's en‐
3259 vironment.
3260
3262 ml(1), modulefile(4)
3263
3265 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
3266 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2022 Xavier Delaruelle
32675.2.0 2022-11-08 MODULE(1)