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 Examples of initialization
57 C Shell initialization (and derivatives):
58 source /usr/share/Modules/init/csh
60 module load modulefile modulefile ...
61 Bourne Shell (sh) (and derivatives):
63 . /usr/share/Modules/init/sh
65 module load modulefile modulefile ...
66 Perl:
68 require "/usr/share/Modules/init/perl.pm";
70 &module('load', 'modulefile', 'modulefile', '...');
71 Python:
73 import os
75 exec(open('/usr/share/Modules/init/python.py').read())
76 module('load', 'modulefile', 'modulefile', '...')
77 Bourne Shell (sh) (and derivatives) with autoinit sub-command:
79 eval "`/usr/share/Modules/libexec/modulecmd.tcl sh autoinit`"
81 Modulecmd startup
83 Upon invocation modulecmd.tcl sources a site-specific configuration
84 script if it exists. The location for this script is /etc/environment-
85 modules/siteconfig.tcl. An additional siteconfig script may be speci‐
86 fied with the $MODULES_SITECONFIG environment variable, if allowed by
87 modulecmd.tcl configuration, and will be loaded if it exists after
88 /etc/environment-modules/siteconfig.tcl. Siteconfig is a Tcl script
89 that enables to supersede any global variable or procedure definition
90 of modulecmd.tcl.
91 Afterward, modulecmd.tcl sources rc files which contain global, user
93 and modulefile specific setups. These files are interpreted as module‐
94 files. See modulefile(4) for detailed information.
95 Upon invocation of modulecmd.tcl module run-command files are sourced
97 in the following order:
98 1. Global RC file as specified by $MODULERCFILE or /etc/environment-
100 modules/rc. If $MODULERCFILE points to a directory, the modulerc
101 file in this directory is used as global RC file.
102 2. User specific module RC file $HOME/.modulerc
104 3. All .modulerc and .version files found during modulefile seeking.
106 Command line switches
108 The module command accepts command line switches as its first parame‐
109 ter. These may be used to control output format of all information
110 displayed and the module behavior in case of locating and interpreting
111 modulefiles.
112 All switches may be entered either in short or long notation. The fol‐
114 lowing switches are accepted:
115 --help, -h
117 Give some helpful usage information, and terminates the command.
118 --version, -V
120 Lists the current version of the module command. The command then
121 terminates without further processing.
122 --debug, -D
124 Debug mode. Causes module to print debugging messages about its
125 progress.
126 --verbose, -v
128 Enable verbose messages during module command execution.
129 --silent, -s
131 Turn off error, warning and informational messages. module command
132 output result is not affected by silent mode.
133 --paginate
135 Pipe all message output into less (or if set, $MODULES_PAGER) if
136 error output stream is a terminal. See also MODULES_PAGER section.
137 --no-pager
139 Do not pipe message output into a pager.
140 --color[=WHEN]
142 Colorize the output. WHEN defaults to always or can be never or
143 auto. See also MODULES_COLOR section.
144 --auto
146 On load, unload and switch sub-commands, enable automated module
147 handling mode. See also MODULES_AUTO_HANDLING section.
148 --no-auto
150 On load, unload and switch sub-commands, disable automated module
151 handling mode. See also MODULES_AUTO_HANDLING section.
152 --force, -f
154 On load, unload and switch sub-commands, by-pass any unsatisfied
155 modulefile constraint corresponding to the declared prereq and con‐
156 flict. Which means for instance that a modulefile will be loaded
157 even if it comes in conflict with another loaded modulefile or that
158 a modulefile will be unloaded even if it is required as a prereq by
159 another modulefile.
160 On clear sub-command, skip the confirmation dialog and proceed.
162 --terse, -t
164 Display avail, list and savelist output in short format.
165 --long, -l
167 Display avail, list and savelist output in long format.
168 --default, -d
170 On avail sub-command, display only the default version of each mod‐
171 ule name. Default version is the explicitly set default version or
172 also the implicit default version if config option implicit_default
173 is enabled (see Locating Modulefiles section in the modulefile(4)
174 man page for further details on implicit default version).
175 --latest, -L
177 On avail sub-command, display only the highest numerically sorted
178 version of each module name (see Locating Modulefiles section in the
179 modulefile(4) man page).
180 --starts-with, -S
182 On avail sub-command, return modules whose name starts with search
183 query string.
184 --contains, -C
186 On avail sub-command, return modules whose fully qualified name con‐
187 tains search query string.
188 --indepth
190 On avail sub-command, include in search results the matching module‐
191 files and directories and recursively the modulefiles and directo‐
192 ries contained in these matching directories.
193 --no-indepth
195 On avail sub-command, limit search results to the matching module‐
196 files and directories found at the depth level expressed by the
197 search query. Thus modulefiles contained in directories part of the
198 result are excluded.
199 --icase, -i
201 Match module specification arguments in a case insensitive manner.
202 Module Sub-Commands
204 help [modulefile...]
205 Print the usage of each sub-command. If an argument is given, print
206 the Module-specific help information for the modulefile.
207 The parameter modulefile may also be a symbolic modulefile name or a
209 modulefile alias. It may also leverage a specific syntax to finely
210 select module version (see Advanced module version specifiers sec‐
211 tion below).
212 add modulefile...
214 See load.
215 load [--auto|--no-auto] [-f] modulefile...
217 Load modulefile into the shell environment.
218 The parameter modulefile may also be a symbolic modulefile name or a
220 modulefile alias. It may also leverage a specific syntax to finely
221 select module version (see Advanced module version specifiers sec‐
222 tion below).
223 rm modulefile...
225 See unload.
226 unload [--auto|--no-auto] [-f] modulefile...
228 Remove modulefile from the shell environment.
229 The parameter modulefile may also be a symbolic modulefile name or a
231 modulefile alias. It may also leverage a specific syntax to finely
232 select module version (see Advanced module version specifiers sec‐
233 tion below).
234 swap [modulefile1] modulefile2
236 See switch.
237 switch [--auto|--no-auto] [-f] [modulefile1] modulefile2
239 Switch loaded modulefile1 with modulefile2. If modulefile1 is not
240 specified, then it is assumed to be the currently loaded module with
241 the same root name as modulefile2.
242 The parameter modulefile may also be a symbolic modulefile name or a
244 modulefile alias. It may also leverage a specific syntax to finely
245 select module version (see Advanced module version specifiers sec‐
246 tion below).
247 show modulefile...
249 See display.
250 display modulefile...
252 Display information about one or more modulefiles. The display
253 sub-command will list the full path of the modulefile and the envi‐
254 ronment changes the modulefile will make if loaded. (Note: It will
255 not display any environment changes found within conditional state‐
256 ments.)
257 The parameter modulefile may also be a symbolic modulefile name or a
259 modulefile alias. It may also leverage a specific syntax to finely
260 select module version (see Advanced module version specifiers sec‐
261 tion below).
262 list [-t|-l]
264 List loaded modules.
265 avail [-d|-L] [-t|-l] [-S|-C] [--indepth|--no-indepth] [path...]
267 List all available modulefiles in the current MODULEPATH. All direc‐
268 tories in the MODULEPATH are recursively searched for files contain‐
269 ing the modulefile magic cookie. If an argument is given, then each
270 directory in the MODULEPATH is searched for modulefiles whose path‐
271 name, symbolic version-name or alias match the argument. Argument
272 may contain wildcard characters. Multiple versions of an application
273 can be supported by creating a subdirectory for the application con‐
274 taining modulefiles for each version.
275 Symbolic version-names and aliases found in the search are displayed
277 in the result of this sub-command. Symbolic version-names are dis‐
278 played next to the modulefile they are assigned to within parenthe‐
279 sis. Aliases are listed in the MODULEPATH section where they have
280 been defined. To distinguish aliases from modulefiles a @ symbol is
281 added within parenthesis next to their name. Aliases defined through
282 a global or user specific module RC file are listed under the
283 global/user modulerc section.
284 When colored output is enabled and a specific graphical rendition is
286 defined for module default version, the default symbol is omitted
287 and instead the defined graphical rendition is applied to the rela‐
288 tive modulefile. When colored output is enabled and a specific
289 graphical rendition is defined for module alias, the @ symbol is
290 omitted. The defined graphical rendition applies to the module alias
291 name. See MODULES_COLOR and MODULES_COLORS sections for details on
292 colored output.
293 The parameter path may also refer to a symbolic modulefile name or a
295 modulefile alias. It may also leverage a specific syntax to finely
296 select module version (see Advanced module version specifiers sec‐
297 tion below).
298 aliases
300 List all available symbolic version-names and aliases in the current
301 MODULEPATH. All directories in the MODULEPATH are recursively
302 searched in the same manner than for the avail sub-command. Only the
303 symbolic version-names and aliases found in the search are dis‐
304 played.
305 use [-a|--append] directory...
307 Prepend one or more directories to the MODULEPATH environment vari‐
308 able. The --append flag will append the directory to MODULEPATH.
309 Reference counter environment variable MODULEPATH_modshare is also
311 set to increase the number of times directory has been added to MOD‐
312 ULEPATH.
313 unuse directory...
315 Remove one or more directories from the MODULEPATH environment vari‐
316 able if reference counter of these directories is equal to 1 or
317 unknown.
318 Reference counter of directory in MODULEPATH denotes the number of
320 times directory has been enabled. When attempting to remove direc‐
321 tory from MODULEPATH, reference counter variable MODULEPATH_modshare
322 is checked and directory is removed only if its relative counter is
323 equal to 1 or not defined. Elsewhere directory is kept and reference
324 counter is decreased by 1.
325 refresh
327 See reload.
328 reload
330 Unload then load all loaded modulefiles.
331 No unload then load is performed and an error is returned if the
333 loaded modulefiles have unsatisfied constraint corresponding to the
334 prereq and conflict they declare.
335 purge
337 Unload all loaded modulefiles.
338 clear [-f]
340 Force the Modules package to believe that no modules are currently
341 loaded. A confirmation is requested if command-line switch -f (or
342 --force) is not passed. Typed confirmation should equal to yes or y
343 in order to proceed.
344 source scriptfile...
346 Execute scriptfile into the shell environment. scriptfile must be
347 written with modulefile syntax and specified with a fully qualified
348 path. Once executed scriptfile is not marked loaded in shell envi‐
349 ronment which differ from load sub-command.
350 whatis [modulefile...]
352 Display the information set up by the module-whatis commands inside
353 the specified modulefiles. These specified modulefiles may be
354 expressed using wildcard characters. If no modulefile is specified,
355 all module-whatis lines will be shown.
356 The parameter modulefile may also be a symbolic modulefile name or a
358 modulefile alias. It may also leverage a specific syntax to finely
359 select module version (see Advanced module version specifiers sec‐
360 tion below).
361 apropos string
363 See search.
364 keyword string
366 See search.
367 search string
369 Seeks through the module-whatis informations of all modulefiles for
370 the specified string. All module-whatis informations matching the
371 string in a case insensitive manner will be displayed. string may
372 contain wildcard characters.
373 test modulefile...
375 Execute and display results of the Module-specific tests for the
376 modulefile.
377 The parameter modulefile may also be a symbolic modulefile name or a
379 modulefile alias. It may also leverage a specific syntax to finely
380 select module version (see Advanced module version specifiers sec‐
381 tion below).
382 save [collection]
384 Record the currently set MODULEPATH directory list and the currently
385 loaded modulefiles in a collection file under the user's collection
386 directory $HOME/.module. If collection name is not specified, then
387 it is assumed to be the default collection. If collection is a fully
388 qualified path, it is saved at this location rather than under the
389 user's collection directory.
390 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
392 value of this variable will be appended to the collection file name.
393 By default, if loaded modulefile corresponds to the explicitly
395 defined default module version, the bare module name is recorded. If
396 config option implicit_default is enabled, the bare module name is
397 also recorded for the implicit default module version. If MOD‐
398 ULES_COLLECTION_PIN_VERSION is set to 1, module version is always
399 recorded even if it is the default version.
400 No collection is recorded and an error is returned if the loaded
402 modulefiles have unsatisfied constraint corresponding to the prereq
403 and conflict they declare.
404 restore [collection]
406 Restore the environment state as defined in collection. If collec‐
407 tion name is not specified, then it is assumed to be the default
408 collection. If collection is a fully qualified path, it is restored
409 from this location rather than from a file under the user's collec‐
410 tion directory. If MODULES_COLLECTION_TARGET is set, a suffix equiv‐
411 alent to the value of this variable is appended to the collection
412 file name to restore.
413 When restoring a collection, the currently set MODULEPATH directory
415 list and the currently loaded modulefiles are unused and unloaded
416 then used and loaded to exactly match the MODULEPATH and loaded mod‐
417 ulefiles lists saved in this collection file. The order of the paths
418 and modulefiles set in collection is preserved when restoring. It
419 means that currently loaded modules are unloaded to get the same
420 LOADEDMODULES root than collection and currently used module paths
421 are unused to get the same MODULEPATH root. Then missing module
422 paths are used and missing modulefiles are loaded.
423 If a module, without a default version explicitly defined, is
425 recorded in a collection by its bare name: loading this module when
426 restoring the collection will fail if config option implicit_default
427 is disabled.
428 saverm [collection]
430 Delete the collection file under the user's collection directory. If
431 collection name is not specified, then it is assumed to be the
432 default collection. If MODULES_COLLECTION_TARGET is set, a suffix
433 equivalent to the value of this variable will be appended to the
434 collection file name.
435 saveshow [collection]
437 Display the content of collection. If collection name is not speci‐
438 fied, then it is assumed to be the default collection. If collection
439 is a fully qualified path, this location is displayed rather than a
440 collection file under the user's collection directory. If MOD‐
441 ULES_COLLECTION_TARGET is set, a suffix equivalent to the value of
442 this variable will be appended to the collection file name.
443 savelist [-t|-l]
445 List collections that are currently saved under the user's collec‐
446 tion directory. If MODULES_COLLECTION_TARGET is set, only collec‐
447 tions matching the target suffix will be displayed.
448 initadd modulefile...
450 Add modulefile to the shell's initialization file in the user's home
451 directory. The startup files checked (in order) are:
452 C Shell
454 .modules, .cshrc, .csh_variables and .login
455 TENEX C Shell
457 .modules, .tcshrc, .cshrc, .csh_variables and .login
458 Bourne and Korn Shells
460 .modules, .profile
461 GNU Bourne Again Shell
463 .modules, .bash_profile, .bash_login, .profile and .bashrc
464 Z Shell
466 .modules, .zshrc, .zshenv and .zlogin
467 Friendly Interactive Shell
469 .modules, .config/fish/config.fish
470 If a module load line is found in any of these files, the module‐
472 files are appended to any existing list of modulefiles. The module
473 load line must be located in at least one of the files listed above
474 for any of the init sub-commands to work properly. If the module
475 load line is found in multiple shell initialization files, all of
476 the lines are changed.
477 initprepend modulefile...
479 Does the same as initadd but prepends the given modules to the
480 beginning of the list.
481 initrm modulefile...
483 Remove modulefile from the shell's initialization files.
484 initswitch modulefile1 modulefile2
486 Switch modulefile1 with modulefile2 in the shell's initialization
487 files.
488 initlist
490 List all of the modulefiles loaded from the shell's initialization
491 file.
492 initclear
494 Clear all of the modulefiles from the shell's initialization files.
495 path modulefile
497 Print path to modulefile.
498 The parameter modulefile may also be a symbolic modulefile name or a
500 modulefile alias. It may also leverage a specific syntax to finely
501 select module version (see Advanced module version specifiers sec‐
502 tion below).
503 paths modulefile
505 Print path of available modulefiles matching argument.
506 The parameter modulefile may also be a symbolic modulefile name or a
508 modulefile alias. It may also leverage a specific syntax to finely
509 select module version (see Advanced module version specifiers sec‐
510 tion below).
511 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
513 Append value to environment variable. The variable is a colon, or
514 delimiter, separated list. See append-path in the modulefile(4) man
515 page for further explanation.
516 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
518 value...
519 Prepend value to environment variable. The variable is a colon, or
520 delimiter, separated list. See prepend-path in the modulefile(4) man
521 page for further explanation.
522 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
524 Remove value from the colon, or delimiter, separated list in envi‐
525 ronment variable. See remove-path in the modulefile(4) man page for
526 further explanation.
527 is-loaded [modulefile...]
529 Returns a true value if any of the listed modulefiles has been
530 loaded or if any modulefile is loaded in case no argument is pro‐
531 vided. Returns a false value elsewhere. See is-loaded in the module‐
532 file(4) man page for further explanation.
533 The parameter modulefile may also be a symbolic modulefile name or a
535 modulefile alias. It may also leverage a specific syntax to finely
536 select module version (see Advanced module version specifiers sec‐
537 tion below).
538 is-saved [collection...]
540 Returns a true value if any of the listed collections exists or if
541 any collection exists in case no argument is provided. Returns a
542 false value elsewhere. See is-saved in the modulefile(4) man page
543 for further explanation.
544 is-used [directory...]
546 Returns a true value if any of the listed directories has been
547 enabled in MODULEPATH or if any directory is enabled in case no
548 argument is provided. Returns a false value elsewhere. See is-used
549 in the modulefile(4) man page for further explanation.
550 is-avail modulefile...
552 Returns a true value if any of the listed modulefiles exists in
553 enabled MODULEPATH. Returns a false value elsewhere. See is-avail in
554 the modulefile(4) man page for further explanation.
555 The parameter modulefile may also be a symbolic modulefile name or a
557 modulefile alias. It may also leverage a specific syntax to finely
558 select module version (see Advanced module version specifiers sec‐
559 tion below).
560 info-loaded modulefile
562 Returns the names of currently loaded modules matching passed mod‐
563 ulefile. Returns an empty string if passed modulefile does not
564 match any loaded modules. See module-info loaded in the module‐
565 file(4) man page for further explanation.
566 config [--dump-state|name [value]|--reset name]
568 Gets or sets modulecmd.tcl options. Reports the currently set value
569 of passed option name or all existing options if no name passed. If
570 a name and a value are provided, the value of option name is set to
571 value. If command-line switch --reset is passed in addition to a
572 name, overridden overridden value for option name is cleared.
573 When a reported option value differs from default value a mention is
575 added to indicate whether the overridden value is coming from a com‐
576 mand-line switch (cmd-line) or from an environment variable
577 (env-var). When a reported option value is locked and cannot be
578 altered a (locked) mention is added.
579 If no value is currently set for an option name, the mention <undef>
581 is reported.
582 When command-line switch --dump-state is passed, current mod‐
584 ulecmd.tcl state and Modules-related environment variables are
585 reported in addition to currently set modulecmd.tcl options.
586 Existing option names are:
588 · advanced_version_spec: advanced module version specification to
590 finely select modulefiles (defines environment variable MOD‐
591 ULES_ADVANCED_VERSION_SPEC when set
592 · auto_handling: automated module handling mode (defines MOD‐
594 ULES_AUTO_HANDLING)
595 · avail_indepth: avail sub-command in depth search mode (defines
597 MODULES_AVAIL_INDEPTH)
598 · avail_report_dir_sym: display symbolic versions targeting directo‐
600 ries on avail sub-command
601 · avail_report_mfile_sym: display symbolic versions targeting mod‐
603 ulefiles on avail sub-command
604 · collection_pin_version: register exact modulefile version in col‐
606 lection (defines MODULES_COLLECTION_PIN_VERSION)
607 · collection_target: collection target which is valid for current
609 system (defines MODULES_COLLECTION_TARGET)
610 · color: colored output mode (defines MODULES_COLOR)
612 · colors: chosen colors to highlight output items (defines MOD‐
614 ULES_COLORS)
615 · contact: modulefile contact address (defines MODULECONTACT)
617 · extended_default: allow partial module version specification
619 (defines MODULES_EXTENDED_DEFAULT)
620 · extra_siteconfig: additional site-specific configuration script
622 location (defines MODULES_SITECONFIG)
623 · home: location of Modules package master directory (defines MOD‐
625 ULESHOME)
626 · icase: enable case insensitive match (defines MODULES_ICASE)
628 · ignored_dirs: directories ignored when looking for modulefiles
630 · implicit_default: set an implicit default version for modules
632 (defines MODULES_IMPLICIT_DEFAULT)
633 · locked_configs: configuration options that cannot be superseded
635 · pager: text viewer to paginate message output (defines MOD‐
637 ULES_PAGER)
638 · rcfile: global run-command file location (defines MODULERCFILE)
640 · run_quarantine: environment variables to indirectly pass to mod‐
642 ulecmd.tcl (defines MODULES_RUN_QUARANTINE)
643 · silent_shell_debug: disablement of shell debugging property for
645 the module command (defines MODULES_SILENT_SHELL_DEBUG)
646 · search_match: module search match style (defines MOD‐
648 ULES_SEARCH_MATCH)
649 · set_shell_startup: ensure module command definition by setting
651 shell startup file (defines MODULES_SET_SHELL_STARTUP)
652 · siteconfig: primary site-specific configuration script location
654 · tcl_ext_lib: Modules Tcl extension library location
656 · term_background: terminal background color kind (defines MOD‐
658 ULES_TERM_BACKGROUND)
659 · unload_match_order: unload firstly loaded or lastly loaded module
661 matching request (defines MODULES_UNLOAD_MATCH_ORDER)
662 · verbosity: module command verbosity level (defines MODULES_VER‐
664 BOSITY)
665 · wa_277: workaround for Tcsh history issue (defines MODULES_WA_277)
667 The options avail_report_dir_sym, avail_report_mfile_sym, ignored_dirs,
669 locked_configs, siteconfig and tcl_ext_lib cannot be altered. Moreover
670 all options referred in locked_configs value are locked thus they can‐
671 not be altered.
672 Modulefiles
674 modulefiles are written in the Tool Command Language (Tcl) and are
675 interpreted by modulecmd.tcl. modulefiles can use conditional state‐
676 ments. Thus the effect a modulefile will have on the environment may
677 change depending upon the current state of the environment.
678 Environment variables are unset when unloading a modulefile. Thus, it
680 is possible to load a modulefile and then unload it without having the
681 environment variables return to their prior state.
682 Advanced module version specifiers
684 When the advanced module version specifiers mechanism is enabled (see
685 MODULES_ADVANCED_VERSION_SPEC), the specification of modulefile passed
686 on Modules sub-commands changes. After the module name a version con‐
687 straint prefixed by the @ character may be added. It could be directly
688 appended to the module name or separated from it with a space charac‐
689 ter.
690 Constraints can be expressed to refine the selection of module version
692 to:
693 · a single version with the @version syntax, for instance foo@1.2.3
695 syntax will select module foo/1.2.3
696 · a list of versions with the @version1,version2,... syntax, for
698 instance foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10
699 · a range of versions with the @version1:, @:version2 and @ver‐
701 sion1:version2 syntaxes, for instance foo@1.2: will select all ver‐
702 sions of module foo greater than or equal to 1.2, foo@:1.3 will
703 select all versions less than or equal to 1.3 and foo@1.2:1.3 matches
704 all versions between 1.2 and 1.3 including 1.2 and 1.3 versions
705 Advanced specification of single version or list of versions may bene‐
707 fit from the activation of the extended default mechanism (see MOD‐
708 ULES_EXTENDED_DEFAULT) to use an abbreviated notation like @1 to refer
709 to more precise version numbers like 1.2.3. Range of versions on its
710 side natively handles abbreviated versions.
711 In order to be specified in a range of versions or compared to a range
713 of versions, the version major element should corresponds to a number.
714 For instance 10a, 1.2.3, 1.foo are versions valid for range comparison
715 whereas default or foo.2 versions are invalid for range comparison.
716 Collections
718 Collections describe a sequence of module use then module load commands
719 that are interpreted by modulecmd.tcl to set the user environment as
720 described by this sequence. When a collection is activated, with the
721 restore sub-command, module paths and loaded modules are unused or
722 unloaded if they are not part or if they are not ordered the same way
723 as in the collection.
724 Collections are generated by the save sub-command that dumps the cur‐
726 rent user environment state in terms of module paths and loaded mod‐
727 ules. By default collections are saved under the $HOME/.module direc‐
728 tory.
729 Collections may be valid for a given target if they are suffixed. In
731 this case these collections can only be restored if their suffix corre‐
732 spond to the current value of the MODULES_COLLECTION_TARGET environment
733 variable (see the dedicated section of this topic below).
734
736 The module command exits with 0 if its execution succeed. Elsewhere 1
737 is returned.
738
740 LOADEDMODULES
741 A colon separated list of all loaded modulefiles.
742 MODULECONTACT
744 Email address to contact in case any issue occurs during the inter‐
745 pretation of modulefiles.
746 MODULEPATH
748 The path that the module command searches when looking for module‐
749 files. Typically, it is set to the master modulefiles directory,
750 /usr/share/Modules/modulefiles, by the initialization script. MOD‐
751 ULEPATH can be set using module use or by the module initialization
752 script to search group or personal modulefile directories before or
753 after the master modulefile directory.
754 Path elements registered in the MODULEPATH environment variable may
756 contain reference to environment variables which are converted to
757 their corresponding value by module command each time it looks at
758 the MODULEPATH value. If an environment variable referred in a path
759 element is not defined, its reference is converted to an empty
760 string.
761 MODULERCFILE
763 The location of a global run-command file containing modulefile spe‐
764 cific setup. See Modulecmd startup section for detailed information.
765 MODULESHOME
767 The location of the master Modules package file directory containing
768 module command initialization scripts, the executable program mod‐
769 ulecmd.tcl, and a directory containing a collection of master mod‐
770 ulefiles.
771 MODULES_ADVANCED_VERSION_SPEC
773 If set to 1, enable advanced module version specifiers (see Advanced
774 module version specifiers section). If set to 0, disable advanced
775 module version specifiers.
776 Advanced module version specifiers enablement is defined in the fol‐
778 lowing order of preference: MODULES_ADVANCED_VERSION_SPEC environ‐
779 ment variable then the default set in modulecmd.tcl script configu‐
780 ration. Which means MODULES_ADVANCED_VERSION_SPEC overrides default
781 configuration.
782 MODULES_AUTO_HANDLING
784 If set to 1, enable automated module handling mode. If set to 0 dis‐
785 able automated module handling mode. Other values are ignored.
786 Automated module handling mode consists in additional actions trig‐
788 gered when loading or unloading a modulefile to satisfy the con‐
789 straints it declares. When loading a modulefile, following actions
790 are triggered:
791 · Requirement Load: load of the modulefiles declared as a prereq of
793 the loading modulefile.
794 · Dependent Reload: reload of the modulefiles declaring a prereq
796 onto loaded modulefile or declaring a prereq onto a modulefile
797 part of this reloading batch.
798 When unloading a modulefile, following actions are triggered:
800 · Dependent Unload: unload of the modulefiles declaring a
802 non-optional prereq onto unloaded modulefile or declaring a
803 non-optional prereq onto a modulefile part of this unloading
804 batch. A prereq modulefile is considered optional if the prereq
805 definition order is made of multiple modulefiles and at least one
806 alternative modulefile is loaded.
807 · Useless Requirement Unload: unload of the prereq modulefiles that
809 have been automatically loaded for either the unloaded modulefile,
810 an unloaded dependent modulefile or a modulefile part of this use‐
811 less requirement unloading batch. Modulefiles are added to this
812 unloading batch only if they are not required by any other loaded
813 modulefiles.
814 · Dependent Reload: reload of the modulefiles declaring a conflict
816 or an optional prereq onto either the unloaded modulefile, an
817 unloaded dependent or an unloaded useless requirement or declaring
818 a prereq onto a modulefile part of this reloading batch.
819 In case a loaded modulefile has some of its declared constraints
821 unsatisfied (pre-required modulefile not loaded or conflicting mod‐
822 ulefile loaded for instance), this loaded modulefile is excluded
823 from the automatic reload actions described above.
824 For the specific case of the switch sub-command, where a modulefile
826 is unloaded to then load another modulefile. Dependent modulefiles
827 to Unload are merged into the Dependent modulefiles to Reload that
828 are reloaded after the load of the switched-to modulefile.
829 Automated module handling mode enablement is defined in the follow‐
831 ing order of preference: --auto/--no-auto command line switches,
832 then MODULES_AUTO_HANDLING environment variable, then the default
833 set in modulecmd.tcl script configuration. Which means MOD‐
834 ULES_AUTO_HANDLING overrides default configuration and
835 --auto/--no-auto command line switches override every other ways to
836 enable or disable this mode.
837 MODULES_AVAIL_INDEPTH
839 If set to 1, enable in depth search results for avail sub-command.
840 If set to 0 disable avail sub-command in depth mode. Other values
841 are ignored.
842 When in depth mode is enabled, modulefiles and directories contained
844 in directories matching search query are also included in search
845 results. When disabled these modulefiles and directories contained
846 in matching directories are excluded.
847 avail sub-command in depth mode enablement is defined in the follow‐
849 ing order of preference: --indepth/--no-indepth command line
850 switches, then MODULES_AVAIL_INDEPTH environment variable, then the
851 default set in modulecmd.tcl script configuration. Which means MOD‐
852 ULES_AVAIL_INDEPTH overrides default configuration and
853 --indepth/--no-indepth command line switches override every other
854 ways to enable or disable this mode.
855 MODULES_CMD
857 The location of the active module command script.
858 MODULES_COLLECTION_PIN_VERSION
860 If set to 1, register exact version number of modulefiles when sav‐
861 ing a collection. Elsewhere modulefile version number is omitted if
862 it corresponds to the explicitly set default version and also to the
863 implicit default when config option implicit_default is enabled.
864 MODULES_COLLECTION_TARGET
866 The collection target that determines what collections are valid
867 thus reachable on the current system.
868 Collection directory may sometimes be shared on multiple machines
870 which may use different modules setup. For instance modules users
871 may access with the same HOME directory multiple systems using dif‐
872 ferent OS versions. When it happens a collection made on machine 1
873 may be erroneous on machine 2.
874 When a target is set, only the collections made for that target are
876 available to the restore, savelist, saveshow and saverm sub-com‐
877 mands. Saving collection registers the target footprint by suffixing
878 the collection filename with .$MODULES_COLLECTION_TARGET. Collection
879 target is not involved when collection is specified as file path on
880 the saveshow, restore and save sub-commands.
881 For example, the MODULES_COLLECTION_TARGET variable may be set with
883 results from commands like lsb_release, hostname, dnsdomainname,
884 etc.
885 MODULES_COLOR
887 Defines if output should be colored or not. Accepted values are
888 never, auto and always.
889 When color mode is set to auto, output is colored only if the stan‐
891 dard error output channel is attached to a terminal.
892 Colored output enablement is defined in the following order of pref‐
894 erence: --color command line switch, then MODULES_COLOR environment
895 variable, then CLICOLOR and CLICOLOR_FORCE environment variables,
896 then the default set in modulecmd.tcl script configuration. Which
897 means MODULES_COLOR overrides default configuration and the CLI‐
898 COLOR/CLICOLOR_FORCE variables. --color command line switch over‐
899 rides every other ways to enable or disable this mode.
900 CLICOLOR and CLICOLOR_FORCE environment variables are also honored
902 to define color mode. The never mode is set if CLICOLOR equals to 0.
903 If CLICOLOR is set to another value, it corresponds to the auto
904 mode. The always mode is set if CLICOLOR_FORCE is set to a value
905 different than 0. Color mode set with these two variables is super‐
906 seded by mode set with MODULES_COLOR environment variable.
907 MODULES_COLORS
909 Specifies the colors and other attributes used to highlight various
910 parts of the output. Its value is a colon-separated list of output
911 items associated to a Select Graphic Rendition (SGR) code. It fol‐
912 lows the same syntax than LS_COLORS.
913 Output items are designated by keys. Items able to be colorized are:
915 highlighted element (hi), debug information (db), tag separator
916 (se); Error (er), warning (wa), module error (me) and info (in) mes‐
917 sage prefixes; Modulepath (mp), directory (di), module alias (al),
918 module symbolic version (sy), module default version (de) and mod‐
919 ulefile command (cm).
920 See the Select Graphic Rendition (SGR) section in the documentation
922 of the text terminal that is used for permitted values and their
923 meaning as character attributes. These substring values are integers
924 in decimal representation and can be concatenated with semicolons.
925 Modules takes care of assembling the result into a complete SGR
926 sequence (33[...m). Common values to concatenate include 1 for bold,
927 4 for underline, 30 to 37 for foreground colors and 90 to 97 for
928 16-color mode foreground colors. See also
929 https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters
930 for a complete SGR code reference.
931 No graphical rendition will be applied to an output item that could
933 normaly be colored but which is not defined in the color set. Thus
934 if MODULES_COLORS is defined empty, no output will be colored at
935 all.
936 The color set is defined for Modules in the following order of pref‐
938 erence: MODULES_COLORS environment variable, then the default set in
939 modulecmd.tcl script configuration. Which means MODULES_COLORS over‐
940 rides default configuration.
941 MODULES_EXTENDED_DEFAULT
943 If set to 1, a specified module version is matched against starting
944 portion of existing module versions, where portion is a substring
945 separated from the rest of the version string by a . character. For
946 example specified modules mod/1 and mod/1.2 will match existing
947 modulefile mod/1.2.3.
948 In case multiple modulefiles match specified module version and a
950 single module has to be selected, explicitly set default version is
951 returned if it is part of matching modulefiles. Elsewhere implicit
952 default among matching modulefiles is returned if defined (see MOD‐
953 ULES_IMPLICIT_DEFAULT section)
954 This environment variable supersedes the value of the configuration
956 option extended_default set in modulecmd.tcl script.
957 MODULES_ICASE
959 When module specification are passed as argument to module sub-com‐
960 mands or modulefile Tcl commands, defines the case sensitiveness to
961 apply to match them. When MODULES_ICASE is set to never, a case sen‐
962 sitive match is applied in any cases. When set to search, a case
963 insensitive match is applied to the avail, whatis and paths sub-com‐
964 mands. When set to always, a case insensitive match is also applied
965 to the other module sub-commands and modulefile Tcl commands for the
966 module specification they receive as argument.
967 Case sensitiveness behavior is defined in the following order of
969 preference: --icase command line switch, which corresponds to the
970 always mode, then MODULES_ICASE environment variable, then the
971 default set in modulecmd.tcl script configuration. Which means MOD‐
972 ULES_ICASE overrides default configuration and --icase command line
973 switch overrides every other ways to set case sensitiveness behav‐
974 ior.
975 MODULES_IMPLICIT_DEFAULT
977 Defines (if set to 1) or not (if set to 0) an implicit default ver‐
978 sion for modules without a default version explicitly defined (see
979 Locating Modulefiles section in the modulefile(4) man page).
980 Without either an explicit or implicit default version defined a
982 module must be fully qualified (version should be specified in addi‐
983 tion to its name) to get:
984 · targeted by module load, switch, display, help, test and path
986 sub-commands.
987 · restored from a collection, unless already loaded in collec‐
989 tion-specified order.
990 · automatically loaded by automated module handling mechanisms (see
992 MODULES_AUTO_HANDLING section) when declared as module require‐
993 ment, with prereq or module load modulefile commands.
994 An error is returned in the above situations if either no explicit
996 or implicit default version is defined.
997 This environment variable supersedes the value of the configuration
999 option implicit_default set in modulecmd.tcl script. This environ‐
1000 ment variable is ignored if implicit_default has been declared
1001 locked in locked_configs configuration option.
1002 MODULES_LMALTNAME
1004 A colon separated list of the alternative names set through mod‐
1005 ule-version and module-alias statements corresponding to all loaded
1006 modulefiles. Each element in this list starts by the name of the
1007 loaded modulefile followed by all alternative names resolving to it.
1008 The loaded modulefile and its alternative names are separated by the
1009 ampersand character.
1010 This environment variable is intended for module command internal
1012 use to get knowledge of the alternative names matching loaded mod‐
1013 ulefiles in order to keep environment consistent when conflicts or
1014 pre-requirements are set over these alternative designations. It
1015 also helps to find a match after modulefiles being loaded when
1016 unload, is-loaded or info-loaded actions are run over these names.
1017 MODULES_LMCONFLICT
1019 A colon separated list of the conflict statements defined by all
1020 loaded modulefiles. Each element in this list starts by the name of
1021 the loaded modulefile declaring the conflict followed by the name of
1022 all modulefiles it declares a conflict with. These loaded module‐
1023 files and conflicting modulefile names are separated by the amper‐
1024 sand character.
1025 This environment variable is intended for module command internal
1027 use to get knowledge of the conflicts declared by the loaded module‐
1028 files in order to keep environment consistent when a conflicting
1029 module is asked for load afterward.
1030 MODULES_LMNOTUASKED
1032 A colon separated list of all loaded modulefiles that were not
1033 explicitly asked for load from the command-line.
1034 This environment variable is intended for module command internal
1036 use to distinguish the modulefiles that have been loaded automati‐
1037 cally from modulefiles that have been asked by users.
1038 MODULES_LMPREREQ
1040 A colon separated list of the prereq statements defined by all
1041 loaded modulefiles. Each element in this list starts by the name of
1042 the loaded modulefile declaring the pre-requirement followed by the
1043 name of all modulefiles it declares a prereq with. These loaded mod‐
1044 ulefiles and pre-required modulefile names are separated by the
1045 ampersand character. When a prereq statement is composed of multiple
1046 modulefiles, these modulefile names are separated by the pipe char‐
1047 acter.
1048 This environment variable is intended for module command internal
1050 use to get knowledge of the pre-requirement declared by the loaded
1051 modulefiles in order to keep environment consistent when a
1052 pre-required module is asked for unload afterward.
1053 MODULES_PAGER
1055 Text viewer for use to paginate message output if error output
1056 stream is attached to a terminal. The value of this variable is com‐
1057 posed of a pager command name or path eventually followed by com‐
1058 mand-line options.
1059 Paging command and options are defined for Modules in the following
1061 order of preference: MODULES_PAGER environment variable, then the
1062 default set in modulecmd.tcl script configuration. Which means MOD‐
1063 ULES_PAGER overrides default configuration.
1064 If MODULES_PAGER variable is set to an empty string or to the value
1066 cat, pager will not be launched.
1067 MODULES_RUNENV_<VAR>
1069 Value to set to environment variable <VAR> for modulecmd.tcl
1070 run-time execution if <VAR> is referred in MODULES_RUN_QUARANTINE.
1071 MODULES_RUN_QUARANTINE
1073 A space separated list of environment variable names that should be
1074 passed indirectly to modulecmd.tcl to protect its run-time environ‐
1075 ment from side-effect coming from their current definition.
1076 Each variable found in MODULES_RUN_QUARANTINE will have its value
1078 emptied or set to the value of the corresponding MOD‐
1079 ULES_RUNENV_<VAR> variable when defining modulecmd.tcl run-time
1080 environment.
1081 Original values of these environment variables set in quarantine are
1083 passed to modulecmd.tcl via <VAR>_modquar variables.
1084 MODULES_SEARCH_MATCH
1086 When searching for modules with avail sub-command, defines the way
1087 query string should match against available module names. With
1088 starts_with value, returned modules are those whose name begins by
1089 search query string. When set to contains, any modules whose fully
1090 qualified name contains search query string are returned.
1091 Module search match style is defined in the following order of pref‐
1093 erence: --starts-with and --contains command line switches, then
1094 MODULES_SEARCH_MATCH environment variable, then the default set in
1095 modulecmd.tcl script configuration. Which means MODULES_SEARCH_MATCH
1096 overrides default configuration and --starts-with/--contains command
1097 line switches override every other ways to set search match style.
1098 MODULES_SET_SHELL_STARTUP
1100 If set to 1, defines when module command initializes the shell
1101 startup file to ensure that the module command is still defined in
1102 sub-shells. Setting shell startup file means defining the ENV and
1103 BASH_ENV environment variable to the Modules bourne shell initial‐
1104 ization script. If set to 0, shell startup file is not defined.
1105 MODULES_SILENT_SHELL_DEBUG
1107 If set to 1, disable any xtrace or verbose debugging property set on
1108 current shell session for the duration of either the module command
1109 or the module shell initialization script. Only applies to Bourne
1110 Shell (sh) and its derivatives.
1111 MODULES_SITECONFIG
1113 Location of a site-specific configuration script to source into mod‐
1114 ulecmd.tcl. See also Modulecmd startup section.
1115 This environment variable is ignored if extra_siteconfig has been
1117 declared locked in locked_configs configuration option.
1118 MODULES_TERM_BACKGROUND
1120 Inform Modules of the terminal background color to determine if the
1121 color set for dark background or the color set for light background
1122 should be used to color output in case no specific color set is
1123 defined with the MODULES_COLORS variable. Accepted values are dark
1124 and light.
1125 MODULES_UNLOAD_MATCH_ORDER
1127 When a module unload request matches multiple loaded modules, unload
1128 firstly loaded module or lastly loaded module. Accepted values are
1129 returnfirst and returnlast.
1130 MODULES_USE_COMPAT_VERSION
1132 If set to 1 prior to Modules package initialization, enable Modules
1133 compatibility version (3.2 release branch) rather main version at
1134 initialization scripts running time. Modules package compatibility
1135 version should be installed along with main version for this envi‐
1136 ronment variable to have any effect.
1137 MODULES_VERBOSITY
1139 Defines the verbosity level of the module command. Available ver‐
1140 bosity levels from the least to the most verbose are:
1141 · silent: turn off error, warning and informational messages but
1143 does not affect module command output result.
1144 · concise: enable error and warning messages but disable informa‐
1146 tional messages.
1147 · normal: turn on informational messages, like a report of the addi‐
1149 tional module evaluations triggered by loading or unloading mod‐
1150 ules, aborted evaluation issues or a report of each module evalua‐
1151 tion occurring during a restore or source sub-commands.
1152 · verbose: add additional informational messages, like a systematic
1154 report of the loading or unloading module evaluations.
1155 · debug: print debugging messages about module command execution.
1157 Module command verbosity is defined in the following order of pref‐
1159 erence: --silent, --verbose and --debug command line switches, then
1160 MODULES_VERBOSITY environment variable, then the default set in mod‐
1161 ulecmd.tcl script configuration. Which means MODULES_VERBOSITY over‐
1162 rides default configuration and --silent/--verbose/--debug command
1163 line switches overrides every other ways to set verbosity level.
1164 MODULES_WA_277
1166 If set to 1 prior to Modules package initialization, enables work‐
1167 around for Tcsh history issue (see
1168 https://github.com/cea-hpc/modules/issues/277). This issue leads to
1169 erroneous history entries under Tcsh shell. When workaround is
1170 enabled, an alternative module alias is defined which fixes the his‐
1171 tory mechanism issue. However the alternative definition of the mod‐
1172 ule alias weakens shell evaluation of the code produced by module‐
1173 files. Characters with special meaning for Tcsh shell (like { and
1174 }) may not be used anymore in shell alias definition elsewhere the
1175 evaluation of the code produced by modulefiles will return a syntax
1176 error.
1177 _LMFILES_
1179 A colon separated list of the full pathname for all loaded module‐
1180 files.
1181 <VAR>_modquar
1183 Value of environment variable <VAR> passed to modulecmd.tcl in order
1184 to restore <VAR> to this value once started.
1185 <VAR>_modshare
1187 Reference counter variable for path-like variable <VAR>. A colon
1188 separated list containing pairs of elements. A pair is formed by a
1189 path element followed its usage counter which represents the number
1190 of times this path has been enabled in variable <VAR>. A colon sepa‐
1191 rates the two parts of the pair.
1192
1194 /usr/share/Modules
1195 The MODULESHOME directory.
1196 /etc/environment-modules/siteconfig.tcl
1198 The site-specific configuration script of modulecmd.tcl. An addi‐
1199 tional configuration script could be defined using the MODULES_SITE‐
1200 CONFIG environment variable.
1201 /etc/environment-modules/rc
1203 The system-wide modules rc file. The location of this file can be
1204 changed using the MODULERCFILE environment variable as described
1205 above.
1206 $HOME/.modulerc
1208 The user specific modules rc file.
1209 $HOME/.module
1211 The user specific collection directory.
1212 /usr/share/Modules/modulefiles
1214 The directory for system-wide modulefiles. The location of the
1215 directory can be changed using the MODULEPATH environment variable
1216 as described above.
1217 /usr/share/Modules/libexec/modulecmd.tcl
1219 The modulefile interpreter that gets executed upon each invocation
1220 of module.
1221 /usr/share/Modules/init/<shell>
1223 The Modules package initialization file sourced into the user's
1224 environment.
1225
1227 modulefile(4)
1228
1230 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
1231 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2020 Xavier Delaruelle
12324.4.1 2020-01-03 MODULE(1)