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 if it exists a site-specific con‐
84 figuration script located in /usr/share/Modules/etc/siteconfig.tcl.
85 This Tcl script enables to supersede any global variable or procedure
86 definition of modulecmd.tcl.
87 Afterward, modulecmd.tcl sources rc files which contain global, user
89 and modulefile specific setups. These files are interpreted as module‐
90 files. See modulefile(4) for detailed information.
91 Upon invocation of modulecmd.tcl module run-command files are sourced
93 in the following order:
94 1. Global RC file as specified by $MODULERCFILE or /usr/share/Mod‐
96 ules/etc/rc. If $MODULERCFILE points to a directory, the modulerc
97 file in this directory is used as global RC file.
98 2. User specific module RC file $HOME/.modulerc
100 3. All .modulerc and .version files found during modulefile seeking.
102 Command line switches
104 The module command accepts command line switches as its first parame‐
105 ter. These may be used to control output format of all information
106 displayed and the module behavior in case of locating and interpreting
107 modulefiles.
108 All switches may be entered either in short or long notation. The fol‐
110 lowing switches are accepted:
111 --help, -h
113 Give some helpful usage information, and terminates the command.
114 --version, -V
116 Lists the current version of the module command. The command then
117 terminates without further processing.
118 --debug, -D
120 Debug mode. Causes module to print debugging messages about its
121 progress.
122 --paginate
124 Pipe all message output into less (or if set, $MODULES_PAGER) if
125 error output stream is a terminal. See also MODULES_PAGER section.
126 --no-pager
128 Do not pipe message output into a pager.
129 --terse, -t
131 Display avail, list and savelist output in short format.
132 --long, -l
134 Display avail, list and savelist output in long format.
135 --default, -d
137 On avail sub-command, display only the default version of each mod‐
138 ule name. Default version is either the explicitly set default ver‐
139 sion or the highest numerically sorted modulefile if no default ver‐
140 sion set (see Locating Modulefiles section in the modulefile(4) man
141 page).
142 --latest, -L
144 On avail sub-command, display only the highest numerically sorted
145 version of each module name (see Locating Modulefiles section in the
146 modulefile(4) man page).
147 Module Sub-Commands
149 help [modulefile...]
150 Print the usage of each sub-command. If an argument is given, print
151 the Module-specific help information for the modulefile.
152 add modulefile...
154 See load.
155 load modulefile...
157 Load modulefile into the shell environment.
158 rm modulefile...
160 See unload.
161 unload modulefile...
163 Remove modulefile from the shell environment.
164 swap [modulefile1] modulefile2
166 See switch.
167 switch [modulefile1] modulefile2
169 Switch loaded modulefile1 with modulefile2. If modulefile1 is not
170 specified, then it is assumed to be the currently loaded module with
171 the same root name as modulefile2.
172 show modulefile...
174 See display.
175 display modulefile...
177 Display information about one or more modulefiles. The display
178 sub-command will list the full path of the modulefile and the envi‐
179 ronment changes the modulefile will make if loaded. (Note: It will
180 not display any environment changes found within conditional state‐
181 ments.)
182 list [-t|-l]
184 List loaded modules.
185 avail [-d|-L] [-t|-l] [path...]
187 List all available modulefiles in the current MODULEPATH. All direc‐
188 tories in the MODULEPATH are recursively searched for files contain‐
189 ing the modulefile magic cookie. If an argument is given, then each
190 directory in the MODULEPATH is searched for modulefiles whose path‐
191 name, symbolic version-name or alias match the argument. Argument
192 may contain wildcard characters. Multiple versions of an application
193 can be supported by creating a subdirectory for the application con‐
194 taining modulefiles for each version.
195 Symbolic version-names and aliases found in the search are displayed
197 in the result of this sub-command. Symbolic version-names are dis‐
198 played next to the modulefile they are assigned to within parenthe‐
199 sis. Aliases are listed in the MODULEPATH section where they have
200 been defined. To distinguish aliases from modulefiles a @ symbol is
201 added within parenthesis next to their name. Aliases defined through
202 a global or user specific module RC file are listed under the
203 global/user modulerc section.
204 aliases
206 List all available symbolic version-names and aliases in the current
207 MODULEPATH. All directories in the MODULEPATH are recursively
208 searched in the same manner than for the avail sub-command. Only the
209 symbolic version-names and aliases found in the search are dis‐
210 played.
211 use [-a|--append] directory...
213 Prepend one or more directories to the MODULEPATH environment vari‐
214 able. The --append flag will append the directory to MODULEPATH.
215 Reference counter environment variable MODULEPATH_modshare is also
217 set to increase the number of times directory has been added to MOD‐
218 ULEPATH.
219 unuse directory...
221 Remove one or more directories from the MODULEPATH environment vari‐
222 able if reference counter of these directories is equal to 1 or
223 unknown.
224 Reference counter of directory in MODULEPATH denotes the number of
226 times directory has been enabled. When attempting to remove direc‐
227 tory from MODULEPATH, reference counter variable MODULEPATH_modshare
228 is checked and directory is removed only if its relative counter is
229 equal to 1 or not defined. Elsewhere directory is kept and reference
230 counter is decreased by 1.
231 refresh
233 See reload.
234 reload
236 Unload then load all loaded modulefiles.
237 purge
239 Unload all loaded modulefiles.
240 source modulefile...
242 Execute modulefile into the shell environment. modulefile must be
243 specified with a fully qualified path. Once executed modulefile is
244 not marked loaded in shell environment which differ from load
245 sub-command.
246 whatis [modulefile...]
248 Display the information set up by the module-whatis commands inside
249 the specified modulefiles. These specified modulefiles may be
250 expressed using wildcard characters. If no modulefile is specified,
251 all module-whatis lines will be shown.
252 apropos string
254 See search.
255 keyword string
257 See search.
258 search string
260 Seeks through the module-whatis informations of all modulefiles for
261 the specified string. All module-whatis informations matching the
262 string will be displayed. string may contain wildcard characters.
263 test modulefile...
265 Execute and display results of the Module-specific tests for the
266 modulefile.
267 save [collection]
269 Record the currently set MODULEPATH directory list and the currently
270 loaded modulefiles in a collection file under the user's collection
271 directory $HOME/.module. If collection name is not specified, then
272 it is assumed to be the default collection. If collection is a fully
273 qualified path, it is saved at this location rather than under the
274 user's collection directory.
275 If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the
277 value of this variable will be appended to the collection file name.
278 By default, if loaded modulefile corresponds to the default module
280 version, the bare module name is recorded. If MODULES_COLLEC‐
281 TION_PIN_VERSION is set to 1, module version is always recorded even
282 if it is the default version.
283 restore [collection]
285 Restore the environment state as defined in collection. If collec‐
286 tion name is not specified, then it is assumed to be the default
287 collection. If collection is a fully qualified path, it is restored
288 from this location rather than from a file under the user's collec‐
289 tion directory. If MODULES_COLLECTION_TARGET is set, a suffix equiv‐
290 alent to the value of this variable is appended to the collection
291 file name to restore.
292 When restoring a collection, the currently set MODULEPATH directory
294 list and the currently loaded modulefiles are unused and unloaded
295 then used and loaded to exactly match the MODULEPATH and loaded mod‐
296 ulefiles lists saved in this collection file. The order of the paths
297 and modulefiles set in collection is preserved when restoring. It
298 means that currently loaded modules are unloaded to get the same
299 LOADEDMODULES root than collection and currently used module paths
300 are unused to get the same MODULEPATH root. Then missing module
301 paths are used and missing modulefiles are loaded.
302 saverm [collection]
304 Delete the collection file under the user's collection directory. If
305 collection name is not specified, then it is assumed to be the
306 default collection. If MODULES_COLLECTION_TARGET is set, a suffix
307 equivalent to the value of this variable will be appended to the
308 collection file name.
309 saveshow [collection]
311 Display the content of collection. If collection name is not speci‐
312 fied, then it is assumed to be the default collection. If collection
313 is a fully qualified path, this location is displayed rather than a
314 collection file under the user's collection directory. If MOD‐
315 ULES_COLLECTION_TARGET is set, a suffix equivalent to the value of
316 this variable will be appended to the collection file name.
317 savelist [-t|-l]
319 List collections that are currently saved under the user's collec‐
320 tion directory. If MODULES_COLLECTION_TARGET is set, only collec‐
321 tions matching the target suffix will be displayed.
322 initadd modulefile...
324 Add modulefile to the shell's initialization file in the user's home
325 directory. The startup files checked (in order) are:
326 C Shell
328 .modules, .cshrc, .csh_variables and .login
329 TENEX C Shell
331 .modules, .tcshrc, .cshrc, .csh_variables and .login
332 Bourne and Korn Shells
334 .modules, .profile
335 GNU Bourne Again Shell
337 .modules, .bash_profile, .bash_login, .profile and .bashrc
338 Z Shell
340 .modules, .zshrc, .zshenv and .zlogin
341 Friendly Interactive Shell
343 .modules, .config/fish/config.fish
344 If a module load line is found in any of these files, the module‐
346 files are appended to any existing list of modulefiles. The module
347 load line must be located in at least one of the files listed above
348 for any of the init sub-commands to work properly. If the module
349 load line is found in multiple shell initialization files, all of
350 the lines are changed.
351 initprepend modulefile...
353 Does the same as initadd but prepends the given modules to the
354 beginning of the list.
355 initrm modulefile...
357 Remove modulefile from the shell's initialization files.
358 initswitch modulefile1 modulefile2
360 Switch modulefile1 with modulefile2 in the shell's initialization
361 files.
362 initlist
364 List all of the modulefiles loaded from the shell's initialization
365 file.
366 initclear
368 Clear all of the modulefiles from the shell's initialization files.
369 path modulefile
371 Print path to modulefile.
372 paths modulefile
374 Print path of available modulefiles matching argument.
375 append-path [-d C|--delim C|--delim=C] [--duplicates] variable value...
377 Append value to environment variable. The variable is a colon, or
378 delimiter, separated list. See append-path in the modulefile(4) man
379 page for further explanation.
380 prepend-path [-d C|--delim C|--delim=C] [--duplicates] variable
382 value...
383 Prepend value to environment variable. The variable is a colon, or
384 delimiter, separated list. See prepend-path in the modulefile(4) man
385 page for further explanation.
386 remove-path [-d C|--delim C|--delim=C] [--index] variable value...
388 Remove value from the colon, or delimiter, separated list in envi‐
389 ronment variable. See remove-path in the modulefile(4) man page for
390 further explanation.
391 is-loaded [modulefile...]
393 Returns a true value if any of the listed modulefiles has been
394 loaded or if any modulefile is loaded in case no argument is pro‐
395 vided. Returns a false value elsewhere. See is-loaded in the module‐
396 file(4) man page for further explanation.
397 is-saved [collection...]
399 Returns a true value if any of the listed collections exists or if
400 any collection exists in case no argument is provided. Returns a
401 false value elsewhere. See is-saved in the modulefile(4) man page
402 for further explanation.
403 is-used [directory...]
405 Returns a true value if any of the listed directories has been
406 enabled in MODULEPATH or if any directory is enabled in case no
407 argument is provided. Returns a false value elsewhere. See is-used
408 in the modulefile(4) man page for further explanation.
409 is-avail modulefile...
411 Returns a true value if any of the listed modulefiles exists in
412 enabled MODULEPATH. Returns a false value elsewhere. See is-avail in
413 the modulefile(4) man page for further explanation.
414 info-loaded modulefile
416 Returns the names of currently loaded modules matching passed mod‐
417 ulefile. Returns an empty string if passed modulefile does not
418 match any loaded modules. See module-info loaded in the module‐
419 file(4) man page for further explanation.
420 Modulefiles
422 modulefiles are written in the Tool Command Language (Tcl) and are
423 interpreted by modulecmd.tcl. modulefiles can use conditional state‐
424 ments. Thus the effect a modulefile will have on the environment may
425 change depending upon the current state of the environment.
426 Environment variables are unset when unloading a modulefile. Thus, it
428 is possible to load a modulefile and then unload it without having the
429 environment variables return to their prior state.
430 Collections
432 Collections describe a sequence of module use then module load commands
433 that are interpreted by modulecmd.tcl to set the user environment as
434 described by this sequence. When a collection is activated, with the
435 restore sub-command, module paths and loaded modules are unused or
436 unloaded if they are not part or if they are not ordered the same way
437 as in the collection.
438 Collections are generated by the save sub-command that dumps the cur‐
440 rent user environment state in terms of module paths and loaded mod‐
441 ules. By default collections are saved under the $HOME/.module direc‐
442 tory.
443 Collections may be valid for a given target if they are suffixed. In
445 this case these collections can only be restored if their suffix corre‐
446 spond to the current value of the MODULES_COLLECTION_TARGET environment
447 variable (see the dedicated section of this topic below).
448
450 The module command exits with 0 if its execution succeed. Elsewhere 1
451 is returned.
452
454 LOADEDMODULES
455 A colon separated list of all loaded modulefiles.
456 MODULEPATH
458 The path that the module command searches when looking for module‐
459 files. Typically, it is set to the master modulefiles directory,
460 /usr/share/Modules/modulefiles, by the initialization script. MOD‐
461 ULEPATH can be set using module use or by the module initialization
462 script to search group or personal modulefile directories before or
463 after the master modulefile directory.
464 Path elements registered in the MODULEPATH environment variable may
466 contain reference to environment variables which are converted to
467 their corresponding value by module command each time it looks at
468 the MODULEPATH value. If an environment variable referred in a path
469 element is not defined, its reference is converted to an empty
470 string.
471 MODULESHOME
473 The location of the master Modules package file directory containing
474 module command initialization scripts, the executable program mod‐
475 ulecmd.tcl, and a directory containing a collection of master mod‐
476 ulefiles.
477 MODULES_CMD
479 The location of the active module command script.
480 MODULES_COLLECTION_PIN_VERSION
482 If set to 1, register exact version number of modulefiles when sav‐
483 ing a collection. Elsewhere modulefile version number is omitted if
484 it corresponds to the implicit or explicitly set default version.
485 MODULES_COLLECTION_TARGET
487 The collection target that determines what collections are valid
488 thus reachable on the current system.
489 Collection directory may sometimes be shared on multiple machines
491 which may use different modules setup. For instance modules users
492 may access with the same HOME directory multiple systems using dif‐
493 ferent OS versions. When it happens a collection made on machine 1
494 may be erroneous on machine 2.
495 When a target is set, only the collections made for that target are
497 available to the restore, savelist, saveshow and saverm sub-com‐
498 mands. Saving collection registers the target footprint by suffixing
499 the collection filename with .$MODULES_COLLECTION_TARGET. Collection
500 target is not involved when collection is specified as file path on
501 the saveshow, restore and save sub-commands.
502 For example, the MODULES_COLLECTION_TARGET variable may be set with
504 results from commands like lsb_release, hostname, dnsdomainname,
505 etc.
506 MODULES_PAGER
508 Text viewer for use to paginate message output if error output
509 stream is attached to a terminal. The value of this variable is com‐
510 posed of a pager command name or path eventually followed by com‐
511 mand-line options.
512 Paging command and options are defined for Modules in the following
514 order of preference: MODULES_PAGER environment variable, then the
515 default set in modulecmd.tcl script configuration. Which means MOD‐
516 ULES_PAGER overrides default configuration.
517 If MODULES_PAGER variable is set to an empty string or to the value
519 cat, pager will not be launched.
520 MODULES_RUNENV_<VAR>
522 Value to set to environment variable <VAR> for modulecmd.tcl
523 run-time execution if <VAR> is referred in MODULES_RUN_QUARANTINE.
524 MODULES_RUN_QUARANTINE
526 A space separated list of environment variable names that should be
527 passed indirectly to modulecmd.tcl to protect its run-time environ‐
528 ment from side-effect coming from their current definition.
529 Each variable found in MODULES_RUN_QUARANTINE will have its value
531 emptied or set to the value of the corresponding MOD‐
532 ULES_RUNENV_<VAR> variable when defining modulecmd.tcl run-time
533 environment.
534 Original values of these environment variables set in quarantine are
536 passed to modulecmd.tcl via <VAR>_modquar variables.
537 MODULES_SILENT_SHELL_DEBUG
539 If set to 1, disable any xtrace or verbose debugging property set on
540 current shell session for the duration of either the module command
541 or the module shell initialization script. Only applies to Bourne
542 Shell (sh) and its derivatives.
543 MODULES_USE_COMPAT_VERSION
545 If set to 1 prior to Modules package initialization, enable Modules
546 compatibility version (3.2 release branch) rather main version at
547 initialization scripts running time. Modules package compatibility
548 version should be installed along with main version for this envi‐
549 ronment variable to have any effect.
550 _LMFILES_
552 A colon separated list of the full pathname for all loaded module‐
553 files.
554 <VAR>_modquar
556 Value of environment variable <VAR> passed to modulecmd.tcl in order
557 to restore <VAR> to this value once started.
558 <VAR>_modshare
560 Reference counter variable for path-like variable <VAR>. A colon
561 separated list containing pairs of elements. A pair is formed by a
562 path element followed its usage counter which represents the number
563 of times this path has been enabled in variable <VAR>. A colon sepa‐
564 rates the two parts of the pair.
565
567 /usr/share/Modules
568 The MODULESHOME directory.
569 /usr/share/Modules/etc/rc
571 The system-wide modules rc file. The location of this file can be
572 changed using the MODULERCFILE environment variable as described
573 above.
574 $HOME/.modulerc
576 The user specific modules rc file.
577 $HOME/.module
579 The user specific collection directory.
580 /usr/share/Modules/modulefiles
582 The directory for system-wide modulefiles. The location of the
583 directory can be changed using the MODULEPATH environment variable
584 as described above.
585 /usr/share/Modules/libexec/modulecmd.tcl
587 The modulefile interpreter that gets executed upon each invocation
588 of module.
589 /usr/share/Modules/init/<shell>
591 The Modules package initialization file sourced into the user's
592 environment.
593
595 modulefile(4)
596
598 1996-1999 John L. Furlani & Peter W. Osel, 1998-2017 R.K.Owen,
599 2002-2004 Mark Lakata, 2004-2017 Kent Mein, 2016-2018 Xavier Delaruelle
6004.1.4 2018-08-20 MODULE(1)