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 creates the module command as either an alias or function and
37 creates Modules environment variables.
38 The module alias or function executes the modulecmd.tcl program located
40 in /usr/share/Modules/libexec and has the shell evaluate the command's
41 output. The first argument to modulecmd.tcl specifies the type of
42 shell.
43 The initialization scripts are kept in /usr/share/Modules/init/<shell>
45 where <shell> is the name of the sourcing shell. For example, a C Shell
46 user sources the /usr/share/Modules/init/csh script. The sh, csh, tcsh,
47 bash, ksh, zsh and fish shells are supported by modulecmd.tcl. In addi‐
48 tion, python, perl, ruby, tcl, cmake, r and lisp "shells" are supported
49 which writes the environment changes to stdout as python, perl, ruby,
50 tcl, lisp, r or cmake code.
51 Initialization may also be performed by calling the autoinit sub-com‐
53 mand of the modulecmd.tcl program. Evaluation into the shell of the
54 result of this command defines the module alias or function.
55 A ml alias or function may also be defined at initialization time if
57 enabled (see MODULES_ML section). ml is a handy frontend leveraging all
58 module command capabilities with less character typed. See ml(1) for
59 detailed information.
60 Examples of initialization
62 C Shell initialization (and derivatives):
63 source /usr/share/Modules/init/csh
65 module load modulefile modulefile ...
66 Bourne Shell (sh) (and derivatives):
68 . /usr/share/Modules/init/sh
70 module load modulefile modulefile ...
71 Perl:
73 require "/usr/share/Modules/init/perl.pm";
75 &module('load', 'modulefile', 'modulefile', '...');
76 Python:
78 import os
80 exec(open('/usr/share/Modules/init/python.py').read())
81 module('load', 'modulefile', 'modulefile', '...')
82 Bourne Shell (sh) (and derivatives) with autoinit sub-command:
84 eval "`/usr/share/Modules/libexec/modulecmd.tcl sh autoinit`"
86 Modulecmd startup
88 Upon invocation modulecmd.tcl sources a site-specific configuration
89 script if it exists. The location for this script is /etc/environment-
90 modules/siteconfig.tcl. An additional siteconfig script may be speci‐
91 fied with the MODULES_SITECONFIG environment variable, if allowed by
92 modulecmd.tcl configuration, and will be loaded if it exists after
93 /etc/environment-modules/siteconfig.tcl. Siteconfig is a Tcl script
94 that enables to supersede any global variable or procedure definition
95 of modulecmd.tcl.
96 Afterward, modulecmd.tcl sources rc files which contain global, user
98 and modulefile specific setups. These files are interpreted as module‐
99 files. See modulefile(4) for detailed information.
100 Upon invocation of modulecmd.tcl module run-command files are sourced
102 in the following order:
103 1. Global RC file as specified by MODULERCFILE variable or /etc/envi‐
105 ronment-modules/rc. If MODULERCFILE points to a directory, the mod‐
106 ulerc file in this directory is used as global RC file.
107 2. User specific module RC file $HOME/.modulerc
109 3. All .modulerc and .version files found during modulefile seeking.
111 Command line switches
113 The module command accepts command line switches as its first parame‐
114 ter. These may be used to control output format of all information dis‐
115 played and the module behavior in case of locating and interpreting
116 modulefiles.
117 All switches may be entered either in short or long notation. The fol‐
119 lowing switches are accepted:
120 --auto On load, unload and switch sub-commands, enable automated module
122 handling mode. See also MODULES_AUTO_HANDLING section.
123 --color=<WHEN>
125 Colorize the output. WHEN defaults to always or can be never or
126 auto. See also MODULES_COLOR section.
127 --contains, -C
129 On avail sub-command, return modules whose fully qualified name
130 contains search query string.
131 --debug, -D
133 Debug mode. Causes module to print debugging messages about its
134 progress.
135 --default, -d
137 On avail sub-command, display only the default version of each
138 module name. Default version is the explicitly set default ver‐
139 sion or also the implicit default version if the configuration
140 option implicit_default is enabled (see Locating Modulefiles
141 section in the modulefile(4) man page for further details on
142 implicit default version).
143 --force, -f
145 On load, unload and switch sub-commands, by-pass any unsatisfied
146 modulefile constraint corresponding to the declared prereq and
147 conflict. Which means for instance that a modulefile will be
148 loaded even if it comes in conflict with another loaded module‐
149 file or that a modulefile will be unloaded even if it is
150 required as a prereq by another modulefile.
151 On clear sub-command, skip the confirmation dialog and proceed.
153 --help, -h
155 Give some helpful usage information, and terminates the command.
156 --icase, -i
158 Match module specification arguments in a case insensitive man‐
159 ner.
160 --indepth
162 On avail sub-command, include in search results the matching
163 modulefiles and directories and recursively the modulefiles and
164 directories contained in these matching directories.
165 --json, -j
167 Display avail, list, savelist, whatis and search output in JSON
168 format.
169 --latest, -L
171 On avail sub-command, display only the highest numerically
172 sorted version of each module name (see Locating Modulefiles
173 section in the modulefile(4) man page).
174 --long, -l
176 Display avail, list and savelist output in long format.
177 --no-auto
179 On load, unload and switch sub-commands, disable automated mod‐
180 ule handling mode. See also MODULES_AUTO_HANDLING section.
181 --no-indepth
183 On avail sub-command, limit search results to the matching mod‐
184 ulefiles and directories found at the depth level expressed by
185 the search query. Thus modulefiles contained in directories part
186 of the result are excluded.
187 --no-pager
189 Do not pipe message output into a pager.
190 --paginate
192 Pipe all message output into less (or if set, to the command
193 referred in MODULES_PAGER variable) if error output stream is a
194 terminal. See also MODULES_PAGER section.
195 --silent, -s
197 Turn off error, warning and informational messages. module com‐
198 mand output result is not affected by silent mode.
199 --starts-with, -S
201 On avail sub-command, return modules whose name starts with
202 search query string.
203 --terse, -t
205 Display avail, list and savelist output in short format.
206 --verbose, -v
208 Enable verbose messages during module command execution.
209 --version, -V
211 Lists the current version of the module command. The command
212 then terminates without further processing.
213 Module Sub-Commands
215 add modulefile...
216 See load.
217 aliases
219 List all available symbolic version-names and aliases in the
220 current MODULEPATH. All directories in the MODULEPATH are
221 recursively searched in the same manner than for the avail
222 sub-command. Only the symbolic version-names and aliases found
223 in the search are displayed.
224 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
226 Append value to environment variable. The variable is a colon,
227 or delimiter, separated list. See append-path in the module‐
228 file(4) man page for further explanation.
229 apropos [-j] string
231 See search.
232 avail [-d|-L] [-t|-l|-j] [-S|-C] [--indepth|--no-indepth] [path...]
234 List all available modulefiles in the current MODULEPATH. All
235 directories in the MODULEPATH are recursively searched for files
236 containing the modulefile magic cookie. If an argument is given,
237 then each directory in the MODULEPATH is searched for module‐
238 files whose pathname, symbolic version-name or alias match the
239 argument. Argument may contain wildcard characters. Multiple
240 versions of an application can be supported by creating a subdi‐
241 rectory for the application containing modulefiles for each ver‐
242 sion.
243 Symbolic version-names and aliases found in the search are dis‐
245 played in the result of this sub-command. Symbolic version-names
246 are displayed next to the modulefile they are assigned to within
247 parenthesis. Aliases are listed in the MODULEPATH section where
248 they have been defined. To distinguish aliases from modulefiles
249 a @ symbol is added within parenthesis next to their name.
250 Aliases defined through a global or user specific module RC file
251 are listed under the global/user modulerc section.
252 When colored output is enabled and a specific graphical rendi‐
254 tion is defined for module default version, the default symbol
255 is omitted and instead the defined graphical rendition is
256 applied to the relative modulefile. When colored output is
257 enabled and a specific graphical rendition is defined for module
258 alias, the @ symbol is omitted. The defined graphical rendition
259 applies to the module alias name. See MODULES_COLOR and
260 MODULES_COLORS sections for details on colored output.
261 The parameter path may also refer to a symbolic modulefile name
263 or a modulefile alias. It may also leverage a specific syntax to
264 finely select module version (see Advanced module version speci‐
265 fiers section below).
266 clear [-f]
268 Force the Modules package to believe that no modules are cur‐
269 rently loaded. A confirmation is requested if command-line
270 switch -f (or --force) is not passed. Typed confirmation should
271 equal to yes or y in order to proceed.
272 config [--dump-state|name [value]|--reset name]
274 Gets or sets modulecmd.tcl options. Reports the currently set
275 value of passed option name or all existing options if no name
276 passed. If a name and a value are provided, the value of option
277 name is set to value. If command-line switch --reset is passed
278 in addition to a name, overridden value for option name is
279 cleared.
280 When a reported option value differs from default value a men‐
282 tion is added to indicate whether the overridden value is coming
283 from a command-line switch (cmd-line) or from an environment
284 variable (env-var). When a reported option value is locked and
285 cannot be altered a (locked) mention is added.
286 If no value is currently set for an option name, the mention
288 <undef> is reported.
289 When command-line switch --dump-state is passed, current mod‐
291 ulecmd.tcl state and Modules-related environment variables are
292 reported in addition to currently set modulecmd.tcl options.
293 Existing option names are:
295 · advanced_version_spec: advanced module version specification
297 to finely select modulefiles (defines environment variable
298 MODULES_ADVANCED_VERSION_SPEC when set
299 · auto_handling: automated module handling mode (defines
301 MODULES_AUTO_HANDLING)
302 · avail_indepth: avail sub-command in depth search mode (defines
304 MODULES_AVAIL_INDEPTH)
305 · avail_report_dir_sym: display symbolic versions targeting
307 directories on avail sub-command
308 · avail_report_mfile_sym: display symbolic versions targeting
310 modulefiles on avail sub-command
311 · collection_pin_version: register exact modulefile version in
313 collection (defines MODULES_COLLECTION_PIN_VERSION)
314 · collection_target: collection target which is valid for cur‐
316 rent system (defines MODULES_COLLECTION_TARGET)
317 · color: colored output mode (defines MODULES_COLOR)
319 · colors: chosen colors to highlight output items (defines
321 MODULES_COLORS)
322 · contact: modulefile contact address (defines MODULECONTACT)
324 · extended_default: allow partial module version specification
326 (defines MODULES_EXTENDED_DEFAULT)
327 · extra_siteconfig: additional site-specific configuration
329 script location (defines MODULES_SITECONFIG)
330 · home: location of Modules package master directory (defines
332 MODULESHOME)
333 · icase: enable case insensitive match (defines MODULES_ICASE)
335 · ignored_dirs: directories ignored when looking for modulefiles
337 · implicit_default: set an implicit default version for modules
339 (defines MODULES_IMPLICIT_DEFAULT)
340 · locked_configs: configuration options that cannot be super‐
342 seded
343 · ml: define ml command at initialization time (defines
345 MODULES_ML)
346 · pager: text viewer to paginate message output (defines
348 MODULES_PAGER)
349 · rcfile: global run-command file location (defines
351 MODULERCFILE)
352 · run_quarantine: environment variables to indirectly pass to
354 modulecmd.tcl (defines MODULES_RUN_QUARANTINE)
355 · silent_shell_debug: disablement of shell debugging property
357 for the module command (defines MODULES_SILENT_SHELL_DEBUG)
358 · search_match: module search match style (defines
360 MODULES_SEARCH_MATCH)
361 · set_shell_startup: ensure module command definition by setting
363 shell startup file (defines MODULES_SET_SHELL_STARTUP)
364 · siteconfig: primary site-specific configuration script loca‐
366 tion
367 · tcl_ext_lib: Modules Tcl extension library location
369 · term_background: terminal background color kind (defines
371 MODULES_TERM_BACKGROUND)
372 · unload_match_order: unload firstly loaded or lastly loaded
374 module matching request (defines MODULES_UNLOAD_MATCH_ORDER)
375 · verbosity: module command verbosity level (defines
377 MODULES_VERBOSITY)
378 · wa_277: workaround for Tcsh history issue (defines
380 MODULES_WA_277)
381 The options avail_report_dir_sym, avail_report_mfile_sym,
383 ignored_dirs, locked_configs, siteconfig and tcl_ext_lib cannot
384 be altered. Moreover all options referred in locked_configs
385 value are locked, thus they cannot be altered.
386 display modulefile...
388 Display information about one or more modulefiles. The display
389 sub-command will list the full path of the modulefile and the
390 environment changes the modulefile will make if loaded. (Note:
391 It will not display any environment changes found within condi‐
392 tional statements.)
393 The parameter modulefile may also be a symbolic modulefile name
395 or a modulefile alias. It may also leverage a specific syntax to
396 finely select module version (see Advanced module version speci‐
397 fiers section below).
398 help [modulefile...]
400 Print the usage of each sub-command. If an argument is given,
401 print the Module-specific help information for the modulefile.
402 The parameter modulefile may also be a symbolic modulefile name
404 or a modulefile alias. It may also leverage a specific syntax to
405 finely select module version (see Advanced module version speci‐
406 fiers section below).
407 info-loaded modulefile
409 Returns the names of currently loaded modules matching passed
410 modulefile. Returns an empty string if passed modulefile does
411 not match any loaded modules. See module-info loaded in the mod‐
412 ulefile(4) man page for further explanation.
413 initadd modulefile...
415 Add modulefile to the shell's initialization file in the user's
416 home directory. The startup files checked (in order) are:
417 C Shell
419 .modules, .cshrc, .csh_variables and .login
420 TENEX C Shell
422 .modules, .tcshrc, .cshrc, .csh_variables and .login
423 Bourne and Korn Shells
425 .modules, .profile
426 GNU Bourne Again Shell
428 .modules, .bash_profile, .bash_login, .profile and .bashrc
429 Z Shell
431 .modules, .zshrc, .zshenv and .zlogin
432 Friendly Interactive Shell
434 .modules, .config/fish/config.fish
435 If a module load line is found in any of these files, the mod‐
437 ulefiles are appended to any existing list of modulefiles. The
438 module load line must be located in at least one of the files
439 listed above for any of the init sub-commands to work properly.
440 If the module load line is found in multiple shell initializa‐
441 tion files, all of the lines are changed.
442 initclear
444 Clear all of the modulefiles from the shell's initialization
445 files.
446 initlist
448 List all of the modulefiles loaded from the shell's initializa‐
449 tion file.
450 initprepend modulefile...
452 Does the same as initadd but prepends the given modules to the
453 beginning of the list.
454 initrm modulefile...
456 Remove modulefile from the shell's initialization files.
457 initswitch modulefile1 modulefile2
459 Switch modulefile1 with modulefile2 in the shell's initializa‐
460 tion files.
461 is-avail modulefile...
463 Returns a true value if any of the listed modulefiles exists in
464 enabled MODULEPATH. Returns a false value otherwise. See
465 is-avail in the modulefile(4) man page for further explanation.
466 The parameter modulefile may also be a symbolic modulefile name
468 or a modulefile alias. It may also leverage a specific syntax to
469 finely select module version (see Advanced module version speci‐
470 fiers section below).
471 is-loaded [modulefile...]
473 Returns a true value if any of the listed modulefiles has been
474 loaded or if any modulefile is loaded in case no argument is
475 provided. Returns a false value otherwise. See is-loaded in the
476 modulefile(4) man page for further explanation.
477 The parameter modulefile may also be a symbolic modulefile name
479 or a modulefile alias. It may also leverage a specific syntax to
480 finely select module version (see Advanced module version speci‐
481 fiers section below).
482 is-saved [collection...]
484 Returns a true value if any of the listed collections exists or
485 if any collection exists in case no argument is provided.
486 Returns a false value otherwise. See is-saved in the module‐
487 file(4) man page for further explanation.
488 is-used [directory...]
490 Returns a true value if any of the listed directories has been
491 enabled in MODULEPATH or if any directory is enabled in case no
492 argument is provided. Returns a false value otherwise. See
493 is-used in the modulefile(4) man page for further explanation.
494 keyword [-j] string
496 See search.
497 list [-t|-l|-j]
499 List loaded modules.
500 load [--auto|--no-auto] [-f] modulefile...
502 Load modulefile into the shell environment.
503 The parameter modulefile may also be a symbolic modulefile name
505 or a modulefile alias. It may also leverage a specific syntax to
506 finely select module version (see Advanced module version speci‐
507 fiers section below).
508 path modulefile
510 Print path to modulefile.
511 The parameter modulefile may also be a symbolic modulefile name
513 or a modulefile alias. It may also leverage a specific syntax to
514 finely select module version (see Advanced module version speci‐
515 fiers section below).
516 paths modulefile
518 Print path of available modulefiles matching argument.
519 The parameter modulefile may also be a symbolic modulefile name
521 or a modulefile alias. It may also leverage a specific syntax to
522 finely select module version (see Advanced module version speci‐
523 fiers section below).
524 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
526 value...
527 Prepend value to environment variable. The variable is a colon,
528 or delimiter, separated list. See prepend-path in the module‐
529 file(4) man page for further explanation.
530 purge Unload all loaded modulefiles.
532 refresh
534 See reload.
535 reload Unload then load all loaded modulefiles.
537 No unload then load is performed and an error is returned if the
539 loaded modulefiles have unsatisfied constraint corresponding to
540 the prereq and conflict they declare.
541 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
543 Remove value from the colon, or delimiter, separated list in
544 environment variable. See remove-path in the modulefile(4) man
545 page for further explanation.
546 restore [collection]
548 Restore the environment state as defined in collection. If col‐
549 lection name is not specified, then it is assumed to be the
550 default collection. If collection is a fully qualified path, it
551 is restored from this location rather than from a file under the
552 user's collection directory. If MODULES_COLLECTION_TARGET is
553 set, a suffix equivalent to the value of this variable is
554 appended to the collection file name to restore.
555 When restoring a collection, the currently set MODULEPATH direc‐
557 tory list and the currently loaded modulefiles are unused and
558 unloaded then used and loaded to exactly match the MODULEPATH
559 and loaded modulefiles lists saved in this collection file. The
560 order of the paths and modulefiles set in collection is pre‐
561 served when restoring. It means that currently loaded modules
562 are unloaded to get the same LOADEDMODULES root than collection
563 and currently used module paths are unused to get the same MOD‐
564 ULEPATH root. Then missing module paths are used and missing
565 modulefiles are loaded.
566 If a module, without a default version explicitly defined, is
568 recorded in a collection by its bare name: loading this module
569 when restoring the collection will fail if the configuration
570 option implicit_default is disabled.
571 rm modulefile...
573 See unload.
574 save [collection]
576 Record the currently set MODULEPATH directory list and the cur‐
577 rently loaded modulefiles in a collection file under the user's
578 collection directory $HOME/.module. If collection name is not
579 specified, then it is assumed to be the default collection. If
580 collection is a fully qualified path, it is saved at this loca‐
581 tion rather than under the user's collection directory.
582 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
584 value of this variable will be appended to the collection file
585 name.
586 By default, if a loaded modulefile corresponds to the explicitly
588 defined default module version, the bare module name is
589 recorded. If the configuration option implicit_default is
590 enabled, the bare module name is also recorded for the implicit
591 default module version. If MODULES_COLLECTION_PIN_VERSION is set
592 to 1, module version is always recorded even if it is the
593 default version.
594 No collection is recorded and an error is returned if the loaded
596 modulefiles have unsatisfied constraint corresponding to the
597 prereq and conflict they declare.
598 savelist [-t|-l|-j]
600 List collections that are currently saved under the user's col‐
601 lection directory. If MODULES_COLLECTION_TARGET is set, only
602 collections matching the target suffix will be displayed.
603 saverm [collection]
605 Delete the collection file under the user's collection direc‐
606 tory. If collection name is not specified, then it is assumed to
607 be the default collection. If MODULES_COLLECTION_TARGET is set,
608 a suffix equivalent to the value of this variable will be
609 appended to the collection file name.
610 saveshow [collection]
612 Display the content of collection. If collection name is not
613 specified, then it is assumed to be the default collection. If
614 collection is a fully qualified path, this location is displayed
615 rather than a collection file under the user's collection direc‐
616 tory. If MODULES_COLLECTION_TARGET is set, a suffix equivalent
617 to the value of this variable will be appended to the collection
618 file name.
619 search [-j] string
621 Seeks through the module-whatis informations of all modulefiles
622 for the specified string. All module-whatis informations match‐
623 ing the string in a case insensitive manner will be displayed.
624 string may contain wildcard characters.
625 show modulefile...
627 See display.
628 source scriptfile...
630 Execute scriptfile into the shell environment. scriptfile must
631 be written with modulefile syntax and specified with a fully
632 qualified path. Once executed scriptfile is not marked loaded in
633 shell environment which differ from load sub-command.
634 swap [modulefile1] modulefile2
636 See switch.
637 switch [--auto|--no-auto] [-f] [modulefile1] modulefile2
639 Switch loaded modulefile1 with modulefile2. If modulefile1 is
640 not specified, then it is assumed to be the currently loaded
641 module with the same root name as modulefile2.
642 The parameter modulefile may also be a symbolic modulefile name
644 or a modulefile alias. It may also leverage a specific syntax to
645 finely select module version (see Advanced module version speci‐
646 fiers section below).
647 test modulefile...
649 Execute and display results of the Module-specific tests for the
650 modulefile.
651 The parameter modulefile may also be a symbolic modulefile name
653 or a modulefile alias. It may also leverage a specific syntax to
654 finely select module version (see Advanced module version speci‐
655 fiers section below).
656 unload [--auto|--no-auto] [-f] modulefile...
658 Remove modulefile from the shell environment.
659 The parameter modulefile may also be a symbolic modulefile name
661 or a modulefile alias. It may also leverage a specific syntax to
662 finely select module version (see Advanced module version speci‐
663 fiers section below).
664 unuse directory...
666 Remove one or more directories from the MODULEPATH environment
667 variable if reference counter of these directories is equal to 1
668 or unknown.
669 Reference counter of directory in MODULEPATH denotes the number
671 of times directory has been enabled. When attempting to remove
672 directory from MODULEPATH, reference counter variable
673 MODULEPATH_modshare is checked and directory is removed only if
674 its relative counter is equal to 1 or not defined. Otherwise
675 directory is kept and reference counter is decreased by 1.
676 use [-a|--append] directory...
678 Prepend one or more directories to the MODULEPATH environment
679 variable. The --append flag will append the directory to MOD‐
680 ULEPATH.
681 Reference counter environment variable MODULEPATH_modshare is
683 also set to increase the number of times directory has been
684 added to MODULEPATH.
685 whatis [-j] [modulefile...]
687 Display the information set up by the module-whatis commands
688 inside the specified modulefiles. These specified modulefiles
689 may be expressed using wildcard characters. If no modulefile is
690 specified, all module-whatis lines will be shown.
691 The parameter modulefile may also be a symbolic modulefile name
693 or a modulefile alias. It may also leverage a specific syntax to
694 finely select module version (see Advanced module version speci‐
695 fiers section below).
696 Modulefiles
698 modulefiles are written in the Tool Command Language (Tcl) and are
699 interpreted by modulecmd.tcl. modulefiles can use conditional state‐
700 ments. Thus the effect a modulefile will have on the environment may
701 change depending upon the current state of the environment.
702 Environment variables are unset when unloading a modulefile. Thus, it
704 is possible to load a modulefile and then unload it without having the
705 environment variables return to their prior state.
706 Advanced module version specifiers
708 When the advanced module version specifiers mechanism is enabled (see
709 MODULES_ADVANCED_VERSION_SPEC), the specification of modulefile passed
710 on Modules sub-commands changes. After the module name a version con‐
711 straint prefixed by the @ character may be added. It could be directly
712 appended to the module name or separated from it with a space charac‐
713 ter.
714 Constraints can be expressed to refine the selection of module version
716 to:
717 · a single version with the @version syntax, for instance foo@1.2.3
719 syntax will select module foo/1.2.3
720 · a list of versions with the @version1,version2,... syntax, for
722 instance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
723 · a range of versions with the @version1:, @:version2 and @ver‐
725 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
726 sions of module foo greater than or equal to 1.2, foo@:1.3 will
727 select all versions less than or equal to 1.3 and foo@1.2:1.3 matches
728 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
729 Advanced specification of single version or list of versions may bene‐
731 fit from the activation of the extended default mechanism (see
732 MODULES_EXTENDED_DEFAULT) to use an abbreviated notation like @1 to
733 refer to more precise version numbers like 1.2.3. Range of versions on
734 its side natively handles abbreviated versions.
735 In order to be specified in a range of versions or compared to a range
737 of versions, the version major element should corresponds to a number.
738 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
739 whereas default or foo.2 versions are invalid for range comparison.
740 If the implicit default mechanism is also enabled (see
742 MODULES_IMPLICIT_DEFAULT), a default and latest symbolic versions are
743 automatically defined for each module name (also at each directory
744 level for deep modulefiles). These automatic version symbols are
745 defined unless a symbolic version, alias, or regular module version
746 already exists for these default or latest version names. Using the
747 mod@latest (or mod/latest) syntax ensures highest available version
748 will be selected.
749 Collections
751 Collections describe a sequence of module use then module load commands
752 that are interpreted by modulecmd.tcl to set the user environment as
753 described by this sequence. When a collection is activated, with the
754 restore sub-command, module paths and loaded modules are unused or
755 unloaded if they are not part or if they are not ordered the same way
756 as in the collection.
757 Collections are generated by the save sub-command that dumps the cur‐
759 rent user environment state in terms of module paths and loaded mod‐
760 ules. By default collections are saved under the $HOME/.module direc‐
761 tory.
762 Collections may be valid for a given target if they are suffixed. In
764 this case these collections can only be restored if their suffix corre‐
765 spond to the current value of the MODULES_COLLECTION_TARGET environment
766 variable (see the dedicated section of this topic below).
767
769 The module command exits with 0 if its execution succeed. Otherwise 1
770 is returned.
771
773 _LMFILES_
774 A colon separated list of the full pathname for all loaded mod‐
775 ulefiles.
776 LOADEDMODULES
778 A colon separated list of all loaded modulefiles.
779 MODULECONTACT
781 Email address to contact in case any issue occurs during the
782 interpretation of modulefiles.
783 MODULEPATH
785 The path that the module command searches when looking for mod‐
786 ulefiles. Typically, it is set to the master modulefiles direc‐
787 tory, /usr/share/Modules/modulefiles, by the initialization
788 script. MODULEPATH can be set using module use or by the module
789 initialization script to search group or personal modulefile
790 directories before or after the master modulefile directory.
791 Path elements registered in the MODULEPATH environment variable
793 may contain reference to environment variables which are con‐
794 verted to their corresponding value by module command each time
795 it looks at the MODULEPATH value. If an environment variable
796 referred in a path element is not defined, its reference is con‐
797 verted to an empty string.
798 MODULERCFILE
800 The location of a global run-command file containing modulefile
801 specific setup. See Modulecmd startup section for detailed
802 information.
803 MODULES_ADVANCED_VERSION_SPEC
805 If set to 1, enable advanced module version specifiers (see
806 Advanced module version specifiers section). If set to 0, dis‐
807 able advanced module version specifiers.
808 Advanced module version specifiers enablement is defined in the
810 following order of preference: MODULES_ADVANCED_VERSION_SPEC
811 environment variable then the default set in modulecmd.tcl
812 script configuration. Which means MODULES_ADVANCED_VERSION_SPEC
813 overrides default configuration.
814 MODULES_AUTO_HANDLING
816 If set to 1, enable automated module handling mode. If set to 0
817 disable automated module handling mode. Other values are
818 ignored.
819 Automated module handling mode consists in additional actions
821 triggered when loading or unloading a modulefile to satisfy the
822 constraints it declares. When loading a modulefile, following
823 actions are triggered:
824 · Requirement Load: load of the modulefiles declared as a prereq
826 of the loading modulefile.
827 · Dependent Reload: reload of the modulefiles declaring a prereq
829 onto loaded modulefile or declaring a prereq onto a modulefile
830 part of this reloading batch.
831 When unloading a modulefile, following actions are triggered:
833 · Dependent Unload: unload of the modulefiles declaring a
835 non-optional prereq onto unloaded modulefile or declaring a
836 non-optional prereq onto a modulefile part of this unloading
837 batch. A prereq modulefile is considered optional if the pre‐
838 req definition order is made of multiple modulefiles and at
839 least one alternative modulefile is loaded.
840 · Useless Requirement Unload: unload of the prereq modulefiles
842 that have been automatically loaded for either the unloaded
843 modulefile, an unloaded dependent modulefile or a modulefile
844 part of this useless requirement unloading batch. Modulefiles
845 are added to this unloading batch only if they are not
846 required by any other loaded modulefiles.
847 · Dependent Reload: reload of the modulefiles declaring a con‐
849 flict or an optional prereq onto either the unloaded module‐
850 file, an unloaded dependent or an unloaded useless requirement
851 or declaring a prereq onto a modulefile part of this reloading
852 batch.
853 In case a loaded modulefile has some of its declared constraints
855 unsatisfied (pre-required modulefile not loaded or conflicting
856 modulefile loaded for instance), this loaded modulefile is
857 excluded from the automatic reload actions described above.
858 For the specific case of the switch sub-command, where a module‐
860 file is unloaded to then load another modulefile. Dependent mod‐
861 ulefiles to Unload are merged into the Dependent modulefiles to
862 Reload that are reloaded after the load of the switched-to mod‐
863 ulefile.
864 Automated module handling mode enablement is defined in the fol‐
866 lowing order of preference: --auto/--no-auto command line
867 switches, then MODULES_AUTO_HANDLING environment variable, then
868 the default set in modulecmd.tcl script configuration. Which
869 means MODULES_AUTO_HANDLING overrides default configuration and
870 --auto/--no-auto command line switches override every other ways
871 to enable or disable this mode.
872 MODULES_AVAIL_INDEPTH
874 If set to 1, enable in depth search results for avail sub-com‐
875 mand. If set to 0 disable avail sub-command in depth mode. Other
876 values are ignored.
877 When in depth mode is enabled, modulefiles and directories con‐
879 tained in directories matching search query are also included in
880 search results. When disabled these modulefiles and directories
881 contained in matching directories are excluded.
882 avail sub-command in depth mode enablement is defined in the
884 following order of preference: --indepth/--no-indepth command
885 line switches, then MODULES_AVAIL_INDEPTH environment variable,
886 then the default set in modulecmd.tcl script configuration.
887 Which means MODULES_AVAIL_INDEPTH overrides default configura‐
888 tion and --indepth/--no-indepth command line switches override
889 every other ways to enable or disable this mode.
890 MODULES_CMD
892 The location of the active module command script.
893 MODULES_COLLECTION_PIN_VERSION
895 If set to 1, register exact version number of modulefiles when
896 saving a collection. Otherwise modulefile version number is
897 omitted if it corresponds to the explicitly set default version
898 and also to the implicit default when the configuration option
899 implicit_default is enabled.
900 MODULES_COLLECTION_TARGET
902 The collection target that determines what collections are valid
903 thus reachable on the current system.
904 Collection directory may sometimes be shared on multiple
906 machines which may use different modules setup. For instance
907 modules users may access with the same HOME directory multiple
908 systems using different OS versions. When it happens a collec‐
909 tion made on machine 1 may be erroneous on machine 2.
910 When a target is set, only the collections made for that target
912 are available to the restore, savelist, saveshow and saverm
913 sub-commands. Saving a collection registers the target footprint
914 by suffixing the collection filename with .$MODULES_COLLEC‐
915 TION_TARGET. The collection target is not involved when collec‐
916 tion is specified as file path on the saveshow, restore and save
917 sub-commands.
918 For example, the MODULES_COLLECTION_TARGET variable may be set
920 with results from commands like lsb_release, hostname, dnsdo‐
921 mainname, etc.
922 MODULES_COLOR
924 Defines if output should be colored or not. Accepted values are
925 never, auto and always.
926 When color mode is set to auto, output is colored only if the
928 standard error output channel is attached to a terminal.
929 Colored output enablement is defined in the following order of
931 preference: --color command line switch, then MODULES_COLOR
932 environment variable, then NO_COLOR, CLICOLOR and CLICOLOR_FORCE
933 environment variables, then the default set in modulecmd.tcl
934 script configuration. Which means MODULES_COLOR overrides
935 default configuration and the NO_COLOR and CLICOLOR/CLI‐
936 COLOR_FORCE variables. --color command line switch overrides
937 every other ways to enable or disable this mode.
938 NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables are
940 also honored to define color mode. The never mode is set if
941 NO_COLOR is defined (regardless of its value) or if CLICOLOR
942 equals to 0. If CLICOLOR is set to another value, it corresponds
943 to the auto mode. The always mode is set if CLICOLOR_FORCE is
944 set to a value different than 0. NO_COLOR variable prevails
945 over CLICOLOR and CLICOLOR_FORCE. Color mode set with these
946 three variables is superseded by mode set with MODULES_COLOR
947 environment variable.
948 MODULES_COLORS
950 Specifies the colors and other attributes used to highlight var‐
951 ious parts of the output. Its value is a colon-separated list of
952 output items associated to a Select Graphic Rendition (SGR)
953 code. It follows the same syntax than LS_COLORS.
954 Output items are designated by keys. Items able to be colorized
956 are: highlighted element (hi), debug information (db), tag sepa‐
957 rator (se); Error (er), warning (wa), module error (me) and info
958 (in) message prefixes; Modulepath (mp), directory (di), module
959 alias (al), module symbolic version (sy), module default version
960 (de) and modulefile command (cm).
961 See the Select Graphic Rendition (SGR) section in the documenta‐
963 tion of the text terminal that is used for permitted values and
964 their meaning as character attributes. These substring values
965 are integers in decimal representation and can be concatenated
966 with semicolons. Modules takes care of assembling the result
967 into a complete SGR sequence (\33[...m). Common values to con‐
968 catenate include 1 for bold, 4 for underline, 30 to 37 for fore‐
969 ground colors and 90 to 97 for 16-color mode foreground colors.
970 See also
971 https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
972 for a complete SGR code reference.
973 No graphical rendition will be applied to an output item that
975 could normaly be colored but which is not defined in the color
976 set. Thus if MODULES_COLORS is defined empty, no output will be
977 colored at all.
978 The color set is defined for Modules in the following order of
980 preference: MODULES_COLORS environment variable, then the
981 default set in modulecmd.tcl script configuration. Which means
982 MODULES_COLORS overrides default configuration.
983 MODULES_EXTENDED_DEFAULT
985 If set to 1, a specified module version is matched against
986 starting portion of existing module versions, where portion is a
987 substring separated from the rest of the version string by a .
988 character. For example specified modules mod/1 and mod/1.2 will
989 match existing modulefile mod/1.2.3.
990 In case multiple modulefiles match the specified module version
992 and a single module has to be selected, the explicitly set
993 default version is returned if it is part of matching module‐
994 files. Otherwise the implicit default among matching modulefiles
995 is returned if defined (see MODULES_IMPLICIT_DEFAULT section)
996 This environment variable supersedes the value of the configura‐
998 tion option extended_default set in modulecmd.tcl script.
999 MODULES_ICASE
1001 When module specification are passed as argument to module
1002 sub-commands or modulefile Tcl commands, defines the case sensi‐
1003 tiveness to apply to match them. When MODULES_ICASE is set to
1004 never, a case sensitive match is applied in any cases. When set
1005 to search, a case insensitive match is applied to the avail,
1006 whatis and paths sub-commands. When set to always, a case insen‐
1007 sitive match is also applied to the other module sub-commands
1008 and modulefile Tcl commands for the module specification they
1009 receive as argument.
1010 Case sensitiveness behavior is defined in the following order of
1012 preference: --icase command line switch, which corresponds to
1013 the always mode, then MODULES_ICASE environment variable, then
1014 the default set in modulecmd.tcl script configuration. Which
1015 means MODULES_ICASE overrides default configuration and --icase
1016 command line switch overrides every other ways to set case sen‐
1017 sitiveness behavior.
1018 MODULES_IMPLICIT_DEFAULT
1020 Defines (if set to 1) or not (if set to 0) an implicit default
1021 version for modules without a default version explicitly defined
1022 (see Locating Modulefiles section in the modulefile(4) man
1023 page).
1024 Without either an explicit or implicit default version defined a
1026 module must be fully qualified (version should be specified in
1027 addition to its name) to get:
1028 · targeted by module load, switch, display, help, test and path
1030 sub-commands.
1031 · restored from a collection, unless already loaded in collec‐
1033 tion-specified order.
1034 · automatically loaded by automated module handling mechanisms
1036 (see MODULES_AUTO_HANDLING section) when declared as module
1037 requirement, with prereq or module load modulefile commands.
1038 An error is returned in the above situations if either no
1040 explicit or implicit default version is defined.
1041 This environment variable supersedes the value of the configura‐
1043 tion option implicit_default set in modulecmd.tcl script. This
1044 environment variable is ignored if implicit_default has been
1045 declared locked in locked_configs configuration option.
1046 MODULES_LMALTNAME
1048 A colon separated list of the alternative names set through mod‐
1049 ule-version and module-alias statements corresponding to all
1050 loaded modulefiles. Each element in this list starts by the name
1051 of the loaded modulefile followed by all alternative names
1052 resolving to it. The loaded modulefile and its alternative names
1053 are separated by the ampersand character.
1054 This environment variable is intended for module command inter‐
1056 nal use to get knowledge of the alternative names matching
1057 loaded modulefiles in order to keep environment consistent when
1058 conflicts or pre-requirements are set over these alternative
1059 designations. It also helps to find a match after modulefiles
1060 being loaded when unload, is-loaded or info-loaded actions are
1061 run over these names.
1062 MODULES_LMCONFLICT
1064 A colon separated list of the conflict statements defined by all
1065 loaded modulefiles. Each element in this list starts by the name
1066 of the loaded modulefile declaring the conflict followed by the
1067 name of all modulefiles it declares a conflict with. These
1068 loaded modulefiles and conflicting modulefile names are sepa‐
1069 rated by the ampersand character.
1070 This environment variable is intended for module command inter‐
1072 nal use to get knowledge of the conflicts declared by the loaded
1073 modulefiles in order to keep environment consistent when a con‐
1074 flicting module is asked for load afterward.
1075 MODULES_LMNOTUASKED
1077 A colon separated list of all loaded modulefiles that were not
1078 explicitly asked for load from the command-line.
1079 This environment variable is intended for module command inter‐
1081 nal use to distinguish the modulefiles that have been loaded
1082 automatically from modulefiles that have been asked by users.
1083 MODULES_LMPREREQ
1085 A colon separated list of the prereq statements defined by all
1086 loaded modulefiles. Each element in this list starts by the name
1087 of the loaded modulefile declaring the pre-requirement followed
1088 by the name of all modulefiles it declares a prereq with. These
1089 loaded modulefiles and pre-required modulefile names are sepa‐
1090 rated by the ampersand character. When a prereq statement is
1091 composed of multiple modulefiles, these modulefile names are
1092 separated by the pipe character.
1093 This environment variable is intended for module command inter‐
1095 nal use to get knowledge of the pre-requirement declared by the
1096 loaded modulefiles in order to keep environment consistent when
1097 a pre-required module is asked for unload afterward.
1098 MODULES_ML
1100 If set to 1, define ml command when initializing Modules (see
1101 Package Initialization section). If set to 0, ml command is not
1102 defined.
1103 ml command enablement is defined in the following order of pref‐
1105 erence: MODULES_ML environment variable then the default set in
1106 modulecmd.tcl script configuration. Which means MODULES_ML over‐
1107 rides default configuration.
1108 MODULES_PAGER
1110 Text viewer for use to paginate message output if error output
1111 stream is attached to a terminal. The value of this variable is
1112 composed of a pager command name or path eventually followed by
1113 command-line options.
1114 Paging command and options are defined for Modules in the fol‐
1116 lowing order of preference: MODULES_PAGER environment variable,
1117 then the default set in modulecmd.tcl script configuration.
1118 Which means MODULES_PAGER overrides default configuration.
1119 If MODULES_PAGER variable is set to an empty string or to the
1121 value cat, pager will not be launched.
1122 MODULES_RUN_QUARANTINE
1124 A space separated list of environment variable names that should
1125 be passed indirectly to modulecmd.tcl to protect its run-time
1126 environment from side-effect coming from their current defini‐
1127 tion.
1128 Each variable found in MODULES_RUN_QUARANTINE will have its
1130 value emptied or set to the value of the corresponding
1131 MODULES_RUNENV_<VAR> variable when defining modulecmd.tcl
1132 run-time environment.
1133 Original values of these environment variables set in quarantine
1135 are passed to modulecmd.tcl via <VAR>_modquar variables.
1136 MODULES_RUNENV_<VAR>
1138 Value to set to environment variable <VAR> for modulecmd.tcl
1139 run-time execution if <VAR> is referred in
1140 MODULES_RUN_QUARANTINE.
1141 MODULES_SEARCH_MATCH
1143 When searching for modules with avail sub-command, defines the
1144 way query string should match against available module names.
1145 With starts_with value, returned modules are those whose name
1146 begins by search query string. When set to contains, any modules
1147 whose fully qualified name contains search query string are
1148 returned.
1149 Module search match style is defined in the following order of
1151 preference: --starts-with and --contains command line switches,
1152 then MODULES_SEARCH_MATCH environment variable, then the default
1153 set in modulecmd.tcl script configuration. Which means
1154 MODULES_SEARCH_MATCH overrides default configuration and
1155 --starts-with/--contains command line switches override every
1156 other ways to set search match style.
1157 MODULES_SET_SHELL_STARTUP
1159 If set to 1, defines when module command initializes the shell
1160 startup file to ensure that the module command is still defined
1161 in sub-shells. Setting shell startup file means defining the ENV
1162 and BASH_ENV environment variable to the Modules bourne shell
1163 initialization script. If set to 0, shell startup file is not
1164 defined.
1165 MODULES_SILENT_SHELL_DEBUG
1167 If set to 1, disable any xtrace or verbose debugging property
1168 set on current shell session for the duration of either the mod‐
1169 ule command or the module shell initialization script. Only
1170 applies to Bourne Shell (sh) and its derivatives.
1171 MODULES_SITECONFIG
1173 Location of a site-specific configuration script to source into
1174 modulecmd.tcl. See also Modulecmd startup section.
1175 This environment variable is ignored if extra_siteconfig has
1177 been declared locked in locked_configs configuration option.
1178 MODULES_TERM_BACKGROUND
1180 Inform Modules of the terminal background color to determine if
1181 the color set for dark background or the color set for light
1182 background should be used to color output in case no specific
1183 color set is defined with the MODULES_COLORS variable. Accepted
1184 values are dark and light.
1185 MODULES_UNLOAD_MATCH_ORDER
1187 When a module unload request matches multiple loaded modules,
1188 unload firstly loaded module or lastly loaded module. Accepted
1189 values are returnfirst and returnlast.
1190 MODULES_USE_COMPAT_VERSION
1192 If set to 1 prior to Modules package initialization, enable Mod‐
1193 ules compatibility version (3.2 release branch) rather main ver‐
1194 sion at initialization scripts running time. Modules package
1195 compatibility version should be installed along with main ver‐
1196 sion for this environment variable to have any effect.
1197 MODULES_VERBOSITY
1199 Defines the verbosity level of the module command. Available
1200 verbosity levels from the least to the most verbose are:
1201 · silent: turn off error, warning and informational messages but
1203 does not affect module command output result.
1204 · concise: enable error and warning messages but disable infor‐
1206 mational messages.
1207 · normal: turn on informational messages, like a report of the
1209 additional module evaluations triggered by loading or unload‐
1210 ing modules, aborted evaluation issues or a report of each
1211 module evaluation occurring during a restore or source
1212 sub-commands.
1213 · verbose: add additional informational messages, like a system‐
1215 atic report of the loading or unloading module evaluations.
1216 · debug: print debugging messages about module command execu‐
1218 tion.
1219 Module command verbosity is defined in the following order of
1221 preference: --silent, --verbose and --debug command line
1222 switches, then MODULES_VERBOSITY environment variable, then the
1223 default set in modulecmd.tcl script configuration. Which means
1224 MODULES_VERBOSITY overrides default configuration and --silent/‐
1225 --verbose/--debug command line switches overrides every other
1226 ways to set verbosity level.
1227 MODULES_WA_277
1229 If set to 1 prior to Modules package initialization, enables
1230 workaround for Tcsh history issue (see
1231 https://github.com/cea-hpc/modules/issues/277). This issue
1232 leads to erroneous history entries under Tcsh shell. When work‐
1233 around is enabled, an alternative module alias is defined which
1234 fixes the history mechanism issue. However the alternative defi‐
1235 nition of the module alias weakens shell evaluation of the code
1236 produced by modulefiles. Characters with a special meaning for
1237 Tcsh shell (like { and }) may not be used anymore in shell alias
1238 definition otherwise the evaluation of the code produced by mod‐
1239 ulefiles will return a syntax error.
1240 MODULESHOME
1242 The location of the master Modules package file directory con‐
1243 taining module command initialization scripts, the executable
1244 program modulecmd.tcl, and a directory containing a collection
1245 of master modulefiles.
1246 <VAR>_modquar
1248 Value of environment variable <VAR> passed to modulecmd.tcl in
1249 order to restore <VAR> to this value once started.
1250 <VAR>_modshare
1252 Reference counter variable for path-like variable <VAR>. A colon
1253 separated list containing pairs of elements. A pair is formed by
1254 a path element followed its usage counter which represents the
1255 number of times this path has been enabled in variable <VAR>. A
1256 colon separates the two parts of the pair.
1257
1259 /usr/share/Modules
1260 The MODULESHOME directory.
1261 /etc/environment-modules/siteconfig.tcl
1263 The site-specific configuration script of modulecmd.tcl. An addi‐
1264 tional configuration script could be defined using the
1265 MODULES_SITECONFIG environment variable.
1266 /etc/environment-modules/rc
1268 The system-wide modules rc file. The location of this file can be
1269 changed using the MODULERCFILE environment variable as described
1270 above.
1271 $HOME/.modulerc
1273 The user specific modules rc file.
1274 $HOME/.module
1276 The user specific collection directory.
1277 /usr/share/Modules/modulefiles
1279 The directory for system-wide modulefiles. The location of the
1280 directory can be changed using the MODULEPATH environment variable
1281 as described above.
1282 /usr/share/Modules/libexec/modulecmd.tcl
1284 The modulefile interpreter that gets executed upon each invocation
1285 of module.
1286 /usr/share/Modules/init/<shell>
1288 The Modules package initialization file sourced into the user's
1289 environment.
1290
1292 ml(1), modulefile(4)
1293
1295 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1296 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2020 Xavier Delaruelle
12974.5.3 2020-08-31 MODULE(1)