MODULE(1)

📦

version 5.7.0 · 18 versions

✨ MODULE(1) ✨ — the `module` command, bestie edition 💅

okay so real talk: this is the manual page for module, and it lives in the Modules section of the manual. buckle up, it's a long one, but it's gonna be iconic 🎀

🌸 NAME 🌸

module — the command interface to the Modules package 🫶

🦋 SYNOPSIS 🦋

module [switches] [sub-command [sub-command-args]]

💖 DESCRIPTION 💖

okay so module is your user interface to the Modules package, and the Modules package is literally the thing that does dynamic modification of your environment via modulefiles. slay 💅

each modulefile holds all the info needed to configure your shell for an application. once the Modules package is initialized, you can modify the environment on a per-module basis using the module command, which interprets modulefiles. typically modulefiles instruct the module command to alter or set shell environment variables like PATH, MANPATH, etc. modulefiles may be shared by lots of users on a system, and users may also have their own set to supplement or replace the shared ones — so you can have your own little corner 💜

the modulefiles get added to and removed from the current environment by the user. the environment changes contained in a modulefile can be summarized through the module command too. and if you give no arguments at all, you get a summary of module usage and the sub-commands. cute, right? ✨

the action the module command takes is described by the sub-command and its associated arguments.

🧚 Package Initialization 🧚

the Modules package and the module command get initialized when a shell-specific initialization script is sourced into the shell. the script executes the autoinit sub-command of the modulecmd.tcl program located in /usr/share/Modules/libexec for the corresponding shell. the output of this execution is evaluated by the shell, which creates the module command as either an alias or function, and creates the Modules environment variables.

during this initialization process, if the Modules environment is found undefined (when both MODULEPATH and LOADEDMODULES are found either unset or empty), the modulespath and initrc configuration files located in /etc/environment-modules are evaluated if present, and in this order. the modulespath file contains the list of modulepaths to enable during initialization — in this file the modulepaths are separated by newline or colon characters. initrc is a modulefile that defines, during initialization, the modulepaths to enable, the modules to load and the module configuration to apply.

during the initialization process, if the Modules environment is found defined, a module refresh is automatically applied to restore in the current environment all non-persistent components set by loaded modules 😤

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

the initialization scripts are kept in /usr/share/Modules/init/<shell> where <shell> is the name of the sourcing shell. for example, a C Shell user sources the /usr/share/Modules/init/csh script. the sh, csh, tcsh, bash, ksh, zsh, fish, cmd and pwsh shells are supported by modulecmd.tcl. plus, python, perl, ruby, tcl, cmake, r and lisp "shells" are supported, which writes the environment changes to stdout as python, perl, ruby, tcl, lisp, r or cmake code. the range? unmatched 🌈

initialization may also be performed by directly calling the autoinit sub-command of the modulecmd.tcl program.

a ml alias or function may also be defined at initialization time if enabled (see the MODULES_ML section). ml is a handy frontend leveraging all module command capabilities with less characters typed — see ml for all the detailed info 💫

a mogui alias or function may also be defined at initialization time if the mogui-cmd command is found in PATH. mogui is the Graphical User Interface for Modules. environment changes performed in the GUI are applied onto the shell session that executed mogui 🖥️✨

the installation location of the env_modules Python module (which is defined with the --with-pythondir installation option) may also be added to the PYTHONPATH environment variable during initialization, unless the --enable-set-pythonpath installation option has been disabled.

🍓 Examples of initialization 🍓

these are verbatim, bestie — copy them exactly, no cap 🙈

C Shell initialization (and derivatives):

source /usr/share/Modules/init/csh
module load modulefile modulefile ...

Bourne Shell (sh) (and derivatives):

. /usr/share/Modules/init/sh
module load modulefile modulefile ...

PowerShell (pwsh):

. /usr/share/Modules/init/pwsh.ps1
envmodule load modulefile modulefile ...

Perl:

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

Python:

from env_modules import module
module("load", "modulefile", "modulefile", "...")

Alternative initialization for Python if env_modules script is not part of an enabled Python module directory:

import sys
sys.path.insert(1, "/usr/share/Modules/init")
from env_modules import module
module("load", "modulefile", "modulefile", "...")

Ruby:

require '/usr/share/Modules/init/ruby.rb'
ENVModule.module('load', 'modulefile', 'modulefile', '...')

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

eval "$(/usr/share/Modules/libexec/modulecmd.tcl sh autoinit)"

🧁 Modulecmd startup 🧁

upon invocation, modulecmd.tcl sources a site-specific configuration script if it exists. the siteconfig script is a Tcl script located at /etc/environment-modules/siteconfig.tcl. it lets you supersede any global variable or procedure definition of modulecmd.tcl. see "Site-specific configuration" for the detailed tea ☕

afterward, modulecmd.tcl sources rc files which contain global, user and modulefile-specific setups. these files are interpreted as modulefiles — see modulefile for the full rundown 👑

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

Global RC file(s) as specified by MODULERCFILE variable or /etc/environment-modules/rc. If a path element in MODULERCFILE points to a directory, the modulerc file in this directory is used as a global RC file.
User specific module RC file $HOME/.modulerc
All .modulerc and .version files found during modulefile seeking.

these module run-command files must begin like modulefiles do, with the #%Module file signature — also called the Modules magic cookie 🍪✨. a version number may be placed after this string. the version number reflects the minimum version of modulecmd.tcl required to interpret the run-command file. if a version number doesn't exist, then modulecmd.tcl will assume the run-command file is compatible. files without the magic cookie, or with a version number greater than the current version of modulecmd.tcl, will not be interpreted and an error is reported 😭. such an error does not abort the whole module evaluation, so breathe. if the mcookie_version_check configuration is disabled, the version number set is not checked.

Note: run-command files are intended to set parameters for modulefiles, not to configure the module command itself. iykyk 💀

💅 Command line switches 💅

the module command accepts command line switches as its first parameter. these may be used to control the output format of all information displayed, and the module behavior when locating and interpreting modulefiles.

all switches may be entered either in short or long notation. the following switches are accepted:

--all, -a — include hidden modules in the search performed with the avail, aliases, list, lint, savelist, search, spider or whatis sub-commands. hard-hidden modules are not affected by this option, just so you know 💀
--auto — enable automated module handling mode on sub-commands that load or unload modulefiles. see also the MODULES_AUTO_HANDLING section.
--color=<WHEN> — colorize the output. WHEN defaults to always, or can be never or auto. see also the MODULES_COLOR section 🌈
--contains, -C — on avail, list, savelist and spider sub-commands, return modules or collections whose fully qualified name contains the search query string.
--debug, -D, -DD — debug mode. causes module to print debugging messages about its progress. multiple -D options increase the debug verbosity. the maximum is 2.
--default, -d — on avail and spider sub-commands, display only the default version of each module name. the default version is the explicitly set default version, or also the implicit default version if the configuration option implicit_default is enabled (see the "Locating Modulefiles" section in the modulefile man page for further details on implicit default version).
--dumpname — report the name of the current implementation of the module command. this option returns Modules for this implementation. the command then terminates without further processing.
--force, -f — okay this one does a LOT, so buckle up 🫶
- on load, unload, switch, load-any, try-load, mod-to-sh and source sub-commands, by-pass any unsatisfied modulefile constraint corresponding to the declared prereq, via requirement and conflict. which means, for instance, that a modulefile will be loaded even if it comes in conflict with another loaded modulefile, or that a modulefile will be unloaded even if it is a requirement of another modulefile.
- on load, ml, mod-to-sh, purge, reload, switch, try-load and unload sub-commands, applies continue-on-error behavior when an error occurs, even if the abort_on_error option is enabled.
- on ml, purge, reload, reset, restore, stash, stashpop, switch and unload sub-commands, unloads the modulefile anyway even if an evaluation error occurs.
- on clear sub-command, skip the confirmation dialog and proceed.
- on purge sub-command, also unload sticky modules and modulefiles that are depended on by non-unloadable modules, except requirements of retained super-sticky modules.
--help, -h — give some helpful usage information, and terminates the command 🫶
--icase, -i — match module specification arguments in a case insensitive manner.
--ignore-cache — ignore module cache.
--ignore-user-rc — skip evaluation of the user-specific module rc file ($HOME/.modulerc).
--indepth — on avail and spider sub-commands, include in the search results the matching modulefiles and directories, and recursively the modulefiles and directories contained in these matching directories.
--json, -j — display avail, list, savelist, search, spider, stashlist and whatis output in JSON format 🎀

more parts coming, bestie — don't go anywhere 💜

--latest, -L — ngl this one is a whole vibe check for avail and spider ✨ it makes them show only the highest numerically sorted version of each module name (peep the Locating Modulefiles section in the modulefile(5) man page for the deets).
--long, -l — gives you the long format for avail, list, savelist, spider and stashlist output. maximum detail, no crumbs 🎀
--no-auto — turns off automated module handling mode on the sub-commands that load or unload modulefiles. See also the MODULES_AUTO_HANDLING section 💅
--no-indepth — on avail and spider, keeps the search results limited to the matching modulefiles and directories found at the depth level expressed by the search query. so like, modulefiles chilling inside directories that are part of the result get excluded 🙈
--no-modulepath-ignore — skips applying modulepath-ignore pattern definitions for the current command execution 🦋 every element of the modulepath directories gets walked through and checked as if no pattern were defined at all.

careful bestie: a modulepath cache file built with patterns applied does not contain the ignored elements — so combine this with the --ignore-cache option to also search elements excluded from the cache file. iykyk 💀

--no-pager, -P — don't pipe message output into a pager. See also the MODULES_PAGINATE section 🌸
--no-redirect — don't send message output to stdout, keep it on stderr. simple as that 💜
--output=LIST, -o LIST — defines the content to report in addition to module names 👑 supported by the avail, list and spider sub-commands on their regular or terse output modes. Accepted values are a LIST of elements to report, separated by the colon character (:). The order of the elements in LIST does not matter, periodt.

Accepted elements in LIST for the avail and spider sub-commands are: modulepath, alias, provided-alias, dirwsym, indesym, sym, tag, key, hidden, variant, variantifspec and via. heads up: the via element is not accepted on terse output mode 🙅‍♀️

Accepted elements in LIST for the list sub-command are: header, idx, variant, alias, indesym, sym, tag, hidden and key.

The order of the elements in LIST does not matter (yes, again, it's that serious). Module names are the only content reported when LIST is set to an empty value.

LIST may be prefixed by a + or - character to indicate respectively to append it to or subtract it from the current configuration option value ✨

See also MODULES_AVAIL_OUTPUT, MODULES_LIST_OUTPUT and MODULES_SPIDER_OUTPUT.

--paginate, -p — pipes all message output into less (or, if set, into the command referred in the MODULES_PAGER variable) if the error output stream is a terminal. See also the MODULES_PAGINATE section 🫶
--redirect — sends message output to stdout instead of stderr. only supported on sh, bash, ksh, zsh and fish shells, so know your shell bestie 💅
--silent, -s — turns off error, warning and informational messages. the actual module command output result is not affected by silent mode, so you still get your stuff 📵
--starts-with, -S — on avail, list, savelist and spider sub-commands, returns modules or collections whose name starts with the search query string. matching from the front only, icon behavior ⭐
--tag=LIST — on load, load-any, switch and try-load sub-commands, applies the LIST of module tags to the loading modulefile 🏷️ LIST corresponds to the concatenation of multiple tags separated by the colon character (:). LIST should not contain tags inherited from modulefile state or from other modulefile commands. If the module is already loaded, tags from LIST are added to the list of tags already applied to this module 💜
--terse, -t — displays avail, list, savelist, spider and stashlist output in short format. minimal, clean, aesthetic 🌸
--timer — prints at the end of the output an evaluation of the total execution time of the module command ⏱️ when mixed with a single or multiple --debug options, it replaces the regular debug messages by reports of the execution time of every internal procedure calls. numbers girlies rise 🔥
--trace, -T — trace mode 🕵️‍♀️ reports details on module searches, resolutions, selections and evaluations in addition to printing verbose messages.
--verbose, -v, -vv — enables verbose messages during module command execution. multiple -v options increase the verbosity level, and the maximum is 2 🗣️
--version, -V — lists the current version of the module command, and then the command terminates without further processing. short and sweet 💖
--width=COLS, -w COLS — sets the width of the output to COLS columns. See also the MODULES_TERM_WIDTH section 📐

🎀 Module Sub-Commands 🎀

`add [options] modulefile...`

See load. that's it, that's the whole thing 💅

`add-any [options] modulefile...`

See load-any 🦋

`aliases [-a]`

Lists all available symbolic version-names and aliases in the current MODULEPATH ✨ all directories in the MODULEPATH are recursively searched in the same manner as for the avail sub-command. Only the symbolic version-names and aliases found in the search are displayed, nothing else, we're being picky 🎀

`append-path [options] variable value...`

Appends value to an environment variable. The variable is a colon, or delimiter, separated list. See append-path in the modulefile(5) man page for the options description and further explanation 👑

lowkey important: when append-path is called as a module sub-command, the reference counter variable — the one that denotes the number of times value has been added to the environment variable — is not updated unless the --duplicates option is set 😭

`apropos [-a] [-j] string`

See search 💜

`avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]`

avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth]
[pattern...]

Lists all available modulefiles in the current MODULEPATH 👑 all directories in the MODULEPATH are recursively searched for files containing the Modules magic cookie 🍪 if a pattern argument is given, then each directory in the MODULEPATH is searched for modulefiles whose pathname, symbolic version-name or alias match pattern in a case insensitive manner by default. pattern may contain wildcard characters 🌟 multiple versions of an application can be supported by creating a subdirectory for the application containing modulefiles for each version.

Symbolic version-names and aliases found in the search are displayed in the result of this sub-command 🦋 symbolic version-names are displayed next to the modulefile they are assigned to, within parenthesis. Aliases are listed in the MODULEPATH section where they have been defined, and to distinguish aliases from modulefiles a @ symbol is added within parenthesis next to their name. Aliases defined through a global or user specific module RC file are listed under the global/user modulerc section 💅

When colored output is enabled and a specific graphical rendition is defined for the module default version, the default symbol is omitted and instead the defined graphical rendition is applied to the relative modulefile 🌈 when colored output is enabled and a specific graphical rendition is defined for a module alias, the @ symbol is omitted, and the defined graphical rendition applies to the module alias name ✨ see the MODULES_COLOR and MODULES_COLORS sections for details on colored output.

Module tags applying to the available modulefiles returned by the avail sub-command are reported along the module name they are associated to (see the Module tags section) 🏷️

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

A Key section is added at the end of the output in case some elements are reported in parentheses or chevrons along a module name, or if some graphical rendition is made over some output elements. This Key section gives hints on the meaning of such elements 🗝️

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

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

When several patterns are provided, all modulefiles matching at least one of these patterns are listed 🙌

`cachebuild [modulepath...]`

Builds the module cache file for the designated modulepaths 🧚 if no argument is provided, the cache file is built for every modulepath currently enabled. Cache file creation is skipped for modulepaths where the user cannot write in 🙈

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

See the Module cache section for more details on the module cache mechanism 💖

`cacheclear`

Deletes the module cache file in every modulepath currently enabled 💀 if the user cannot write in a modulepath directory, cache file deletion is skipped for this modulepath.

See the Module cache section for more details on the module cache mechanism 🌸

`clear [-f]`

Forces the Modules package to believe that no modules are currently loaded 😳 a confirmation is requested if command-line switch -f (or --force) is not passed. The typed confirmation should equal to yes or y in order to proceed 🫶

config is your settings bestie inside modulecmd.tcl 💅 — here’s the mood:

config [--dump-state|name [value]|--reset name]

Ok so config gets and sets modulecmd.tcl options. Pass just an option name and it reports that option’s currently set value; pass no name at all and it reports every existing option. Give it a name and a value and it sets option name to value. If you pass the command-line switch --reset along with a name, it clears the overridden value for that option. 🫶

When a reported option value differs from its default value, you get a little mention telling you whether the overridden value is coming from a command-line switch (cmd-line) or from an environment variable (env-var). When a reported option value is locked and cannot be altered, you get a (locked) mention. If no value is currently set for an option name, the mention <undef> gets reported. 😭

For options whose value is a colon-separated list, value may be prefixed by a + or - character. That means append it to or subtract it from the current option value, respectively. ✨

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

Existing option names are:

abort_on_error — a list of module sub-commands that abort the evaluation sequence when an error is raised by an evaluated module. Evaluations already performed are withdrawn, and remaining modules to evaluate are skipped. 😭 This configuration option can be changed at installation time with the --with-abort-on-error option. The MODULES_ABORT_ON_ERROR environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_ABORT_ON_ERROR description for details.
advanced_version_spec — advanced module version specification to finely select modulefiles. Default value is 1. It can be changed at installation time with the --disable-advanced-version-spec option. The MODULES_ADVANCED_VERSION_SPEC environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_ADVANCED_VERSION_SPEC description for details. 🎀
auto_handling — automated module handling mode. Default value is 1. It can be changed at installation time with the --disable-auto-handling option. The MODULES_AUTO_HANDLING environment variable is defined by the config sub-command when changing this configuration option from its default value. The --auto and --no-auto command-line switches change the value of this configuration option. See MODULES_AUTO_HANDLING description for details. ⭐
avail_indepth — avail sub-command in depth search mode. Default value is 1. It can be changed at installation time with the --disable-avail-indepth option. The MODULES_AVAIL_INDEPTH environment variable is defined by the config sub-command when changing this configuration option from its default value. The --indepth and --no-indepth command-line switches change the value of this configuration option. See MODULES_AVAIL_INDEPTH description for details. 🔥
avail_output — content to report in addition to module names on avail sub-command regular output mode. Default value is modulepath:alias:dirwsym:sym:tag:variantifspec:key. It can be changed at installation time with the --with-avail-output option. The MODULES_AVAIL_OUTPUT environment variable is defined by the config sub-command when changing this configuration option from its default value. The --output/-o command-line switches change the value of this configuration option. See MODULES_AVAIL_OUTPUT description for details. 🌸
avail_terse_output — content to report in addition to module names on avail sub-command terse output mode. Default value is modulepath:alias:dirwsym:sym:tag:variantifspec. It can be changed at installation time with the --with-avail-terse-output option. The MODULES_AVAIL_TERSE_OUTPUT environment variable is defined by the config sub-command when changing this configuration option from its default value. The --output/-o command-line switches change the value of this configuration option. See MODULES_AVAIL_TERSE_OUTPUT description for details. 🦋
cache_buffer_bytes — size of the buffer used when reading or writing cache files. Default value is 32768. Values between 4096 and 1000000 are accepted. The MODULES_CACHE_BUFFER_BYTES environment variable is defined by the config sub-command when changing this configuration option from its default value. 💜
cache_expiry_secs — number of seconds a cache file is considered valid after being generated. Default value is 0. Values between 0 and 31536000 are accepted. The MODULES_CACHE_EXPIRY_SECS environment variable is defined by the config sub-command when changing this configuration option from its default value. 🍓
collection_pin_version — register exact modulefile version in collection. Default value is 0. The MODULES_COLLECTION_PIN_VERSION environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_COLLECTION_PIN_VERSION description for details. 🧚
collection_pin_tag — register full tag list applying to modulefiles in collection. Default value is 0. The MODULES_COLLECTION_PIN_TAG environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_COLLECTION_PIN_TAG description for details. 🎀
collection_target — collection target which is valid for current system. This configuration option is unset by default. The MODULES_COLLECTION_TARGET environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_COLLECTION_TARGET description for details. 🌈
color — colored output mode. Default value is auto. It can be changed at installation time with the --disable-color option. The MODULES_COLOR environment variable is defined by the config sub-command when changing this configuration option from its default value. The --color command-line switches change the value of this configuration option. See MODULES_COLOR description for details. 👑
colors — chosen colors to highlight output items. Default value is hi=1:db=2:tr=2:se=2:er=91:wa=93:me=95:in=94:mp=1;94:di=94:al=96:va=93:sy=95:de=4:cm=92:aL=100:L=90;47:H=2:F=41:nF=31;43:S=46:sS=44:kL=30;48;5;109:W=30;43. It can be changed at installation time with the --with-dark-background-colors or --with-light-background-colors options in conjunction with --with-terminal-background. The MODULES_COLORS environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_COLORS description for details. 💅
conflict_unload — automated unload of conflicting modules when loading a module. This mechanism is part of the automated module handling mode and also requires enablement of the auto_handling configuration option. Default value is 0. It can be changed at installation time with the --enable-conflict-unload option. The MODULES_CONFLICT_UNLOAD environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_CONFLICT_UNLOAD description for details. 💀
contact — modulefile contact address. Default value is root@localhost. The MODULECONTACT environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULECONTACT description for details. 🙈
domainname — command to fetch domain name. Default value is domainname. It can be changed at installation time with the --with-domainname and --with-domainname-opts options. The MODULES_DOMAINNAME environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_DOMAINNAME description for details. 🌟
editor — text editor command to open modulefile with through edit sub-command. Default value is vi. It can be changed at installation time with the --with-editor option. The MODULES_EDITOR environment variable is defined by the config sub-command when changing this configuration option from its default value. See MODULES_EDITOR description for details. 🫶
extended_default — lets you give a partial module version spec, bestie. Slay.

Default is 1. Want to flip it at installation time? That's the --disable-extended-default option. And whenever config changes this from its default value, the MODULES_EXTENDED_DEFAULT environment variable gets defined. Look at the MODULES_EXTENDED_DEFAULT description for the whole tea 💅

extra_siteconfig — one more place to stash your site-specific configuration script. Head to the Site-specific configuration section for the deets.

This one is unset by default. If config changes it away from its default value, it defines the MODULES_SITECONFIG environment variable. The MODULES_SITECONFIG description has the full story ✨

hide_auto_loaded — tags automatically loaded modules as hidden-loaded. Lowkey sneaky, highkey useful 🫶

Default is 0. The MODULES_HIDE_AUTO_LOADED environment variable gets defined by config when this option is changed from its default value.

home — where the Modules package's main directory lives 🏠

Default value is /usr/share/Modules. Change it at installation time with either the --prefix or the --with-moduleshome option. The MODULESHOME environment variable is defined by config when this option is changed from its default value — see the MODULESHOME description for details.

icase — turns on case-insensitive matching.

Default value is search. Change it at installation time with the --with-icase option. The MODULES_ICASE environment variable is defined by config when this is changed from its default value. Oh and the --icase/-i command line switches also change the value of this option 👑

ignore_cache — ignores the module cache. Bye felicia 💀

Default is 0. The MODULES_IGNORE_CACHE environment variable is defined by config when this option is changed from its default value. The --ignore-cache command line switch changes the value of this option.

ignore_cache_subcmds — the list of module sub-commands that ignore the module cache.

Default is an empty list. The MODULES_IGNORE_CACHE_SUBCMDS environment variable is defined by config when this is changed from its default value. See the MODULES_IGNORE_CACHE_SUBCMDS description for details.

ignore_user_rc — skips evaluation of the user-specific module rc file ($HOME/.modulerc). Not me skipping my own rc file 😭

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

ignored_dirs — directories that get ignored when looking for modulefiles.

Default value is CVS RCS SCCS .svn .git .SYNC .sos. Heads up: the value of this option cannot be altered 🔒

implicit_default — sets an implicit default version for modules.

Default value is 1. Change it at installation time with the --disable-implicit-default option. The MODULES_IMPLICIT_DEFAULT environment variable is defined by config when this option is changed from its default value. See the MODULES_IMPLICIT_DEFAULT description for details.

implicit_requirement — implicitly defines a requirement onto modules specified on module commands inside a modulefile.

Default value is 1. Change it at installation time with the --disable-implicit-requirement option. The MODULES_IMPLICIT_REQUIREMENT environment variable is defined by config when this option is changed from its default value. See the MODULES_IMPLICIT_REQUIREMENT description for details ✨

info_extension — treats module extensions as purely informational: no module alias is associated with them.

Default is 0. The MODULES_INFO_EXTENSION environment variable is defined by config when this option is changed from its default value.

init_envvars — the initial values to assign to environment variables right before they get modified for the very first time 🌱

This configuration option is set to an empty value by default. Change it at installation time with the --with-init-envvars option. The MODULES_INIT_ENVVARS environment variable is defined by config when this option is changed from its default value. See the MODULES_INIT_ENVVARS description for details.

linked_envvars — defines links between environment variables so the same value modification applies to each linked variable 🔗

This configuration option is set to an empty value by default. The MODULES_LINKED_ENVVARS environment variable is defined by config when this option is changed from its default value. See the MODULES_LINKED_ENVVARS description for details.

list_output — the content reported in addition to module names in the regular output mode of the list sub-command.

Default value is header:idx:variant:sym:tag:key. Change it at installation time with the --with-list-output option. The MODULES_LIST_OUTPUT environment variable is defined by config when this option is changed from its default value. The --output/-o command line switches change the value of this option. See the MODULES_LIST_OUTPUT description for details 💖

list_terse_output — the content reported in addition to module names in the terse output mode of the list sub-command.

Default value is header. Change it at installation time with the --with-list-terse-output option. The MODULES_LIST_TERSE_OUTPUT environment variable is defined by config when this option is changed from its default value. The --output/-o command line switches change the value of this option. See the MODULES_LIST_TERSE_OUTPUT description for details.

locked_configs — configuration options that cannot be superseded. Every option referred to in the locked_configs value is locked, so its value cannot be altered. It's giving "you shall not pass" 🚪

This configuration option is set to an empty value by default. Change it at installation time with the --with-locked-configs option. And bestie — the value of this option cannot be altered 🔒

logged_events — the list of events to log.

This configuration option is set to an empty value by default. Change it at installation time with the --with-logged-events option. The MODULES_LOGGED_EVENTS environment variable is defined by config when this option is changed from its default value. See the MODULES_LOGGED_EVENTS description for details.

logger — the command used to log messages.

Default value is logger -t modules. Change it at installation time with the --with-logger and --with-logger-opts options. The MODULES_LOGGER environment variable is defined by config when this option is changed from its default value. See the MODULES_LOGGER description for details 🎀

mcookie_check — decides whether the Modules magic cookie (that's the #%Module file signature, iykyk) should be checked to figure out if a file is a modulefile.

Default value is always. The MODULES_MCOOKIE_CHECK environment variable is defined by config when this option is changed from its default value. See the MODULES_MCOOKIE_CHECK description for details.

mcookie_version_check — decides whether the version set in the Modules magic cookie used in a modulefile should be checked against the version of modulecmd.tcl, to determine if the modulefile could be evaluated or not.

Default value is 1. Change it at installation time with the --disable-mcookie-version-check option. The MODULES_MCOOKIE_VERSION_CHECK environment variable is defined by config when this option is changed from its default value. See the MODULES_MCOOKIE_VERSION_CHECK description for details 🔥

ml — defines the ml command at initialization time.

The default is 1 — cute, standard, keep it. Wanna flip it? It can be changed at installation time with the --disable-ml option. And heads up 💅 the config sub-command defines the MODULES_ML environment variable for you whenever you change this configuration option from its default value. Need the full deets? See the MODULES_ML description.

🎀 `modulepath_ignore`

Okay so this one decides whether your modulepath-ignore pattern definitions actually get applied when the search for modulefiles goes down. When it's disabled? Bestie, every single element of the modulepath directories gets walked through and checked as if no pattern were defined at all. No skipping, no shortcuts, no vibes.

Default value is 1. Two things can override that default: the MODULES_MODULEPATH_IGNORE environment variable, or the --no-modulepath-ignore command line switch. Both supersede, iykyk.

🌸 `nearly_forbidden_days`

Sets the number of days a module should be considered nearly forbidden before it actually reaches its expiry date. It's giving "countdown to doom" energy ⏳

Default value is 14. It can be changed at installation time with the --with-nearly-forbidden-days option. The MODULES_NEARLY_FORBIDDEN_DAYS environment variable is defined by the config sub-command when you change this configuration option from its default value. See the MODULES_NEARLY_FORBIDDEN_DAYS description for details.

🦋 `non_exportable_tags`

Prevents the export of the listed tags to modules once loaded. The separator is a colon : — yes, colon, not comma, don't come for me.

This configuration option is set to an empty value by default. The MODULES_NON_EXPORTABLE_TAGS environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_NON_EXPORTABLE_TAGS description for details.

💅 `pager`

The text viewer used to paginate message output. Your scrolling bestie, basically.

Default value is less -eFKRX. It can be changed at installation time with the --with-pager and --with-pager-opts options. The MODULES_PAGER environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_PAGER description for details.

✨ `paginate`

Controls whether or not the output of the module command should get piped into the pager command. Yes/no, pipe or no pipe, that's the whole plot.

Default value is 1. It can be changed at installation time with the --enable-paginate option. The MODULES_PAGINATE environment variable is defined by the config sub-command when changing this configuration option from its default value. Also, the --paginate/-p and --no-pager/-P command line switches change the value of this configuration option. See the MODULES_PAGINATE description for details.

🧚 `path_entry_reorder`

Changes the order of an entry in a path-like environment variable — and this kicks in when a prepend-path, append-path or use target hits a path entry that's already defined in the environment variable. So like, reshuffling the deck instead of duplicating the card 🃏

Default value is 0. It can be changed at installation time with the --enable-path-entry-reorder option. The MODULES_PATH_ENTRY_REORDER environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_PATH_ENTRY_REORDER description for details.

🔒 `protected_envvars`

Prevents any modification of the listed environment variables. Colon : separator, same deal as before. Nobody touches these. Hands off. 🚫

This configuration option is unset by default. The MODULES_PROTECTED_ENVVARS environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_PROTECTED_ENVVARS description for details.

🌈 `quarantine_support`

Defines if code for quarantine mechanism support should be generated in the module shell function definition. Lowkey niche, highkey useful.

Default value is 0. It can be changed at installation time with the --enable-quarantine-support option. The MODULES_QUARANTINE_SUPPORT environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_QUARANTINE_SUPPORT description for details.

🎀 `rcfile`

Location of the global run-command file(s). That's it, that's the whole thing.

This configuration option is unset by default. The MODULERCFILE environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULERCFILE description for details.

💜 `redirect_output`

Controls whether or not the output of the module command should be redirected from stderr to stdout. Moving the stream, not the drama.

Default value is 1. The MODULES_REDIRECT_OUTPUT environment variable is defined by the config sub-command when changing this configuration option from its default value. The --redirect and --no-redirect command line switches change the value of this configuration option. See the MODULES_REDIRECT_OUTPUT description for details.

⭐ `require_via`

Considers a loaded module that enables a modulepath as a requirement for loaded modules stored in that modulepath. Like, you can't be here without your plus-one.

Default value is 0. It can be changed at installation time with the --enable-require-via option. The MODULES_REQUIRE_VIA environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_REQUIRE_VIA description for details.

🫶 `reset_target_state`

Controls the behavior of the reset sub-command. Specifically: whether the environment should be purged (__purge__), or the initial environment (__init__), or a named collection (any other value) should be restored. Pick your fighter 🥊

Default value is __init__. The MODULES_RESET_TARGET_STATE environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_RESET_TARGET_STATE description for details.

🍓 `run_quarantine`

Environment variables to indirectly pass to modulecmd.tcl. Sneaky little handoff, love that for us.

This configuration option is set to an empty value by default. It can be changed at installation time with the --with-quarantine-vars option that sets MODULES_RUN_QUARANTINE. This environment variable is also defined by the config sub-command when changing this configuration option. See the MODULES_RUN_QUARANTINE description for details.

👑 `search_match`

Module search match style. How the search behaves, basically.

Default value is starts_with. It can be changed at installation time with the --with-search-match option. The MODULES_SEARCH_MATCH environment variable is defined by the config sub-command when changing this configuration option from its default value. The --contains and --starts-with command line switches change the value of this configuration option. See the MODULES_SEARCH_MATCH description for details.

🐚 `set_shell_startup`

Ensures the module command definition by setting the shell startup file. Set it and forget it energy fr fr.

Default value is 0. It can be changed at installation time with the --enable-set-shell-startup option. The MODULES_SET_SHELL_STARTUP environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_SET_SHELL_STARTUP description for details.

💀 `shells_with_ksh_fpath`

Ensures the module command is defined in ksh when it's started as a sub-shell from the listed shells. The ksh girlies deserve nice things too.

This configuration option is set to an empty value by default. The MODULES_SHELLS_WITH_KSH_FPATH environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_SHELLS_WITH_KSH_FPATH description for details.

🤫 `silent_shell_debug`

Disablement of the shell debugging property for the module command. It also defines if code to silence the shell debugging property should be generated in the module shell function definition. Quiet mode, but make it structural.

Default value is 0. It can be changed at installation time with the --enable-silent-shell-debug-support option. The MODULES_SILENT_SHELL_DEBUG environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_SILENT_SHELL_DEBUG description for details.

🌸 `siteconfig`

Primary site-specific configuration script location. See the Site-specific configuration section for details.

Default value is /etc/environment-modules/siteconfig.tcl. It can be changed at installation time with the --prefix or --etcdir options. The value of this option cannot be altered. Read that again, bestie — at runtime you do not get to touch it.

🦋 `source_cache`

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

…and its default value is 0. You can change it at installation time with the --enable-source-cache option. The MODULES_SOURCE_CACHE environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_SOURCE_CACHE description for details. 🗂️

spider_indepth — spider sub-command in depth search mode. Default value is 1. It can be changed at installation time with the --disable-spider-indepth option. The MODULES_SPIDER_INDEPTH environment variable is defined by the config sub-command when changing this configuration option from its default value. The --indepth and --no-indepth command line switches change the value of this configuration option. See the MODULES_SPIDER_INDEPTH description for details. 🕷️
spider_output — Content to report in addition to module names on spider sub-command regular output mode. Default value is modulepath:alias:dirwsym:sym:tag:variantifspec:via:key. It can be changed at installation time with the --with-spider-output option. The MODULES_SPIDER_OUTPUT environment variable is defined by the config sub-command when changing this configuration option from its default value. The --output/-o command line switches change the value of this configuration option. See the MODULES_SPIDER_OUTPUT description for details. 🕸️
spider_terse_output — Content to report in addition to module names on spider sub-command terse output mode. Default value is modulepath:alias:dirwsym:sym:tag:variantifspec. It can be changed at installation time with the --with-spider-terse-output option. The MODULES_SPIDER_TERSE_OUTPUT environment variable is defined by the config sub-command when changing this configuration option from its default value. The --output/-o command line switches change the value of this configuration option. See the MODULES_SPIDER_TERSE_OUTPUT description for details. 🕸️
sticky_purge — Error behavior when unloading a sticky or super-sticky module during a module purge. Also applies to modules whose unload is skipped because they are required, directly or indirectly, by a retained sticky or super-sticky module. Raise an error (default) or emit a warning or be silent. It can be changed at installation time with the --with-sticky-purge option. The MODULES_STICKY_PURGE environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_STICKY_PURGE description for details. 🍯
tag_abbrev — Abbreviations to use to report module tags. Default value is auto-loaded=aL:loaded=L:hidden=H:hidden-loaded=H:forbidden=F:nearly-forbidden=nF:sticky=S:super-sticky=sS:keep-loaded=kL:warning=W. It can be changed at installation time with the --with-tag-abbrev option. The MODULES_TAG_ABBREV environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_TAG_ABBREV description for details. 🏷️
tag_color_name — Tags whose name should be colored instead of the module name. This configuration option is set to an empty value by default. It can be changed at installation time with the --with-tag-color-name option. The MODULES_TAG_COLOR_NAME environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_TAG_COLOR_NAME description for details. 🎨
tcl_ext_lib — Modules Tcl extension library location. Default value is @libdir@/libtclenvmodules.so. It can be changed at installation time with the --prefix or --libdir options. The value of this option cannot be altered. 🔒
tcl_linter — Command to check syntax of modulefiles through the lint sub-command. Default value is nagelfar.tcl. It can be changed at installation time with the --with-tcl-linter and --with-tcl-linter-opts options. The MODULES_TCL_LINTER environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_TCL_LINTER description for details. 🧹
term_background — Terminal background color kind. Default value is dark. It can be changed at installation time with the --with-terminal-background option. The MODULES_TERM_BACKGROUND environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_TERM_BACKGROUND description for details. 🌙
term_width — Set the width of the output. Default value is 0. The MODULES_TERM_WIDTH environment variable is defined by the config sub-command when changing this configuration option from its default value. The --width/-w command line switches change the value of this configuration option. See the MODULES_TERM_WIDTH description for details. 📏
unique_name_loaded — Only one module loaded per module name. Default value is 0. It can be changed at installation time with the --enable-unique-name-loaded option. The MODULES_UNIQUE_NAME_LOADED environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_UNIQUE_NAME_LOADED description for details. ☝️
unload_match_order — Unload firstly loaded or lastly loaded module matching request. Default value is returnlast. It can be changed at installation time with the --with-unload-match-order option. The MODULES_UNLOAD_MATCH_ORDER environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_UNLOAD_MATCH_ORDER description for details. ↩️
variant_shortcut — Shortcut characters that could be used to specify or report module variants. This configuration option is set to an empty value by default. It can be changed at installation time with the --with-variant-shortcut option. The MODULES_VARIANT_SHORTCUT environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_VARIANT_SHORTCUT description for details. ✂️
verbosity — Module command verbosity level. Default value is normal. It can be changed at installation time with the --with-verbosity option. The MODULES_VERBOSITY environment variable is defined by the config sub-command when changing this configuration option from its default value. The --debug/-D, --silent/-s, --trace/-T and --verbose/-v command line switches change the value of this configuration option. See the MODULES_VERBOSITY description for details. 🔊
wa_277 — Workaround for Tcsh history issue. Default value is 0. It can be changed at installation time with the --enable-wa-277 option. The MODULES_WA_277 environment variable is defined by the config sub-command when changing this configuration option from its default value. See the MODULES_WA_277 description for details. 🐚

delete [--auto|--no-auto] [-f] modulefile... — See unload. 🗑️

describe [collection] — See saveshow. 📝

disable [collection] — See saverm. 🚫

display modulefile... — Display information about one or more modulefiles. The display sub-command will list the full path of the modulefile and the environment changes the modulefile will make if loaded. (Note: It will not display any environment changes found within conditional statements.) 👀

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

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

edit modulefile — Open modulefile for editing with the text editor command designated by the editor configuration option. ✏️

help [modulefile...] — Print the usage of each sub-command. If an argument is given, print the Module-specific help information for the modulefile. 🆘

like, the modulefile you pass can also be a symbolic modulefile name or a modulefile alias 💫 and it can also flex that specific syntax to finely select a module version (peep the Advanced module version specifiers section below, iykyk).

And bestie, when you pass several modulefiles? They get evaluated sequentially in the specified order. If one modulefile evaluation raises an error, the help sequence just keeps going. resilient queen behavior ✨

`info-loaded` modulefile

Returns the names of currently loaded modules that match the modulefile you passed. If your modulefile doesn't match any loaded modules, you get an empty string back — that's it, that's the whole vibe. See module-info loaded in the modulefile(5) man page for the full explanation 🫶

`initadd` modulefile...

Adds modulefile to the shell's initialization file in the user's home directory 🏠 The startup files it checks (in order, bestie, order matters) are:

C Shell — .modules, .cshrc, .csh_variables and .login
TENEX C Shell — .modules, .tcshrc, .cshrc, .csh_variables and .login
Bourne and Korn Shells — .modules, .profile
GNU Bourne Again Shell — .modules, .bash_profile, .bash_login, .profile and .bashrc
Z Shell — .modules, .zshrc, .zshenv and .zlogin
Friendly Interactive Shell — .modules, .config/fish/config.fish

If a module load line is found in any of these files, the modulefiles are appended to any existing list of modulefiles. The module load line must be located in at least one of the files listed above for any of the init sub-commands to work properly — no load line, no vibes, fr fr. And if the module load line is found in multiple shell initialization files, all of the lines are changed. every last one 💅

`initclear`

Clears all of the modulefiles from the shell's initialization files. clean slate, main character reset 🌸

`initlist`

Lists all of the modulefiles loaded from the shell's initialization file 👑

`initprepend` modulefile...

Does the same as initadd but prepends the given modules to the beginning of the list. front of the line energy 🎀

`initrm` modulefile...

Removes modulefile from the shell's initialization files. bye bestie 💜

`initswitch` modulefile1 modulefile2

Switches modulefile1 with modulefile2 in the shell's initialization files. the swap is real 🔁

`is-avail` modulefile...

Returns a true value if any of the listed modulefiles exists in the enabled MODULEPATH. Returns a false value otherwise. See is-avail in the modulefile(5) man page for further explanation 🦋

The modulefile parameter may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

`is-loaded` [modulefile...]

Returns a true value if any of the listed modulefiles has been loaded — or if any modulefile is loaded in case no argument is provided. Returns a false value otherwise. See is-loaded in the modulefile(5) man page for further explanation ⭐

`is-saved` [collection...]

Returns a true value if any of the listed collections exists — or if any collection exists in case no argument is provided. Returns a false value otherwise. See is-saved in the modulefile(5) man page for further explanation 🍓

`is-used` [directory...]

Returns a true value if any of the listed directories has been enabled in MODULEPATH — or if any directory is enabled in case no argument is provided. Returns a false value otherwise. See is-used in the modulefile(5) man page for further explanation 🌈

`keyword` [`-a`] [`-j`] string

See search. that's the whole entry, go look at search bestie 👀

`lint` [`-a`] [modulefile...]

Analyzes the syntax of one or more modulefiles with the linter command designated by the tcl_linter configuration option 🧚

If no modulefile is specified, all the modulefiles and modulerc available in enabled modulepaths are analyzed as well as global rc, user rc and modulecache files. Hidden modulefiles are also analyzed when the --all/-a option is set. so thorough, we love an overachiever 💖

When nagelfar.tcl is the selected linter command, a static Tcl syntax analysis is performed. In addition, syntax of modulefile commands are checked in these files based on their kind (global/user rc, modulerc, modulecache or modulefile). it's giving full audit 🔥

`list` [`-t`|`-l`|`-j`] [`-a`] [`-o` LIST] [`-S`|`-C`] [pattern...]

Lists loaded modules. If a pattern is given, then the loaded modules are filtered to only list those whose name matches this pattern. It may contain wildcard characters 🌟 pattern is matched in a case insensitive manner by default. If multiple patterns are given, a loaded module has to match at least one of them to be listed.

Module tags applying to the loaded modules are reported along the module name they are associated to (see Module tags section).

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

A Key section is added at the end of the output in case some elements are reported in parentheses or chevrons along module name, or if some graphical rendition is made over some output elements. This Key section gives hints on the meaning of such elements. cute lil decoder ring 🔑✨

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

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

`load` [options] modulefile...

Loads modulefile into the shell environment 🚀

The load command accepts the following options:

--auto|--no-auto
-f|--force
--tag=taglist

Once loaded, the loaded module tag is associated to the loaded module. If the module has been automatically loaded by another module, the auto-loaded tag is associated instead (see Module tags section).

When several modulefiles are passed, they are loaded sequentially in the specified order. If one modulefile evaluation raises an error, the load sequence continues: loaded modules prior the evaluation error are kept loaded and the sequence is resumed with the load of remaining modulefile in list. Conversely, the load sequence is aborted and already loaded modulefiles are withdrawn if load sub-command is defined in abort_on_error configuration option and the --force option is not set. okay so that's the scary part — read it twice, bestie 😭

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

`load-any` [options] modulefile...

Loads into the shell environment one of the modulefile specified. It tries to load each modulefile specified in list from the left to the right until one got loaded or is found already loaded. Do not complain if modulefile cannot be found 🫶 But if its evaluation fails, an error is reported and the next modulefile in list is evaluated.

The load-any command accepts the following options:

--auto|--no-auto
-f|--force
--tag=taglist

`mod-to-sh` [options] shell modulefile...

Evaluates modulefile and reports the resulting environment changes as code for shell 🐚

The mod-to-sh command accepts the following options:

--auto|--no-auto
-f|--force

An attempt to load modulefile is made to get its environment changes. This evaluation does not change the current shell environment. Like for the load sub-command, no evaluation occurs if modulefile is found loaded in the current environment.

Changes made on environment variable intended for Modules private use (e.g., LOADEDMODULES, _LMFILES_, __MODULES_*) are ignored. hands off the private stuff 🚫

shell could be any shell name supported by modulecmd.tcl.

Produced shell code is returned on the message output channel by modulecmd.tcl. Thus it is not rendered in the current environment by the module shell function.

mod-to-sh automatically sets verbosity to the silent mode, to avoid messages mixing with the produced shell code. Verbosity is not changed if set to the trace mode or any higher debugging level. so don't come crying about missing output, it's silent mode for a reason 🌸

When you pass a bunch of modulefiles all at once, bestie, they get evaluated sequentially, in the exact order you gave them. ✨ And if one of those evaluations throws an error, the mod-to-sh sequence keeps going — environment changes from the modules that were evaluated before the error are preserved, and the sequence picks right back up with the next modulefile in the list. But flip side, the mod-to-sh sequence gets aborted and the changes from already-evaluated modules get withdrawn if mod-to-sh sub-command is defined in the abort_on_error configuration option and the --force option is not set. 💅

🦋 `path` modulefile

Prints the path to modulefile. Simple, iconic, does what it says. 🎀

The modulefile parameter can also be a symbolic modulefile name or a modulefile alias. It can also flex a specific syntax to finely select a module version — check the Advanced module version specifiers section below for that one, iykyk. 👀

🎀 `paths` pattern

Prints the path of the available modulefiles that match pattern. 🗂️

The pattern parameter can also be a symbolic modulefile name or a modulefile alias, and it can also use that same specific syntax to finely select a module version (again: Advanced module version specifiers section below).

Now this part is highkey important: if pattern contains a variant specification or an Extra specifier, the Extra match search process gets triggered to collect the command information used in modulefiles. Modules only make it into the results if they match the pattern variant specification and the extra specifier. And pattern is allowed to be a bare variant specification or a bare extra specifier, with no module name mentioned at all. 🤯

💖 `prepend-path` [options] variable value...

Prepends value to an environment variable. The variable here is a colon, or delimiter, separated list. 🧵

See prepend-path in the modulefile(5) man page for the options description and the whole further explanation situation.

One little gotcha when prepend-path is called as a module sub-command: the reference counter variable — the one that denotes how many times value has been added to the environment variable — is not updated, unless the --duplicates option is set. Noted. 📝

🔥 `purge` [`-f`]

Unloads all loaded modulefiles. Just, like, all of them. 🧹

Sticky and super-sticky modules are kept loaded, along with their required modules, including the indirect requirements. Unload attempts for these modules get skipped according to the sticky_purge configuration: either raise an error (that's the default), emit a warning, or remain silent. 🙈

When the --force option is set, it also unloads sticky modules, modulefiles that are depended by non-unloadable modules, and modulefiles raising an evaluation error. Super-sticky modules and their requirements stay loaded even with --force — no cap, they're not going anywhere. 👑

And if one modulefile unload evaluation raises an error, the purge sequence continues: the modules unloaded before the evaluation error stay unloaded, and the sequence resumes with the unload of the remaining modulefiles. Conversely, the purge sequence is aborted and already-unloaded modulefiles get restored if purge sub-command is defined in the abort_on_error configuration option and the --force option is not set. 💀

⭐ `refresh`

Forces a refresh of all the non-persistent components of the modules you currently have loaded. 🌈

Use this on derived shells where shell completions, shell aliases, or shell functions need to be reinitialized, but the environment variables have already been set by the currently loaded modules. Like, the vibes need re-syncing but the data's already there, y'know?

Loaded modules get evaluated in refresh mode following their load order. In this evaluation mode, only four modulefile commands will produce environment changes: complete, set-alias, set-function, and puts. Everything else that normally produces environment changes (think setenv or append-path) gets ignored during a refresh evaluation, because their changes should already be applied. ✨

Only the loaded modules that define non-persistent environment changes get evaluated in refresh mode. Those loaded modules are listed in the __MODULES_LMREFRESH environment variable. 🫶

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

🌸 `reload` [`-f`]

Unloads, then loads, all loaded modulefiles. The classic "turn it off and on again" but for modules. 🔄

No unload-then-load is performed, and an error is returned, if the loaded modulefiles have an unsatisfied constraint corresponding to the prereq and conflict they declare. Nope, not doing that. 🙅

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

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

🧚 `remove` [`--auto`|`--no-auto`] [`-f`] modulefile...

See unload. 🫡

🍓 `remove-path` [options] variable value...

Removes value from the colon, or delimiter, separated list in the environment variable. See remove-path in the modulefile(5) man page for the options description and the further explanation.

When remove-path is called as a module sub-command, the reference counter variable — the one denoting the number of times value has been added to the environment variable — is ignored, and value gets removed whatever the reference counter value is set to. Yeah, it just goes. ✂️

💜 `reset` [`-f`]

Restores the initial environment, which corresponds to the loaded state right after Modules initialization. 🕰️

The reset sub-command restores the environment definition found in the __MODULES_LMINIT environment variable.

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

The reset behavior can be changed with reset_target_state. That configuration option is set by default to __init__, which corresponds to the whole behavior description above. When it's set to __purge__, reset performs a purge of the environment. When it's set to any other value, reset performs a restore of the corresponding name collection. 🎚️

🌟 `restore` [`-f`] [collection]

Restores the environment state as defined in collection. 🪄

If collection name is not specified, then it's assumed to be the default collection if it exists, and the __init__ special collection otherwise. If collection is a fully qualified path, it gets restored from this location rather than from a file under the user's collection directory. And if MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable is appended to the collection file name to restore. 🏷️

If the collection name is __init__, the initial environment state defined in the __MODULES_LMINIT environment variable gets restored.

Okay, this next bit is the main character of the whole operation: when restoring a collection, the currently set MODULEPATH directory list and the currently loaded modulefiles are unused and unloaded, then used and loaded to exactly match the MODULEPATH and loaded modulefiles lists saved in this collection file. The order of the paths and modulefiles set in the collection is preserved when restoring. Which means: currently loaded modules get unloaded to get the same LOADEDMODULES root as the collection, and currently used module paths get unused to get the same MODULEPATH root. Then the missing module paths get used and the missing modulefiles get loaded. 🧩

Heads up though 🙈: if a module, with no default version explicitly defined, is recorded in a collection by its bare name, then loading this module when restoring the collection will fail if the configuration option implicit_default is disabled. Just so you know.

If one modulefile load or unload evaluation raises an error, the restore sequence continues: environment changes from the modules unloaded or loaded before the evaluation error are preserved, and the sequence resumes with the unload or load of the remaining modulefiles. 💫

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

🎀 `rm` [`--auto`|`--no-auto`] [`-f`] modulefile...

See unload. 🫶

👑 `save` [collection]

Records the currently set MODULEPATH directory list and the currently loaded modulefiles into a collection file under the user's collection directory $HOME/.module. 📦

If collection name is not specified, then it's assumed to be the default collection. If collection is a fully qualified path, it gets saved at this location rather than under the user's collection directory.

If MODULES_COLLECTION_TARGET is set, a suffix equivalent to the value of this variable will be appended to the collection file name.

By default, if a loaded modulefile corresponds to the explicitly defined default module version, the bare module name is recorded. If the configuration option implicit_default is enabled, the bare module name is also recorded for the implicit default module version. And if MODULES_COLLECTION_PIN_VERSION is set to 1, the module version is always recorded, even if it's the default version. 📌

Also by default, only the module tags specifically set with the --tag option, or resulting from a specific module state (like auto-loaded and keep-loaded tags), are recorded in the collection. If MODULES_COLLECTION_PIN_TAG is set to 1, all tags get recorded in the collection, except the nearly-forbidden tag. 🏷️

And no collection is recorded, plus an error is returned, if the loaded modulefiles have an unsatisfied constraint corresponding to the prereq and conflict they declare. 🚫

🦋 `savelist` [`-t`|`-l`|`-j`] [`-a`] [`-S`|`-C`] [pattern...]

Lists the collections that are currently saved under the user's collection directory. 📚

If MODULES_COLLECTION_TARGET is set, only the collections matching the target suffix will be displayed, unless the --all/-a option is set. 💅

If you pass it a pattern, the collections get filtered down so we only list the ones whose name matches — and yeah, pattern can have wildcard characters in it, and matching is case insensitive by default. Give it multiple patterns and a collection only has to match at least one of them to show up. 🎀

Oh and heads up bestie — stash collections do not get listed unless the --all/-a option is set. You can list those separately with the stashlist sub-command. 💅

`saverm` [collection]

Deletes the collection file sitting under your user's collection directory. Don't name a collection? Then it just assumes the default collection. And if MODULES_COLLECTION_TARGET is set, a suffix equal to that variable's value gets appended to the collection file name. 🗑️

`saveshow` [collection]

Shows you what's inside collection. If you don't name one, it assumes the default collection if it exists — otherwise it goes with the __init__ special collection. If collection is a fully qualified path, then it displays that location instead of a collection file under your user's collection directory. If MODULES_COLLECTION_TARGET is set, a suffix equal to that variable's value gets appended to the collection file name. ✨

If collection is __init__, the initial environment content defined in the __MODULES_LMINIT environment variable is what gets displayed.

`search [-a] [-j] string`

Digs through the module-whatis <#mfcmd-module-whatis> info of all the modulefiles looking for string. Every bit of module-whatis info that matches string in a case insensitive manner gets displayed. And string may contain wildcard characters. 🔍

`sh-to-mod shell script [arg...]`

Okay this one is genuinely iconic. It evaluates script with shell, with the arguments you defined, to find out what environment changes it makes. Then it compares the environment before and after the evaluation to figure those changes out, translates them into modulefile commands, and outputs modulefile content equivalent to the evaluation of script. 🧚

What gets tracked:

environment variables
shell aliases
shell functions
shell completions
the current working directory

Changes made on environment variables intended for Modules private use (like LOADEDMODULES, _LMFILES_, __MODULES_*) are ignored, periodt.

shell can be given as a command name or a fully qualified pathname. The supported shells are: sh, dash, csh, tcsh, bash, ksh, ksh93, zsh and fish. 🌈

You can also set shell to bash-eval — in that mode the bash shell script isn't sourced, but the output resulting from its execution gets evaluated to determine the environment changes it makes.

Note

shell runs in non-interactive mode without loading any shell configuration or profile. So basically your script has no access to transient definitions that only exist in interactive sessions or profile files — things like shell aliases, functions, or completion settings. 😭

`show modulefile...`

See display.

`source [options] modulefile...`

Runs modulefile into the shell environment. But here's the twist — once executed, modulefile is not marked as loaded in the shell environment, which is the whole difference from the load sub-command. 🙈

The source command accepts these options:

--auto|--no-auto
-f|--force

If modulefile corresponds to a fully qualified path, that file gets executed. Otherwise modulefile gets searched among the available modulefiles.

The modulefile parameter can also be a symbolic modulefile name or a modulefile alias. It can also leverage a specific syntax to finely select module version (see Advanced module version specifiers section below).

When you pass several modulefiles, they're evaluated sequentially in the order you gave them. If one modulefile evaluation raises an error, the source sequence continues: environment changes from modules sourced before the evaluation error are preserved, and the sequence resumes with the source of the remaining modulefile in the list. 💪

`spider [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]`

spider [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C]
[--indepth|--no-indepth] [pattern...]

Lists all available modulefiles found in enabled modulepaths — plus the ones recursively found in modulepaths enabled by available modulefiles. 🕷️✨

spider starts off by performing an Extra match search to get all the modulepaths to look at. These modulepaths are collected from the directory arguments set to the module use <#mfcmd-module> command, the append-path MODULEPATH <#mfcmd-append-path> command, or the prepend-path MODULEPATH <#mfcmd-prepend-path> modulefile command. Collecting modulepaths happens first in the global/user rc section, then in modulepaths defined in MODULEPATH, then in each modulepath collected from modulefiles, and so on and so on. And since collecting modulepaths means evaluating every available modulefile, it's advised to build and use Module cache to speed up the search. ⚡

Once the modulepaths are gathered, spider proceeds and reports like the avail sub-command. Same set of options supported, no cap.

If a pattern argument is given, then each collected modulepath gets searched for modulefiles whose pathname, symbolic version-name or alias matches pattern — case insensitive by default. pattern may contain wildcard characters.

Symbolic version-names and aliases found in the search show up in the result of this sub-command. Symbolic version-names appear next to the modulefile they're assigned to, within parenthesis. Aliases get listed in the modulepath section where they've been defined — and to distinguish aliases from modulefiles, a @ symbol is added within parenthesis next to their name. Aliases defined through a global or user specific module RC file are listed under the global/user modulerc section. 🎀

When colored output is enabled and a specific graphical rendition is defined for the module default version, the default symbol is omitted and the defined graphical rendition is applied to the relative modulefile instead. When colored output is enabled and a specific graphical rendition is defined for a module alias, the @ symbol is omitted and the defined graphical rendition applies to the module alias name. See the MODULES_COLOR and MODULES_COLORS sections for the details on colored output. 🌸

Module tags applying to the available modulefiles returned by the spider sub-command are reported along the module name they're associated to (see Module tags section).

Module variants and their available values may be reported along the module name they belong to (see Module variants section) — but only if they're defined in the spider output configuration option (see --output/-o option). The Extra match search process gets triggered to collect that variant info.

A Key section gets added at the end of the output in case some elements are reported in parentheses or chevrons along a module name, or if some graphical rendition is made over some output elements. That Key section hands you the hints on what those elements mean. 🔑

If pattern contains a variant specification or Extra specifier, the Extra match search process is triggered to collect command information used in modulefiles. Modules are included in the results only if they match the pattern variant specification and extra specifier. And pattern may be a bare variant specification or extra specifier without mentioning a module name at all. 👑

When you give several patterns, all modulefiles matching at least one of those patterns get listed.

`stash [-f]`

Saves the current environment into a stash collection, then resets to the initial environment. 🫶

A collection is only created if the current environment state differs from the initial environment. The stash collection is named stash-<unix_millis_timestamp> where <unix_millis_timestamp> is the number of milliseconds between the Unix Epoch and when this command runs.

If MODULES_COLLECTION_TARGET is set, a suffix equal to that variable's value gets appended to the stash collection file name.

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

`stashclear`

Removes all the stash collection files of the current collection_target. If no collection target is currently set, it removes stash collection files without a target suffix. 💀

`stashlist [-t|-l|-j]`

Lists all the stash collection files of the current collection_target. If no collection target is currently set, it lists stash collection files without a target suffix. 📋

`stashpop [-f] [stash]`

Restores the stash collection, then deletes the corresponding collection file. 🎁

stash is either a full stash collection name (i.e. stash-<unix_millis_timestamp>) or a stash index. The most recent stash collection has index 0, and 1 is the one before it. When no stash is given, the latest stash collection is assumed (that is, stash index 0).

If MODULES_COLLECTION_TARGET is set, a suffix equal to that variable's value gets appended to the stash collection file name to restore.

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

`stashrm [stash]`

Removes a stash collection file. 🗑️

stash is either a full stash collection name (i.e. stash-<unix_millis_timestamp>) or a stash index. The most recent stash collection has index 0, 1 is the one before it. When no stash is given, the latest stash collection is assumed (that is, stash index 0).

If MODULES_COLLECTION_TARGET is set, a suffix equal to that variable's value gets appended to the stash collection file name to delete.

`stashshow [stash]`

Displays the content of the stash collection file. 👀

Okay so stash is either a full stash collection name (like stash-<unix_millis_timestamp>) or a stash index. The most recent stash collection is index 0, and 1 is the one right before it. When you don't hand over any stash at all, the latest stash collection is assumed — yeah, that's stash index 0, bestie.

If MODULES_COLLECTION_TARGET is set, a suffix equal to the value of that variable gets appended to the stash collection file name for display. cute little label moment ✨

state [name] — grabs modulecmd.tcl states for you 🫶. It reports the currently set value of the state name you pass, or literally all the existing states if you pass no name at all.
swap [options] [modulefile1] modulefile2 — see switch. that's it, that's the whole vibe 💅
switch [options] [modulefile1] modulefile2 — swaps a loaded modulefile1 out for modulefile2 🔁. If you don't specify modulefile1, it's assumed to be the currently loaded module that shares the same root name as modulefile2. And "root name" means the initial part of a module name — i.e., all characters preceding the first /. periodt.

switch accepts these options, no cap:

--auto|--no-auto
-f|--force
--tag=taglist

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias 👑. It may also leverage a specific syntax to finely select a module version (peep the Advanced module version specifiers section below, iykyk).

The --tag option accepts a list of module tags to apply to modulefile once it's loaded. If the module is already loaded, the tags from taglist get added to the list of tags already applied to this module. stacking tags like accessories, honestly iconic 🎀

When the --force option is set, modulefiles get unloaded anyway even if an evaluation error occurs. stubborn queen behaviour, respect.

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

If the load evaluation of modulefile2 raises an error, the switch sequence continues: environment changes from the modulefile1 unload are applied, but not those from the failed modulefile2 load. Conversely, the whole switch sequence is aborted and the unloaded modulefile1 is restored if the switch sub-command is defined in the abort_on_error configuration option and the --force option is not set. it's giving "we tried, we're putting it back" 🙈

test modulefile... — executes and displays the results of the Module-specific tests for the modulefile 🧪. very main character of it.

The parameter modulefile may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select a module version (see the Advanced module version specifiers section below).

When several modulefiles are passed, they get evaluated sequentially in the specified order. If one modulefile evaluation raises an error, the test sequence continues — lowkey resilient ✨.

try-add [options] modulefile... — see try-load. same energy, different name 🦋
try-load [options] modulefile... — like the load sub-command, it loads modulefile into the shell environment, but it does not complain if modulefile cannot be found 🙌. If modulefile is found but its evaluation fails, the error is still reported. soft launch of the load command, honestly.

try-load accepts these options:

--auto|--no-auto
-f|--force
--tag=taglist

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

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

unload [--auto|--no-auto] [-f] modulefile... — removes modulefile from the shell environment. bye bestie, you're uninvited 🫶

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

When several modulefiles are passed, they're unloaded sequentially in the specified order. If one modulefile evaluation raises an error, the unload sequence continues: modules unloaded prior to the evaluation error stay unloaded and the sequence is resumed with the unload of the remaining modulefile in the list. Conversely, the unload sequence is aborted and the already unloaded modulefiles are restored if the unload sub-command is defined in the abort_on_error configuration option and the --force option is not set.

unuse directory... — removes one or more directories from the MODULEPATH environment variable 🧹.

If module unuse <#mfcmd-module> is called during a modulefile evaluation, the reference counter environment variable __MODULES_SHARE_MODULEPATH — which denotes the number of times directory has been enabled — is checked, and directory is removed only if its relative counter is equal to 1 or not defined. Otherwise directory is kept and the reference counter is decreased by 1. When module unuse is called from the command-line or within an initialization modulefile script, directory is removed whatever the reference counter value set is. math girlies rise 😤

If directory corresponds to the concatenation of multiple paths separated by the colon character, each path is treated separately.

update [-f] — see reload. go look, bestie 👀
use [-a|--append|-p|--prepend] directory... — prepends one or more directories to the MODULEPATH environment variable ✨. The --append/-a flag appends the directory to MODULEPATH instead. The --prepend/-p flag explicitly requests the default prepend behaviour. front of the line energy 👑

When directory is already defined in MODULEPATH, it is not added again and it is not moved to the end or the beginning of the environment variable. no reshuffling, no drama.

If module use <#mfcmd-module> is called during a modulefile evaluation, the reference counter environment variable __MODULES_SHARE_MODULEPATH is also set to increase the number of times directory has been added to MODULEPATH. The reference counter is not updated when module use is called from the command-line or within an initialization modulefile script.

A directory that does not exist yet can be specified as an argument and then be added to MODULEPATH. manifesting it into existence 🦋

whatis [-a] [-j] [pattern...] — displays the information set up by the module-whatis <#mfcmd-module-whatis> commands inside modulefiles matching pattern 🔍. pattern may contain wildcard characters. If no pattern is specified, all module-whatis lines will be shown. the full lore dump, basically.

The parameter pattern may also be a symbolic modulefile name or a modulefile alias. It may also leverage a specific syntax to finely select a module version (see the Advanced module version specifiers section below).

If pattern contains a variant specification or an Extra specifier, the Extra match search process is triggered to collect command information used in modulefiles 👀. Modules are included in the results only if they match the pattern variant specification and extra specifier. pattern may be a bare variant specification or extra specifier without mentioning a module name at all. matching on vibes alone, honestly iconic.

🌸 MODULEFILES 🌸

Modulefiles are written in the Tool Command Language (Tcl) and are interpreted by modulecmd.tcl. modulefiles can use conditional statements 🧠. So the effect a modulefile will have on the environment may change depending on the current state of the environment. it's giving adaptive, it's giving context-aware.

Environment variables are unset when unloading a modulefile ⚠️. So yeah — it's totally possible to load a modulefile and then unload it without having the environment variables return to their prior state. no takebacks, bestie, the variables just leave 💀

✨ ADVANCED MODULE VERSION SPECIFIERS ✨

When the advanced module version specifiers mechanism is enabled (see MODULES_ADVANCED_VERSION_SPEC), the specification of modulefile passed on Modules sub-commands changes 🎀. After the module name, a version constraint and variants may be added. fancy detailing unlocked.

⭐ VERSION SPECIFIERS ⭐

After the module name, a version constraint prefixed by the @ character may be added. It could be directly appended to the module name or separated from it with a space character. both work, no gatekeeping 💅

Constraints can be expressed to refine the selection of module version to:

a single version with the @version syntax — for instance, foo@1.2.3 will select module foo/1.2.3 ⭐
a list of versions with the @version1,version2,... syntax — for instance, foo@1.2.3,1.10 will match modules foo/1.2.3 and foo/1.10 🍓
a range of versions with the @version1:, @:version2 and @version1:version2 syntaxes — for instance, foo@1.2: will select all versions of module foo greater than or equal to 1.2, foo@:1.3 will select all versions less than or equal to 1.3, and foo@1.2:1.3 matches all versions between 1.2 and 1.3 including the 1.2 and 1.3 versions themselves 🌈. inclusive queen.

okay so, advanced spec of a single version or a whole list of versions? lowkey you might wanna turn on the extended default mechanism (peep MODULES_EXTENDED_DEFAULT) so you can use the abbreviated notation like @1 to point at way more precise version numbers like 1.2.3. the characters . and - count as version number separators when it's figuring out abbreviated versions. ranges of versions, on the other hand, handle abbreviated versions natively, no extra config needed. and bestie, the upper bound can be less precise than the lower bound — an abbreviated upper bound grabs every version that extends it, as long as those versions also satisfy the lower bound. 🫶

so for a version to be specifiable in a range of versions, or comparable to a range of versions, its major element has to correspond to a number. like 10a, 1.2.3, 1.foo — those are all valid for range comparison. but default or foo.2? nope, invalid for range comparison, sorry babe. 💀

ranges of versions can totally live inside a version list, for example foo@:1.2,1.4:1.6,1.8:. it's giving exclusion era — that spec is how you exclude specific versions, like versions 1.3 and 1.7 in the example above. iconic.

if the implicit default mechanism is also enabled (see MODULES_IMPLICIT_DEFAULT), then default and latest symbolic versions get automatically defined for each module name — and also at each directory level for deep modulefiles. ✨ these automatic version symbols get defined unless a symbolic version, alias, or regular module version already exists for those default or latest version names. using the mod@latest (or mod/latest) syntax guarantees the highest available version gets selected. no cap. 👑

the symbolic version loaded can be used over a loaded module name to designate the loaded version of that module, with its associated selected variants. it's specified with the @ prefix notation (e.g., foo@loaded). and if no version of the designated module is currently loaded? error. returned. immediately. 😭

✨ Variants ✨

after the module name you can specify variants. module variants are alternative evaluation of the same modulefile, k? a variant gets specified by associating a value to its name. that specification then gets transmitted to the evaluating modulefile, which instantiates the variant in the ModuleVariant array variable right when it reaches the variant modulefile command that declares this variant. 🦋

variant can be specified with the name=value syntax, where name is the declared variant name and value is the value this variant is set to when evaluating the modulefile.

boolean variants can be specified with the +name syntax to set the variant on, and with the -name or ~name syntaxes to set it off. careful though — the -name syntax is not supported on the ml command, because the minus sign already means "unload the designated module". rude, I know. the ~name and +name syntaxes can also be defined appended to another specification word (e.g., the module name, version or another variant specification), whereas the -name syntax must be the start of a new specification word. 🎀

boolean variants may also be specified with the name=value syntax. set value to 1, true, t, yes, y or on to enable the variant, or set it to 0, false, f, no, n or off to disable it. simple as. ✅

shortcuts may be used to abbreviate variant specification — the variant_shortcut configuration option associates a shortcut character to a variant name. with a shortcut defined, the variant can be specified with the <shortcut>value syntax. for instance, if the character % is set as a shortcut for variant foo, then the %value syntax is equivalent to the foo=value syntax. obsessed. 💅

a variant shortcut must be exactly one character long, and it must avoid characters used for other concerns or in module names or version specifications (i.e., [-+~/@=:,a-zA-Z0-9]). them's the rules.

variant name should only be composed of characters that are part of the A-Za-z0-9_- range. also, a variant name cannot start with the - (minus) character, and the overall name cannot just be a number.

specific characters used in the variant specification syntax cannot be used as part of the name or version of a module. these specific characters are +, ~, = and all characters set as variant shortcut. exception tho!! an exception is made for the + and ~ characters if the string that follows after does not correspond to a valid variant name (e.g., name+, name++, name/version+1). 🙈

🔍 Extra specifier 🔍

after the module name, extra specifiers can be defined in module search context. extra specifiers are basically an extra query to list available modulefiles based on their content definition. they rely on the Extra match search mechanism, which collects the content of available modulefiles. 🕵️‍♀️

an extra specifier can be set with the element:name[,name,...] syntax, where element is a Tcl modulefile command and name is an item defined by that command. depending on the kind of Tcl modulefile command, name can refer to an environment variable, a shell alias, a module specification, etc.

supported extra specifier elements are:

variant, complete, uncomplete, set-alias, unset-alias, set-function, unset-function, chdir, tag
setenv, unsetenv, append-path, prepend-path, remove-path and pushenv: these elements related to environment variable handling may also be aliased envvar
family and provide: these elements related to module alias may also be aliases provided-alias
prereq, prereq-any, prereq-all, depends-on, depends-on-any, always-load, load, load-any, try-load, switch and switch-on: these elements related to module requirement definition accept a module specification as value name and may be aliased require
conflict, unload, switch and switch-off: these elements related to module incompatibility definition accept a module specification as value name and may be aliased incompat
use

each of the above supported elements corresponds to a Tcl modulefile command. load, load-any, try-load, switch, unload and use match corresponding module sub-commands. prereq-any is an alias on prereq, and depends-on-any and vice versa, since both Tcl modulefile commands are the same. following the same trend, prereq-all is an alias on depends-on and vice versa. regarding switch-off and switch-on elements, they correspond respectively to the module to unload (if specified) and the module to load on a module switch command. switch is an alias that matches both switch-off and switch-on elements. require and incompat elements do not match module commands where the --not-req option is set. setting the MODULEPATH environment variable with append-path or prepend-path commands can be queried with the use element. 💡

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

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

when an extra specifier is prefixed by not: (e.g., not:env:PATH), it acts as a NOT operation. which means the modules listed in the result are those not matching the extra specifier defined. periodt.

module specification used as the name value for some extra specifier elements may leverage the Advanced module version specifiers syntax. however — if a module version range or list is implied, it is currently resolved to existing modules. thus it may not match modulefile definitions targeting modules that do not exist. on top of that, module aliases and symbolic versions are not resolved to their target either, whether they're set in the extra specifier query or in the modulefile definition. 😬

extra specifier can only be set in a module search context (the avail, spider, whatis and paths sub-commands). an error is raised if it's used on a module specification query in another context. an error is also raised if an unknown extra specifier element is defined in the search query. so like… don't try it. 💀

🏷️ Module tags 🏷️

module tags are pieces of information that can be associated to individual modulefiles. tags could be purely informational, or they may lead to specific behaviors. 🎀

module tags may be inherited from the module state set by a modulefile command, or be a consequence of a module action. the inherited tags are:

auto-loaded: the module has been automatically loaded by another module
forbidden: the module has been set forbidden through the use of the module-forbid command, and thus this module cannot be loaded
hidden: the module has been set hidden through the use of the module-hide command, and thus it is not reported by default among the result of avail or spider sub-commands
hidden-loaded: the module has been set hidden once loaded through the use of the module-hide --hidden-loaded command, thus it is not reported by default among the result of a list sub-command
loaded: the module is currently loaded
nearly-forbidden: the module will soon be forbidden, which has been set through the use of the module-forbid command. thus this module will soon not be able to load anymore
warning: a warning message for the use of the module is set through the use of the module-warn command

tags may also be associated to modules by using the module-tag modulefile command. among the tags that could be set this way, some have a special meaning: 👑

keep-loaded: an auto-loaded module cannot be automatically unloaded. this tag is also set through the use of the always-load command
sticky: the module, once loaded, cannot be unloaded unless forced or reloaded (see the Sticky modules section)
super-sticky: the module, once loaded, cannot be unloaded unless reloaded — the module cannot be unloaded even if forced (see the Sticky modules section)

the --tag option helps apply additional tags to modules. it's available on the load, load-any, switch and try-load sub-commands, and on the always-load, depends-on, depends-on-any, module, prereq, prereq-all and prereq-any modulefile commands. in case the designated module is already loaded, the additional tags get added to the list of tags already applied to this module. 🫶

module tags are reported right along the module they're associated to on avail, list and spider sub-command results, and also when the module's loading, unloading, refreshing or tagging evaluation is mentioned. tags could be reported either:

along the module name, with all tags set within angle brackets, each tag separated from the others with a colon character (e.g., foo/1.2 <tag1:tag2>)
graphically rendered over the module name for each tag associated to a Select Graphic Rendition (SGR) code in the color palette (see MODULES_COLORS)

Okay so when an abbreviated string is associated to a tag name (see MODULES_TAG_ABBREV), that abbreviation is what gets used to report the tag along the module name — or the tag is graphically rendered over the module name if an SGR code is associated with that tag abbreviation in the color palette. 💅 With an abbreviation set, the SGR code associated to the tag full name is ignored, so an SGR code should be associated to the abbreviation to get a graphical rendering of the tag. If the abbreviation associated to a tag corresponds to the empty string, the tag is not reported. periodt.

Graphical rendering is made over the tag name or abbreviation instead of over the module name for each tag name or abbreviation set in the MODULES_TAG_COLOR_NAME environment variable.

When several tags have to be rendered graphically over the same module name, each tag is rendered over a sub-part of the module name. In case more tags need to be rendered than the total number of characters in the module name, the remaining tags are graphically rendered over the tag name instead of over the module name. ✨

When the JSON output mode is enabled (with --json), tags are reported by their name under the tags attribute. Tag abbreviation and color rendering do not apply on JSON output. iykyk.

Heads up bestie: module tags cannot be used in search query to designate a modulefile.

🧲 Sticky modules 🧲

Modules are said sticky when they cannot be unloaded — they literally stick to the loaded environment. 🫶 Two kinds of stickiness can be distinguished:

sticky module: cannot be unloaded unless the unload is forced, or the module is reloaded after being unloaded, or a collection is restored.
super-sticky module: cannot be unloaded unless the module is reloaded after being unloaded; super-sticky modules cannot be unloaded even if the unload is forced.

Modules are designated sticky by associating them the sticky or the super-sticky module tag with the module-tag <#mfcmd-module-tag> modulefile command.

Starting with version 5.7, purge also preserves the direct and indirect requirements of retained sticky or super-sticky modules, even if these requirements have no sticky tag. The sticky_purge configuration applies to their skipped unload. With --force, sticky modules can be unloaded, but super-sticky modules and their requirements remain loaded. If several loaded modules satisfy an alternative requirement, only the last necessary one is preserved. 😭

When stickiness is defined over the generic module name (and not over a specific module version, a version list or a version range), sticky or super-sticky module can be swapped by another version of module. For instance if the sticky tag is defined over foo module, loaded module foo/1.2 can be swapped by foo/2.0. Such stickiness definition means one version of module should stay loaded whatever version it is. slay.

When restoring a collection or resetting to the initial environment, sticky modules are unloaded to ensure restore or reset sub-commands fully set the environment in target collection or initial state. Super-sticky modules still cannot be unloaded with restore and reset sub-commands. 💀

🧬 Module variants 🧬

Module variants are alternative evaluation of the same modulefile. A variant is specified by associating a value to its name when designating module. Variant specification relies on the Advanced module version specifiers mechanism. no cap.

Once specified, variant's value is transmitted to the evaluating modulefile which instantiates the variant in the ModuleVariant <#mfvar-ModuleVariant> array variable when reaching the variant <#mfcmd-variant> modulefile command declaring this variant. For instance the module load foo/1.2 bar=value1 command leads to the evaluation of foo/1.2 modulefile with bar=value1 variant specification. When reaching the variant bar value1 value2 value3 command in modulefile during its evaluation, the ModuleVariant(bar) array element is set to the value1 string. 🎀

Once variants are instantiated, modulefile's code could check the variant values to adapt the evaluation and define for instance different module requirements or produce different environment variable setup.

Variants are interpreted in contexts where modulefiles are evaluated. Variants specified on module designation are ignored by the is-avail or path sub-commands. On search sub-commands (avail, spider, whatis and paths), variants are interpreted and trigger the Extra match search process to filter results.

When modulefile is evaluated a value should be specified for each variant this modulefile declares. When reaching the variant <#mfcmd-variant> modulefile command declaring a variant, an error is raised if no value is specified for this variant and if no default value is declared. Specified variant value should match a value from the declared accepted value list if such list is defined otherwise an error is raised. Additionally if a variant is specified but does not correspond to a variant declared in modulefile, an error is raised. not me getting an error because a variant is missing 😭.

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

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

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

When searching for available modules, not: prefix may be added on variant criterion, which matches modules that do not provide these variant values. For instance not:bar=value1 will return modules not defining a bar variant or defining a bar variant but without value1 among available values.

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

Variants are reported within curly braces next to module name, each variant definition separated from the others with a colon character (e.g., foo/1.2{variant1=value:+variant2}). Boolean variants are reported with the +name or -name syntaxes on list sub-command or with the name=on,off syntax on avail and spider sub-commands. When a shortcut character is defined for a variant (see MODULES_VARIANT_SHORTCUT) it is reported with the <shortcut>value syntax. For instance if % character is defined as a shortcut for variant1: foo/1.2{%value:+variant2}. obsessed with the curly brace fit ✨.

When the JSON output mode is enabled (with --json), variants are reported under the variants JSON object as name/value pairs. Values of Boolean variant are set as JSON Boolean. Other values are set as JSON strings. Variant shortcut and color rendering do not apply on JSON output.

🔍 Extra match search 🔍

Extra match search is a mechanism that evaluates available modulefiles during a module search to find those matching an extra query or to report additional information. After selecting modulefiles that match the module name and version specified in search query, these remaining modulefiles are evaluated to collect their content. vibe check: extra evaluation incoming.

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

Extra match search is triggered when:

Module variants and their available values have to be reported in avail and spider outputs (see --output/-o option): extra match search is triggered to collect variant information
Provided module aliases have to be reported in avail and spider outputs (see --output/-o option): extra match search is triggered to collect these module aliases defined within modulefiles
Module variant is specified in search query: extra match search is triggered to collect variant information then match them against variant specified in query
Extra specifier is specified in search query: extra match search is triggered to collect commands used in modulefiles or modulercs then match them against extra specifier query

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

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

Modulefiles tagged forbidden are excluded from extra match search evaluation. Thus they are excluded from result when this mechanism is triggered.

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

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

🎀 Collections 🎀

Collections describe a sequence of module use then module load commands that are interpreted by modulecmd.tcl to set the user environment as described by this sequence.

Collections are generated by the save sub-command that dumps the current user environment state in terms of module paths and loaded modules. By default collections are saved under the $HOME/.module directory.

$ module list
Currently Loaded Modulefiles:
 1) foo/1.2   2) bar/2.0   3) qux/3.5
$ module save foo
$ cat $HOME/.module/foo
module use --append /path/to/modulefiles
module load foo
module load bar/2.0
module load qux/3.5

The content of a collection can also be shown off with the saveshow sub-command. 💅 Ngl, in the example above the bare module name is recorded for the foo modulefile because the loaded version is the implicit default. Loaded version recording can be enforced by enabling the collection_pin_version configuration option. Slay.

$ module config collection_pin_version 1
$ module save foo
$ module saveshow foo
-------------------------------------------------------------------
/home/user/.module/foo:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0
module load qux/3.5

-------------------------------------------------------------------

When a collection is activated with the restore sub-command, module paths and loaded modules are unused or unloaded if they are not part of it, or if they are not ordered the same way as in the collection. Vibe check time:

$ module list
Currently Loaded Modulefiles:
 1) foo/1.2   2) bar/2.1   3) qux/3.5
$ module restore foo
Unloading qux/3.5
Unloading bar/2.1
Loading bar/2.0
Loading qux/3.5
$ module list
Currently Loaded Modulefiles:
 1) foo/1.2   2) bar/2.0   3) qux/3.5

In that example, the second and third loaded modules get changed. The first loaded module is not changed or reloaded because it is the same module between the current environment and the collection. Since the second loaded module was different, that module and all those loaded afterward are unloaded, then the sequence described by the collection is loaded. As a result, the third loaded module is reloaded, even if it was the same module between the current environment and the collection. It’s giving “order matters, bestie.” 🎀

Existing collections can be listed with the savelist sub-command. They can be deleted with the saverm sub-command.

$ module savelist
Named collection list:
 1) default   2) foo
$ module saverm default
$ module savelist
Named collection list:
 1) foo

When no argument is provided to the save, restore, saveshow or saverm sub-commands, the default collection is assumed. ✨

A collection can also be specified as a full pathname:

$ module save /path/to/collections/bar
$ module saveshow /path/to/collections/bar
-------------------------------------------------------------------
/path/to/collections/bar:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0
module load qux/3.5

-------------------------------------------------------------------

🌱 Initial environment 🌱

Initial environment state — which corresponds to modulepaths enabled and modules loaded during Modules initialization — is referred to as the __init__ collection. This collection is virtual because its content is stored in __MODULES_LMINIT and not in a file. It can be displayed with saveshow and restored with the restore sub-command. Iconic behavior, honestly. 🦋

$ module saveshow __init__
-------------------------------------------------------------------
initial environment:

module use --append /path/to/modulefiles
module load foo/1.2

-------------------------------------------------------------------

If the default collection does not exist, the saveshow and restore sub-commands assume the __init__ collection when no argument is provided to them.

$ module list
Currently Loaded Modulefiles:
 1) foo/1.2   2) bar/2.1   3) qux/3.5
$ module savelist
Named collection list:
 1) foo
$ module restore
Unloading qux/3.5
Unloading bar/2.1

Initial environment state can also be restored with the reset sub-command. This sub-command’s behavior can be changed with the reset_target_state configuration option, to choose to just purge loaded modules or to restore a specific collection. Main character energy for a config option, fr fr. 👑

🎯 Collection targets 🎯

A collection target can be defined for the current environment session with the collection_target configuration option. When set, available collections are reduced to those suffixed with the target name. Which means restore, saveshow, savelist and saverm only find collections matching the currently set target.

$ module savelist
Named collection list:
 1) foo
$ module config collection_target mytarget
$ module savelist
No named collection (for target "mytarget").
$ module restore foo
ERROR: Collection foo (for target "mytarget") cannot be found

When saving a new collection, the generated file is suffixed with the currently set target name.

$ module save bar
$ module savelist
Named collection list (for target "mytarget"):
 1) bar
$ ls $HOME/.module
bar.mytarget  foo

Collection targets help to distinguish contexts and make a collection reachable only from the context it has been made for. For instance, the same user account may be used to access different OSes or machine architectures. With a target set, users are ensured to only access collections built for the context they are currently connected to. See also the MODULES_COLLECTION_TARGET section. Periodt. 💅

🧺 Stash collections 🧺

The current user environment can be stashed with the stash sub-command. When this sub-command is called, the current module environment is saved in a stash collection, then the initial environment is restored.

$ module list
Currently Loaded Modulefiles:
 1) foo/1.2   2) qux/4.2
$ module stash
Unloading qux/4.2

Specific sub-commands are available to handle stash collections: stashpop, stashlist, stashshow, stashrm and stashclear. A stash collection is restored with stashpop, which also deletes the collection once restored. Not me being obsessed with clean stash energy. 🍓

$ module stashlist
Stash collection list (for target "mytarget"):
 0) stash-1667669750191
$ module stashpop
Loading qux/4.2
$ module stashlist
No stash collection (for target "mytarget").

Stash collections have the same format and are saved in the same location as other collections. Collection target also applies to stash collections. Creation timestamp is saved in the stash collection name.

A stash collection can be designated by its full collection name (i.e., stash-<creation_timestamp>) or a stash index. The most recent stash collection has index 0, and 1 is the one before it. When no argument is provided on stash sub-commands, the latest stash collection is assumed (that is, stash index 0).

$ module stashlist
Stash collection list (for target "mytarget"):
 0) stash-1667669750783   1) stash-1667669750253
$ module stashshow 1
-------------------------------------------------------------------
/home/user/.module/stash-1667669750253.mytarget:

module use --append /path/to/modulefiles
module load foo/1.2
module load bar/2.0

-------------------------------------------------------------------

🛠️ Site-specific configuration 🛠️

Siteconfig, the site-specific configuration script, is a way to extend modulecmd.tcl. Siteconfig is a Tcl script. Its location is /etc/environment-modules/siteconfig.tcl. 🌸

When modulecmd.tcl is invoked, it sources the siteconfig script if it exists. Any global variable or procedure of modulecmd.tcl can be redefined in siteconfig.

An additional siteconfig script may be specified through the extra_siteconfig configuration option. The MODULES_SITECONFIG environment variable is defined by the config sub-command when setting extra_siteconfig. If it exists, the extra siteconfig is sourced by modulecmd.tcl right after the main siteconfig script. Highkey a little configuration multiverse, iykyk. 🌈

🪝 Hooks 🪝

The add-hook command lets siteconfig register a procedure to be called on one of the fixed set of hook events listed below, without having to know anything about the internal implementation of modulecmd.tcl. This is the recommended way to run site-specific code before or after a modulefile or modulerc evaluation. It is called this way:

add-hook event procedure

event must be one of the hook events listed below; an unrecognized event name is a siteconfig error, raised immediately when add-hook is called. Several procedures may be registered on the same event: they are then all called, in their registration order, every time the event occurs.

If procedure raises an error, this error is reported but does not stop the other procedures registered on the same event from being called, and does not interrupt the modulefile or modulerc evaluation the event relates to. That part is important, bestie — one messy hook doesn’t get to ruin the whole group chat. 💀

Unless stated otherwise, hook procedures execute in the context of the main Tcl interpreter — the same one siteconfig itself runs in — never in the modulefile- or modulerc-specific sub-interpreter the event relates to. See the second example below for how a hook procedure can still reach that sub-interpreter when it needs to run modulefile or modulerc commands.

before-modulefile-eval modfile modname modnamevr modspec mode requested — Called right before a modulefile is evaluated, with the path of the modulefile (modfile), the module name and version being evaluated without its variant specification (modname), the module name, version and variant (modnamevr), the module specification as it was passed to the internal evaluation call, prior to resolution — typically what the user typed on the command line (modspec), the current evaluation mode (mode, see module-info <#mfcmd-module-info>) and whether this modulefile evaluation was directly requested by the user or triggered as a side effect, for instance an automatically-loaded dependency (requested, a boolean). The value procedure returns, if any, is ignored.
after-modulefile-eval modfile modname modnamevr modspec mode requested status — Called right after a modulefile has been evaluated, with the same arguments as before-modulefile-eval plus status: 0 if the modulefile evaluated without error, 1 otherwise. The value procedure returns, if any, is ignored.
before-modulerc-eval modfile modname — Called right before a modulerc or .version file is evaluated, with the path of the file (modfile) and the modulerc short name (modname). Modulerc evaluation is not tied to a single evaluation mode nor to a specific request the way modulefile evaluation is, so neither a mode nor a requested argument is provided here. The value procedure returns, if any, is ignored.

...okay so this event, and after-modulerc-eval too, only apply to a .modulerc or .version file that got resolved while looking up a module under a modulepath. 💅 Those RC files that get read once at startup (rcfile and the other sources listed there)? They are not modulerc files, bestie — they get evaluated through before-modulefile-eval/after-modulefile-eval instead, in load mode, exactly like any file you'd pass to the source sub-command. periodt.

after-modulerc-eval modfile modname status — called right after a modulerc or .version file has been evaluated. Same arguments as before-modulerc-eval, plus status: 0 if the file evaluated without error, 1 otherwise. The value the procedure returns, if any, is ignored. 🫠

The following example uses add-hook to record every directly-requested modulefile load into a site-defined audit file. Ngl this is a whole different need than the built-in logger integration (see the channel argument of puts <# mfcmd-puts>), which only forwards messages a modulefile explicitly sends to it:

proc auditRequestedLoad {modfile modname modnamevr modspec mode requested} {
   if {$requested && $mode eq {load}} {
      set fd [open /var/log/modules-audit.log a]
      puts $fd "[clock format [clock seconds]] $modnamevr"
      close $fd
   }
}
add-hook before-modulefile-eval auditRequestedLoad

So if a hook procedure that's running in the context of the main interpreter needs to execute modulefile commands (like, say, to define environment variables), those commands should be run through the current modulefile Tcl interpreter. 🧚 This keeps the commands behaving consistently with the current modulefile evaluation mode — vibe check passed.

proc hook_procedure {modfile modname modnamevr modspec mode requested} {
    # get the name of the current modulefile Tcl interpreter
    set modfile_interp [getCurrentModfileInterpName]

    # execute a modulefile command in the current interpreter context
    interp eval $modfile_interp setenv MYVAR value
}
add-hook before-modulefile-eval hook_procedure

Advanced hooks

Siteconfig lowkey relies on the Tcl language's ability to overwrite previously defined variables and procedures. 👑 So for the needs add-hook does not cover — for instance rejecting a modulefile evaluation outright, which a hook procedure literally cannot do since its return value is ignored — sites may still deploy their own Tcl code in siteconfig to adapt modulecmd.tcl to their specific needs. The trace Tcl command is the main character here: you can use it to define hooks that run when entering or leaving a given procedure, or when a variable is read or written. Peep the trace(n) man page for detailed information. 🌈

The following example blocks the evaluation of a specific modulefile by raising an error from an enter trace on the internal execute-modulefile procedure — a whole thing that cannot be expressed through before-modulefile-eval:

proc blockModule {cmdstring op} {
   # third word of cmdstring is the resolved module name and version
   if {[lindex $cmdstring 2] eq {foo/1.0}} {
      error "foo/1.0 is blocked by site policy"
   }
}
trace add execution execute-modulefile enter blockModule

Another possibility? Overriding the definition of an existing procedure — first rename its original version, then create a new procedure that adds your specific code and leans on the renamed original procedure for the rest. 🎀 See the rename(n) man page for details. As an example, the following code adds a new query option to the module-info <#mfcmd-module-info> modulefile command:

rename module-info __module-info
proc module-info {what {more {}}} {
   switch -- $what {
      platform { return myhost-$::tcl_platform(machine) }
      default { return [__module-info $what $more] }
   }
}

Heads up bestie: these techniques bind to modulecmd.tcl internal procedure names and call signatures, which may change across versions. Prefer add-hook when one of its events covers the need. 💀

Siteconfig hook variables

Some Tcl variables can be defined in the siteconfig script with a special hook meaning. The following variables are recognized:

modulefile_extra_vars — a list of variable names and associated values to set up in the modulefile evaluation context. These variables can be accessed when the modulefile is executed. In case code in a modulefile changes the value of such a variable, its value gets reset to the one defined in modulefile_extra_vars prior to the evaluation of the next modulefile. 🌸

set modulefile_extra_vars {myvar 1 othervar {some text}}

In the above siteconfig example, modulefile_extra_vars sets the myvar and othervar variables in the modulefile evaluation context with respectively 1 and some text as value.

modulefile_extra_cmds — a list of command and associated local procedure to set up in the modulefile evaluation context. These commands can be called from the modulefile to execute the associated procedure. In case a modulefile changes the definition of such a command, its definition gets bound again to the procedure defined in modulefile_extra_cmds prior to the evaluation of the next modulefile. ✨

proc mycmd {} {
    # Tcl code
}
proc anotherproc {args} {
    # Tcl code
}
set modulefile_extra_cmds {mycmd mycmd othercmd anotherproc}

In the above siteconfig example, modulefile_extra_cmds sets the mycmd and othercmd commands in the modulefile evaluation context and binds them respectively to the mycmd and anotherproc procedures defined in the siteconfig script.

modulerc_extra_vars — a list of variable names and associated values to set up in the modulerc evaluation context. These variables can be accessed when the modulerc is executed. In case code in a modulerc changes the value of such a variable, its value gets reset to the one defined in modulerc_extra_vars prior to the evaluation of the next modulerc. 🦋

set modulerc_extra_vars {myvar 1 othervar {some text}}

In the above siteconfig example, modulerc_extra_vars sets the myvar and othervar variables in the modulerc evaluation context with respectively 1 and some text as value.

modulerc_extra_cmds — a list of command and associated local procedure to set up in the modulerc evaluation context. These commands can be called from the modulerc to execute the associated procedure. In case a modulerc changes the definition of such a command, its definition gets bound again to the procedure defined in modulerc_extra_cmds prior to the evaluation of the next modulerc. 💜

proc mycmd {} {
    # Tcl code
}
proc anotherproc {args} {
    # Tcl code
}
set modulerc_extra_cmds {mycmd mycmd othercmd anotherproc}

In the above siteconfig example, modulerc_extra_cmds sets the mycmd and othercmd commands in the modulerc evaluation context and binds them respectively to the mycmd and anotherproc procedures defined in the siteconfig script.

Module cache

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

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

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

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

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

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

💖 EXIT STATUS 💖

The module command exits with 0 if its execution succeeds. Otherwise 1 is returned. That's it, that's the whole vibe check. ✨

🌸 ENVIRONMENT 🌸

__MODULES_AUTOINIT_INPROGRESS — if set to 1, the autoinit sub-command process is skipped.

This environment variable is set to 1 by the autoinit sub-command after checking that it is not set. It ensures no nested initialization of Modules occur. At the end of the processing of the autoinit sub-command, __MODULES_AUTOINIT_INPROGRESS is unset. 🧚

__MODULES_LMALTNAME — a colon separated list of the alternative names set through module-version <# mfcmd-module-version> and module-alias <# mfcmd-module-alias> statements corresponding to all loaded modulefiles. Each element in this list starts with the name of the loaded modulefile followed by all alternative names resolving to it. The loaded modulefile and its alternative names are separated by the ampersand character. 💅

Each alternative name stored in __MODULES_LMALTNAME is prefixed by the al| string if it corresponds to a module alias, or prefixed by the as| string if it corresponds to an automatic version symbol. These prefixes help to distinguish the different kinds of alternative name. 🎀

This environment variable is intended for module command internal use — to get knowledge of the alternative names matching loaded modulefiles, so the environment stays consistent when conflicts or pre-requirements are set over these alternative designations. It also helps to find a match after modulefiles have been loaded, when unload, is-loaded or info-loaded actions are run over these names. 👑

__MODULES_LMALTNAME — starting version 4.7 of Modules, this one is also used on the list sub-command to report the symbolic versions associated with the loaded modules. 💅 (yes bestie, it does double duty, we love a multitasker)
__MODULES_LMCONFLICT — a colon separated list of the conflict statements defined by all loaded modulefiles. Each element in this list starts by the name of the loaded modulefile declaring the conflict, followed by the name of all modulefiles it declares a conflict with. These loaded modulefiles and conflicting modulefile names are separated by the ampersand character.

This environment variable is intended for module command internal use — to get knowledge of the conflicts declared by the loaded modulefiles, so the environment stays consistent when a conflicting module is asked for load afterward. 🫶

__MODULES_LMEXTRATAG — a colon separated list of the tags corresponding to all loaded modulefiles that have been set through the --tag option. Each element in this list starts by the name of the loaded modulefile, followed by all explicitly set tags applying to it. The loaded modulefile and its tags are separated by the ampersand character.

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

__MODULES_LMINIT — a colon separated list describing the modulepaths that have been enabled and the modulefiles that have been loaded with their tags during Modules initialization. Each element in this list corresponds to a collection definition line. 📋

This environment variable is intended for module command internal use — to get knowledge of the initial loaded state after initialization.

This initial environment state can then be restored with the reset sub-command. It can also be restored with the restore sub-command when __init__ collection name is specified, or when no collection name is specified and no default collection exists.

The content of the initial environment can be displayed with the saveshow sub-command when __init__ collection name is specified, or when no collection name is specified and no default collection exists.

__MODULES_LMPREREQ — a colon separated list of the prereq statements defined by all loaded modulefiles. Each element in this list starts by the name of the loaded modulefile declaring the pre-requirement, followed by the name of all modulefiles it declares a prereq with. These loaded modulefiles and pre-required modulefile names are separated by the ampersand character. When a prereq statement is composed of multiple modulefiles, these modulefile names are separated by the pipe character. 🪄

This environment variable is intended for module command internal use — to get knowledge of the pre-requirement declared by the loaded modulefiles, in order to keep environment consistent when a pre-required module is asked for unload afterward.

__MODULES_LMPREREQPATH — a colon separated list of the prereq statements set with a specific --modulepath option defined by all loaded modulefiles. Each element in this list starts by the name of the loaded modulefile declaring the pre-requirement, followed by the name of all modulefiles it declares a prereq with and their specific modulepath. These loaded modulefiles, pre-required modulefile names and specific modulepaths set are separated by the ampersand character. When a prereq statement is composed of multiple modulefiles or multiple specific modulepaths, these names are separated by the pipe character.

This environment variable is intended for module command internal use — to get knowledge of the pre-requirement declared by the loaded modulefiles, in order to keep environment consistent. 🧚

__MODULES_LMREFRESH — a colon separated list of the loaded modules that are qualified for refresh evaluation. Loaded modules listed in this variable are those defining volatile environment changes like shell completion, alias and function. 🌈
__MODULES_LMSOURCESH — a colon separated list of the source-sh statements defined by all loaded modulefiles. Each element in this list starts by the name of the loaded modulefile declaring the environment changes made by the evaluation of source-sh scripts. This name is followed by each source-sh statement call and the corresponding result achieved in the modulefile. The loaded modulefile name and each source-sh statement description are separated by the ampersand character. The source-sh statement call and each resulting modulefile command (corresponding to the environment changes done by the sourced script) are separated by the pipe character. 🍓

This environment variable is intended for module command internal use — to get knowledge of the modulefile commands applied for each source-sh command when loading the modulefile. In order to reverse these modulefile commands when the modulefile is unloaded, to undo the environment changes.

__MODULES_LMSTICKYRULE — a colon separated list of the sticky or super-sticky tag definitions applying to loaded modulefiles. Each element in this list starts by the name of the loaded modulefile, followed by the sticky tag name and the module specifications on which the tag applies. These loaded modulefiles and sticky tag definitions are separated by the ampersand character. Tag name and module specifications on which it applies are separated by the pipe character.

When stickiness applies specifically to the loaded module name and version, the sticky rule is not recorded in __MODULES_LMSTICKYRULE. 💀 (fr fr, it just doesn't show up there)

This environment variable is intended for module command internal use — to get knowledge of the stickiness scope when a sticky module is changed.

__MODULES_LMTAG — a colon separated list of the tags corresponding to all loaded modulefiles that have been set through module-tag statements or from other modulefile statements like module-forbid (that may apply the nearly-forbidden tag in specific situation) (see the Module tags section). Each element in this list starts by the name of the loaded modulefile, followed by all tags applying to it. The loaded modulefile and its tags are separated by the ampersand character. 🏷️

This environment variable is intended for module command internal use — to get knowledge of the tags applying to loaded modulefiles, in order to report these tags on list sub-command output or to apply specific behavior when unloading the modulefile.

__MODULES_LMUSE — a colon separated list of the modulepaths enabled by all loaded modulefiles. Each element in this list starts by the name of the loaded modulefile enabling the modulepath, followed by all modulepaths it enables. These loaded modulefiles and enabled modulepaths are separated by the ampersand character.

This environment variable is intended for module command internal use — to get knowledge of the modulepath enabled by the loaded modulefiles, in order to keep environment consistent when unloading these modules whereas modulefiles from the enabled modulepaths are loaded. ✨

__MODULES_LMVARIANT — a colon separated list of the variant instantiated through variant statements by all loaded modulefiles (see the Module variants section). Each element in this list starts by the name of the loaded modulefile, followed by all the variant definitions set during the load of this module. The loaded modulefile and each of its variant definitions are separated by the ampersand character. Each variant definition starts with the variant name, followed by the variant value set, then a flag to know if the variant is of the Boolean type, and the last element in this definition is a flag to know if the chosen value is the default one for this variant and if it has been automatically set or not. These four elements composing the variant definition are separated by the pipe character. 🎀

This environment variable is intended for module command internal use — to get knowledge of the variant value defined by the loaded modulefiles, in order to keep environment consistent when requirements are set over a specific variant value, or just to report these variant values when listing loaded modules.

__MODULES_PUSHENV_<VAR> — the stack of saved values for the <VAR> environment variable. A colon-separated list containing pairs of elements. A pair is formed by a loaded module name followed by the value set to <VAR> in this module with the pushenv command. An ampersand character separates the two parts of the pair.

First element in the list corresponds to the lastly set value of <VAR>. If a value were set to <VAR> prior to the first evaluated pushenv command, this value is associated to an empty module name, to record it as a pair element in __MODULES_PUSHENV_<VAR>. 💜

__MODULES_QUAR_<VAR> — the value of environment variable <VAR> passed to modulecmd.tcl in order to restore <VAR> to this value once started.
__MODULES_QUARANTINE_SET — if set to 1, restore the environment variables set on hold by the quarantine mechanism when starting the modulecmd.tcl script. This variable is automatically defined by the Modules shell initialization scripts or the module shell function when they apply the quarantine mechanism. (see MODULES_QUARANTINE_SUPPORT). 🙈
__MODULES_SHARE_<VAR> — the reference counter variable for the path-like variable <VAR>. A colon separated list containing pairs of elements. A pair is formed by a path element followed by its usage counter, which represents the number of times this path has been enabled in variable <VAR>. A colon separates the two parts of the pair. 🌸

So yeah, once you've added an element to a path-like variable more than one time, it gets tracked in the reference counter variable. And if an element of a path-like variable is not found in the reference counter variable? That literally just means it's only been added once to the path-like variable. Iconic minimalism, no notes.

And the empty-string edge case, because of course there's an edge case: when an empty string is added as an element in the path-like variable, it is added to the reference counter variable even if it's added only once — so we can tell the difference between an empty path-like variable and a path-like variable that contains an empty string as its single element. 💅

`_LMFILES_`

A colon separated list of the full pathname for all loaded modulefiles. 🗂️

This environment variable is generated by module command and should not be modified externally. Hands off, bestie — it's not yours to touch. 🙈

`LOADEDMODULES`

A colon separated list of all loaded modulefiles.

Also generated by module command, and also should not be modified externally. Same rule, same energy. ✨

`MODULECONTACT`

Email address to contact in case any issue occurs during the interpretation of modulefiles. 📧

This value supersedes the default value set in the contact configuration option, and you can define it with the config sub-command.

`MODULEPATH`

The path that the module command searches when looking for modulefiles. Typically it's set to the main modulefiles directory, /usr/share/Modules/modulefiles, by the initialization script. You can set MODULEPATH using module use, or let the module initialization script set it, so that group or personal modulefile directories get searched before or after the main modulefile directory. 🦋

Path elements registered in the MODULEPATH environment variable may contain reference to environment variables, and those get converted to their corresponding value by module command every single time it looks at the MODULEPATH value. If an environment variable referred to in a path element isn't defined, its reference is converted to an empty string. Poof. Gone. 😭

`MODULERCFILE`

The location of a global run-command file(s) containing modulefile specific setup. See the Modulecmd startup section for the detailed tea. 🎀

You can define several global run-command files in this environment variable by separating each of them with a colon character. More is more, honestly.

This value supersedes the default value set in the rcfile configuration option, and it can be defined with the config sub-command.

`MODULES_ABORT_ON_ERROR`

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

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

load
ml
mod-to-sh
purge
reload
switch
switch_unload
try-load
unload

Module sub-commands that are not configured to follow the abort on error behavior apply the continue on error behavior instead. In that case, if one modulefile evaluation fails, the sequence just keeps going with the remaining modulefiles. And when the --force option is used, continue on error behavior applies too.

This value supersedes the default value set in the abort_on_error configuration option, and you can define it with the config sub-command.

`MODULES_ADVANCED_VERSION_SPEC`

Set it to 1 and boom — advanced module version specifiers are enabled (peep the Advanced module version specifiers section). Set it to 0 and they're disabled. ✨

This value supersedes the default value set in the advanced_version_spec configuration option, and it can be defined with the config sub-command.

`MODULES_AUTO_HANDLING`

Set it to 1 to enable automated module handling mode, set it to 0 to disable it. Other values are ignored, respectfully. 👑

Automated module handling mode is all about extra actions triggered when loading or unloading a modulefile, so the constraints it declares actually get satisfied. Let's break it down, bestie:

When loading a modulefile, these actions get triggered:

Conflict Unload: unload of the modulefiles declared as a conflict of the loading modulefile — or if it is the same modulefile than the one loading but with a different set of variant or coming from a different modulepath.
Requirement Load: load of the modulefiles declared as a prereq of the loading modulefile.
Useless Requirement Unload: unload of the prereq modulefiles that have been automatically loaded for either an unloaded conflicting modulefile or a modulefile part of this useless requirement unloading batch. Modulefiles get added to this unloading batch only if they are not required by any other loaded modulefiles and if they are not tagged keep-loaded, sticky or super-sticky.
Dependent Reload: reload of the modulefiles declaring a prereq onto the loading modulefile — or declaring a prereq or a via requirement onto a modulefile part of this reloading batch.

When unloading a modulefile, these actions get triggered:

Dependent Unload: unload of the modulefiles declaring a non-optional prereq or a via requirement onto the unloaded modulefile — or onto a modulefile part of this unloading batch. A prereq modulefile counts as optional if the prereq definition order is made of multiple modulefiles and at least one alternative modulefile is loaded.
Useless Requirement Unload: unload of the prereq modulefiles that have been automatically loaded for either the unloaded modulefile, an unloaded dependent modulefile, or a modulefile part of this useless requirement unloading batch. Again, modulefiles are added to this unloading batch only if they're not required by any other loaded modulefiles and if they're not tagged keep-loaded, sticky or super-sticky.
Dependent Reload: reload of the modulefiles declaring a conflict or an optional prereq onto either the unloaded modulefile, an unloaded dependent, or an unloaded useless requirement — or declaring a prereq or a via requirement onto a modulefile part of this reloading batch.

And here's a mood-ruiner: if a loaded modulefile has some of its declared constraints unsatisfied (pre-required modulefile not loaded, or conflicting modulefile loaded, for instance), that loaded modulefile is excluded from the automatic reload actions described above. Sorry babe. 😭

Now for the specific case of the switch sub-command, where a modulefile is unloaded to then load another modulefile: Dependent modulefiles to Unload are merged into the Dependent modulefiles to Reload that get reloaded after the load of the switched-to modulefile. Same process applies to the Dependent Unload modulefiles of Conflict Unload modules. 🫶

The reload phase of all Dependent Reload modulefiles occurs after the evaluation of the main modulefile — whether that's load, unload or switch evaluation.

The reload phase of a Dependent Reload modulefile gets skipped if any of these conditions are met:

The required modules for this modulefile are not loaded.
A conflict is detected with the currently loaded environment.
The enabled modulepaths have changed, and the modulefile is no longer available.

But lowkey it's always attempted if the modulefile is tagged as super-sticky or sticky, and force mode is not enabled. Abort on error behavior is applied if reload of such module kind fails, whatever the value of the abort_on_error configuration option. Dependent Reload modulefiles whose reload has been skipped are treated as Dependent Unload modulefiles.

Conflict Unload mechanism is activated only if the conflict_unload configuration option is also enabled. Teamwork, kinda.

This value supersedes the default value set on the auto_handling configuration option, and it can be defined with the config sub-command. The --auto and --no-auto command line switches override this environment variable. 💅

`MODULES_AVAIL_INDEPTH`

Set to 1 to enable in depth search results for the avail sub-command, set to 0 to disable avail sub-command in depth mode. Other values are ignored. 🧚

When in depth mode is enabled, modulefiles and directories contained in directories matching the search query are also included in the search results. When it's disabled, those modulefiles and directories contained in matching directories are excluded.

This value supersedes the default value set in the avail_indepth configuration option, and it can be defined with the config sub-command. The --indepth and --no-indepth command line switches override this environment variable.

`MODULES_AVAIL_OUTPUT`

A colon separated list of the elements to report in addition to module names on the avail sub-command regular output mode. Extra credit fr fr. 🎀

Accepted elements you can set in the value list are:

alias: module aliases.
provided-alias: show module aliases and evaluate all modulefiles to get aliases provided by them.
dirwsym: directories associated with symbolic versions.
hidden: show all hidden modules.
indesym: symbolic versions reported independently from the module or directory they are attached to.
key: legend appended at the end of the output to explain it.
modulepath: modulepath names set as header prior the list of available modules found in them.
sym: symbolic versions associated with available modules.
tag: tags associated with available modules.
variant: variants and their possible values associated with available modules.
variantifspec — works like variant, but only when a variant has actually been specified in the search query. 💅
via — adds a mention next to the modulepath name of which loaded module enables it, if any. 👑

The order of the elements in the list does not matter. Module names are the only content reported when LIST is set to an empty value.

If the modulepath element is missing from the value list, the available modules from global/user rc and all enabled modulepaths are reported as a single list.

When indesym element is set, dirwsym and sym elements are disabled.

This environment variable value supersedes the default value set in the avail_output configuration option. It can be defined with the config sub-command. The --output/-o command line switches override this environment variable.

🌸 `MODULES_AVAIL_TERSE_OUTPUT` 🌸

A colon separated list of the elements to report in addition to module names on avail sub-command terse output mode.

See MODULES_AVAIL_OUTPUT to get the accepted elements that can be set in value list. Exception for via element which is not accepted for terse output mode.

The order of the elements in the list does not matter. Module names are the only content reported when LIST is set to an empty value.

This environment variable value supersedes the default value set in the avail_terse_output configuration option. It can be defined with the config sub-command. The --output/-o command line switches override this environment variable.

🎀 `MODULES_CACHE_BUFFER_BYTES` 🎀

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

🦋 `MODULES_CACHE_EXPIRY_SECS` 🦋

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

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

💖 `MODULES_CMD` 💖

The location of the active module command script.

⚠️ This environment variable is generated by module command and should not be modified externally.

🌈 `MODULES_COLLECTION_PIN_VERSION` 🌈

If set to 1, register exact version number of modulefiles when saving a collection. Otherwise modulefile version number is omitted if it corresponds to the explicitly set default version and also to the implicit default when the configuration option implicit_default is enabled.

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

⭐ `MODULES_COLLECTION_PIN_TAG` ⭐

If set to 1, register all tags applying to modulefiles when saving a collection. Otherwise only the extra tags set through the --tag option and tags resulting from specific module states (like auto-loaded and keep-loaded tags) are recorded in collection. Note that the nearly-forbidden tag due to its temporal meaning is not saved in collection even when this configuration option is enabled.

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

👑 `MODULES_COLLECTION_TARGET` 👑

The collection target that determines what collections are valid thus reachable on the current system.

Collection directory may sometimes be shared on multiple machines which may use different modules setup. For instance modules users may access with the same HOME directory multiple systems using different OS versions. When it happens a collection made on machine 1 may be erroneous on machine 2.

When a target is set, only the collections made for that target are available to the restore, savelist, saveshow, saverm, stash, stashpop, stashlist, stashshow, and stashrm sub-commands. Saving a collection registers the target footprint by suffixing the collection filename with .$MODULES_COLLECTION_TARGET. The collection target is not involved when collection is specified as file path on the saveshow, restore and save sub-commands.

For example, the MODULES_COLLECTION_TARGET variable may be set with results from commands like lsb_release, hostname, dnsdomainname, etc.

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

💜 `MODULES_COLOR` 💜

Defines if output should be colored or not. Accepted values are never, auto and always.

When color mode is set to auto, output is colored only if the standard error output channel is attached to a terminal.

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

NO_COLOR, CLICOLOR and CLICOLOR_FORCE environment variables are also honored to define color mode. The never mode is set if NO_COLOR is defined (regardless of its value) or if CLICOLOR equals to 0. If CLICOLOR is set to another value, it corresponds to the auto mode. The always mode is set if CLICOLOR_FORCE is set to a value different than 0. NO_COLOR variable prevails over CLICOLOR and CLICOLOR_FORCE. Color mode set with these three variables is superseded by mode set with MODULES_COLOR environment variable or with --color command line switch.

🍓 `MODULES_COLORS` 🍓

Specifies the colors and other attributes used to highlight various parts of the output. Its value is a colon-separated list of output items associated to a Select Graphic Rendition (SGR) code. It follows the same syntax than LS_COLORS.

Output items are designated by keys. Items able to be colorized are: highlighted element (hi), debug information (db), trace information (tr), tag separator (se); Error (er), warning (wa), module error (me) and info (in) message prefixes; Modulepath (mp), directory (di), module alias (al), module variant (va), module symbolic version (sy), module default version (de) and modulefile command (cm).

Module tags can also be colorized. The key to set in the color palette to get a graphical rendering of a tag is the tag name or the tag abbreviation if one is defined for tag. The SGR code applied to a tag name is ignored if an abbreviation is set for this tag thus the SGR code should be defined for this abbreviation to get a graphical rendering. Each basic tag has by default a key set in the color palette, based on its abbreviated string: auto-loaded (aL), forbidden (F), hidden and hidden-loaded (H), loaded (L), nearly-forbidden (nF), sticky (S), super-sticky (sS), keep-loaded (kL) and warning (W).

See the Select Graphic Rendition (SGR) section in the documentation of the text terminal that is used for permitted values and their meaning as character attributes. These substring values are integers in decimal representation and can be concatenated with semicolons. Modules takes care of assembling the result into a complete SGR sequence (\33[...m). Common values to concatenate include 1 for bold, 4 for underline, 30 to 37 for foreground colors and 90 to 97 for 16-color mode foreground colors. See also https://en.wikipedia.org/wiki/ANSI_escape_code#Select_Graphic_Rendition_parameters for a complete SGR code reference.

No graphical rendition will be applied to an output item that could normally be colored but which is not defined in the color set. Thus if MODULES_COLORS is defined empty, no output will be colored at all.

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

🧚 `MODULES_CONFLICT_UNLOAD` 🧚

If set to 1, enable automated unload of conflicting modules when loading a module. If set to 0, disable this automated conflict unload mechanism.

Conflict Unload is a mechanism part of the automated module handling mode. To activate this mechanism, auto_handling configuration option should also be enabled.

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

🌸 `MODULES_DOMAINNAME` 🌸

Command to fetch domain name. The value of this variable is composed of a domainname command name or path eventually followed by command-line options.

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

🫶 `MODULES_EDITOR` 🫶

Text editor command name or path for use to open modulefile through the edit sub-command.

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

Text editor could also be defined through the VISUAL or EDITOR environment variables. These environment variables are overridden by MODULES_EDITOR.

💫 `MODULES_EXTENDED_DEFAULT` 💫

If set to 1, a specified module version is matched against starting portion of existing module versions, where portion is a substring separated from the rest of the version string by . or - characters. For example specified modules mod/1 and mod/1.2 will match existing modulefile mod/1.2.3 and mod/2.4 will match mod/2.4-91db5cf2.

In case multiple modulefiles match the specified module version and a single module has to be selected, the explicitly set default version is returned if it is part of matching modulefiles. Otherwise the implicit default among matching modulefiles is returned if defined (see MODULES_IMPLICIT_DEFAULT section).

...and yeah, this value overrides whatever default you set in the extended_default configuration option — and you can define it with the config sub-command. 💅

MODULES_FAMILY_<NAME> — the module name minus its version that provides for the name family in the environment you've got loaded rn. This one gets defined through the family modulefile command. 🎀

So like, if loading foo/1.0 defines it as being a member of the bar family, then MODULES_FAMILY_BAR gets set to foo. Easy.

🫶 Heads up bestie: this env var is generated by the module command itself — do not go modifying it externally, ok?

MODULES_HIDE_AUTO_LOADED — set it to 1 and every automatically loaded module gets tag-hidden-loaded. Which means they won't show up on the list sub-command unless you pass the --all option. 🙈

This value overrides the default from the hide_auto_loaded configuration option, and you can define it with the config sub-command.

MODULES_ICASE — ok so when module specifications get passed as arguments to module sub-commands or modulefile Tcl commands, this is what decides the case sensitiveness used to match them. 🔍
- Set it to never → case sensitive match, every single time, no exceptions.
- Set it to search → case insensitive match gets applied to the avail, list, whatis, paths, savelist and spider sub-commands.
- Set it to always → case insensitive match is also applied to all the other module sub-commands and modulefile Tcl commands, for the module specifications they receive as arguments.

This value overrides the default from the icase configuration option, and you can define it with the config sub-command. Oh and — the --icase/-i command line switches, which correspond to the always mode, override this environment variable. periodt. 👑

MODULES_IGNORE_CACHE — ignore module cache if set to 1, don't if set to 0. That's it, that's the vibe. ✨

This value overrides the default from the ignore_cache configuration option, and you can define it with the config sub-command. The --ignore-cache command line switch overrides this environment variable.

MODULES_IGNORE_CACHE_SUBCMDS — a colon separated list of the module sub-commands that ignore module cache. When one of these sub-commands runs, modulepath directories get walked through to search for modules instead of relying on their cache file. 🚶‍♀️

Sub-command name aliases (like add for load) resolve to their target sub-command, and that's the name you set in the value list. The ml command used without a sub-command name translates to the underlying load or unload sub-commands, iykyk.

Ignoring cache can be genuinely useful for sub-commands targeting specific modules (like load) when cache files are large — walking through modulepath content to find the modules you asked for may be faster than evaluating the whole entire cache file. 💨

This value overrides the default from the ignore_cache_subcmds configuration option, and you can define it with the config sub-command.

MODULES_IGNORE_USER_RC — skip evaluation of the user-specific module rc file ($HOME/.modulerc) if set to 1, or don't skip it if set to 0. 🏠

This value overrides the default from the ignore_user_rc configuration option, and you can define it with the config sub-command. The --ignore-user-rc command line switch overrides this environment variable.

MODULES_IMPLICIT_DEFAULT — defines (if set to 1) or doesn't (if set to 0) an implicit default version for modules that don't have a default version explicitly defined (peep the Locating Modulefiles section in the modulefile man page for the deets). 🎯

Without either an explicit or implicit default version defined, a module has to be fully qualified (as in, version specified in addition to its name) to get:

targeted by module load, switch, display, help, test and path sub-commands.
restored from a collection, unless already loaded in collection-specified order.
automatically loaded by automated module handling mechanisms when declared as a module requirement, with prereq or module load modulefile commands.

An error gets returned in all those situations if neither an explicit nor an implicit default version is defined. 😭

This value overrides the default from the implicit_default configuration option, and you can define it with the config sub-command. But! this environment variable is ignored if implicit_default has been declared locked in the locked_configs configuration option. 🔒

MODULES_IMPLICIT_REQUIREMENT — defines (if set to 1) or doesn't (if set to 0) an implicit prereq or conflict requirement onto modules specified respectively on module load or module unload commands in a modulefile. 🧚

When it's enabled, an implicit conflict requirement onto the switched-off module and a prereq requirement onto the switched-on module are also defined for module switch commands used in a modulefile.

This value overrides the default from the implicit_requirement configuration option, and you can define it with the config sub-command. The --not-req option, applied to a module command in a modulefile, overrides this environment variable.

MODULES_INFO_EXTENSION — consider (if set to 1) that module extensions have a pure informational purpose and no module alias is associated to them. 👀 Extensions defined with the provide modulefile command are not affected by this mechanism.

This value overrides the default from the info_extension configuration option, and you can define it with the config sub-command.

MODULES_INIT_ENVVARS — a colon-separated list of environment variable initial definitions. Every definition has to use the format VARIABLE_NAME=initial_value. When an environment variable gets modified for the very first time, the corresponding initial value is assigned before the modification is applied. 🌱

This mechanism applies to all path-like environment variable management modulefile commands and module sub-commands (append-path, prepend-path and remove-path).

When an entry gets removed from an environment variable, the variable is unset if its resulting value matches the configured initial value and no explicit reference counter is associated with it. 💖

This value overrides the default from the init_envvars configuration option, and you can define it with the config sub-command.

MODULES_LINKED_ENVVARS — a colon-separated list of environment variable link sets. Each link set is a group of environment variable names separated by the ampersand character. When an environment variable modification command gets applied to the first variable in a link set, the same command is automatically applied to all the other variables in that set. 🔗

This link mechanism applies to all environment variable management modulefile commands and module sub-commands (append-path, prepend-path, pushenv, remove-path, setenv and unsetenv).

For example, if the configuration option is set to FOO&BAR&BAZ:BAR&QUX, a prepend-path command applied to FOO will also be applied to BAR, BAZ, and QUX. Linking is not reflexive though — a command applied to QUX is not propagated to any other environment variable in the link set. 🌀

This value overrides the default from the linked_envvars configuration option, and you can define it with the config sub-command.

MODULES_LIST_OUTPUT — a colon separated list of the elements to report in addition to module names on the list sub-command regular output mode. 🎀

Accepted elements you can set in the value list are:

alias: module aliases targeting loaded modules.
header: sentence to introduce the list of loaded modules or to state that no modules are loaded currently.
hidden: show hidden loaded modules.
idx: index position of each loaded module.
indesym: symbolic versions reported independently from the loaded module they're attached to.
key: legend appended at the end of the output to explain it.
variant: variant values selected for loaded modules.
sym: symbolic versions associated with loaded modules.
tag: tags associated with loaded modules.

The order of the elements in the list genuinely does not matter, bestie. Module names are the only content reported when LIST is set to an empty value. 🤷‍♀️

This value overrides the default from the list_output configuration option, and you can define it with the config sub-command. The --output/-o command line switches override this environment variable.

MODULES_LIST_TERSE_OUTPUT — a colon separated list of the elements to report in addition to module names on the list sub-command terse output mode. ✨

Peep MODULES_LIST_OUTPUT for the accepted elements you can set in the value list.

The order of the elements in the list does not matter. Module names are the only content reported when LIST is set to an empty value.

This value overrides the default from the list_terse_output configuration option, and you can define it with the config sub-command. The --output/-o command line switches override this environment variable.

MODULES_LOGGED_EVENTS — a colon separated list of the events to log. 📝 Accepted events you can set in the value list are:
- auto_eval: log automatically triggered modulefile evaluations
requested_eval — logs modulefile evaluations that were directly requested by the user (like, the actual thing they typed)
- requested_cmd — logs module commands that were directly requested by the user

This environment variable value supersedes the default value set in the logged_events configuration option. It can be defined with the config sub-command. Ngl though — this environment variable is ignored if logged_events has been declared locked in the locked_configs configuration option 🙈.

MODULES_LOGGER

The command used to log informational messages. The value of this variable is composed of a logger command name or path, eventually followed by command-line options 💅.

This environment variable value supersedes the default value set in the logger configuration option. It can be defined with the config sub-command. It's ignored if logger has been declared locked in the locked_configs configuration option.

If MODULES_LOGGER is set to an empty string, logger will not be launched. Periodt.

MODULES_MCOOKIE_CHECK

If set to eval, the Modules magic cookie (that's the #%Module file signature, bestie) is only checked to determine if a file is a modulefile when evaluating these files. If set to always, the Modules magic cookie is also checked when searching for modules.

The eval mode is made to significantly reduce file checks when walking through modulepaths to search for modulefiles. Special care should be given to the content of modulepaths when this eval mode is set, because the following kinds of files are included in search results ✨:

modulefiles with a magic cookie requiring a higher version of modulecmd.tcl
files not beginning with the magic cookie #%Module
read-protected files

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

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

MODULES_MCOOKIE_VERSION_CHECK

If set to 1, the version set in the Modules magic cookie in a modulefile is checked against the current version of modulecmd.tcl to determine if the modulefile can be evaluated.

When a module cache file is available for a given modulepath, version check is considered enabled, since cache content is generated in this mode.

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

MODULES_ML

If set to 1, define the ml command when initializing Modules (see the Package Initialization section). If set to 0, the ml command is not defined.

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

To enable or disable the ml command, MODULES_ML should be set prior to Modules initialization, or the ml configuration option should be set in the initrc configuration file. Timing is everything, iykyk 🕐.

MODULES_MODULEPATH_IGNORE

If set to 0, do not apply modulepath-ignore pattern definitions: every element of the modulepath directories is walked through and checked as if no pattern were defined.

This environment variable supersedes the default value of the modulepath_ignore configuration option. Patterns can be skipped for one command execution with the --no-modulepath-ignore command line switch.

MODULES_NEARLY_FORBIDDEN_DAYS

The number of days a module is considered nearly forbidden prior to reaching its expiry date set by the module-forbid modulefile command. When a nearly forbidden module is evaluated, a warning message is issued to inform that the module will soon be forbidden 😭. If set to 0, modules will never be considered nearly forbidden. Accepted values are integers comprised between 0 and 365.

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

MODULES_NON_EXPORTABLE_TAGS

A colon separated list of tags that should not be exported to the module once it is loaded.

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

The text viewer used to paginate message output. The value of this variable is composed of a pager command name or path, eventually followed by command-line options. See MODULES_PAGINATE to learn how pagination is enabled 👀.

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

MODULES_PAGINATE

If set to 1, the output of the module command is piped into the defined pager command. See the MODULES_PAGER variable for pager command definition.

Pagination is automatically disabled in the following situations, no cap:

MODULES_PAGER variable is set to an empty string or to the value cat.
modulecmd.tcl program is run for scripting language rather than shells.
modulecmd.tcl error output stream is not attached to a terminal.
clear or edit sub-commands are run.

The MODULES_PAGINATE environment variable value supersedes the default value set in the paginate configuration option. It can be defined with the config sub-command. The --paginate/-p and --no-pager/-P command line switches override this environment variable 🔥.

MODULES_PATH_ENTRY_REORDER

This environment variable changes the behavior of the prepend-path, append-path and module use modulefile commands and sub-commands.

If set to 1, and one of these commands targets a path entry that already exists in the environment variable, the entry is moved to the beginning or end (depending on the command), unless duplicates are allowed. If set to 0, the environment variable is not modified when the entry already exists.

$ module config path_entry_reorder 0
$ module append-path PATHVAR /foo
$ module append-path PATHVAR /bar
$ module append-path PATHVAR /foo
$ echo $PATHVAR
/foo:/bar
$ module config path_entry_reorder 1
$ module append-path PATHVAR /foo
$ echo $PATHVAR
/bar:/foo
$ module append-path --duplicates PATHVAR /bar
$ echo $PATHVAR
/bar:/foo:/bar

MODULES_PROTECTED_ENVVARS

A colon separated list of environment variable names that should not be modified by any modulefile command 🛡️.

This prevents modifications by append-path, prepend-path, remove-path, setenv and unsetenv. When these modulefile commands attempt to modify a protected environment variable, a warning message is emitted and the modification is ignored.

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

MODULES_QUARANTINE_SUPPORT

If set to 1, produces the shell code for the quarantine mechanism when the autoinit sub-command generates the module shell function.

The generated shell code for the quarantine mechanism indirectly passes the environment variable defined in MODULES_RUN_QUARANTINE to the modulecmd.tcl script, to protect its run-time environment from side-effects coming from the current definition of these variables 🧚.

To enable quarantine support, MODULES_QUARANTINE_SUPPORT should be set to 1 prior to Modules initialization, or the quarantine_support configuration should be set to 1 in the initrc configuration file. Again with the timing thing, bestie.

The generated code for the quarantine mechanism sets the __MODULES_QUARANTINE_SET environment variable when calling the modulecmd.tcl script, to make it restore the environment variables put in quarantine.

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

MODULES_REDIRECT_OUTPUT

If set to 0, the output generated by the module command is kept on stderr and not redirected to the stdout channel.

This environment variable value supersedes the default value set in the redirect_output configuration option. It can be defined with the config sub-command. The --redirect and --no-redirect command line switches override this environment variable.

MODULES_REQUIRE_VIA

If set to 1, consider a loaded module that enables a modulepath (through the use of the modulefile commands module use, append-path MODULEPATH, or prepend-path MODULEPATH) to be a requirement for loaded modules stored in this modulepath. If set to 0, no dependency is made between these modules.

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

MODULES_RESET_TARGET_STATE

Defines the behavior of the reset sub-command 🌈. When set to __init__, the initial environment is restored. When set to __purge__, reset performs a purge sub-command. Any other value designates a name collection to restore.

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

MODULES_RUN_QUARANTINE

A space separated list of environment variable names that should be passed indirectly to modulecmd.tcl to protect its run-time environment from side-effects coming from their current definition 💜.

So like, if the quarantine mechanism made it into the module shell function (peep MODULES_QUARANTINE_SUPPORT), then every variable you find chillin' in MODULES_RUN_QUARANTINE gets its value emptied out — or set to whatever the matching MODULES_RUNENV_<VAR> variable says — when modulecmd.tcl is defining its run-time environment. 💅

The original values of those quarantined environment variables get passed over to modulecmd.tcl through __MODULES_QUAR_<VAR> variables. iykyk.

Also, every variable found in MODULES_RUN_QUARANTINE gets set in quarantine by modulecmd.tcl while it's creating the Tcl sub-interpreters used to evaluate modulercs and modulefiles. During that creation step the variables get unset or set to the value of their corresponding MODULES_RUNENV_<VAR> variable, and then their original value gets restored. Why? It protects sub-interpreter initialization from side-effects coming from the current definition of these variables (like, say, a TCL_LIBRARY variable pointing at a broken Tcl installation 😭).

This environment variable's value supersedes the default value set in the run_quarantine configuration option. You can define it with the config sub-command. ✨

`MODULES_RUNENV_<VAR>`

The value to set the environment variable <VAR> to for modulecmd.tcl run-time execution, if <VAR> is referred to in MODULES_RUN_QUARANTINE. 🎀

`MODULES_SEARCH_MATCH`

When you're searching for modules with avail, list, spider, or collections with savelist sub-commands, this defines the way the query string should match against available module/collection names. With the starts_with value, the modules/collections returned are the ones whose name begins with the search query string. When it's set to contains, any modules/collections whose fully qualified name contains the search query string get returned. 🔍

This environment variable's value supersedes the default value set in the search_match configuration option. You can define it with the config sub-command. And heads up: the --starts-with and --contains command line switches override this environment variable. 👑

`MODULES_SET_SHELL_STARTUP`

If set to 1, this defines when the module command initializes the shell startup file, so that the module command is still defined in sub-shells. Setting the shell startup file means defining the ENV and BASH_ENV environment variables to the Modules bourne shell initialization script. If set to 0, the shell startup file is not defined. 🐚

This environment variable's value supersedes the default value set in the set_shell_startup configuration option. You can define it with the config sub-command.

To enable the shell startup file, MODULES_SET_SHELL_STARTUP should be set to 1 prior to Modules initialization — or the set_shell_startup configuration option should be set to 1 in the initrc configuration file. Timing matters, bestie. ⏰

`MODULES_SHELLS_WITH_KSH_FPATH`

A list of shells on which the FPATH environment variable should be defined at initialization time, pointing to the ksh-functions directory where the ksh initialization script for the module command lives. It lets the listed shells get the module function defined when starting ksh as a sub-shell from there. ✨

Accepted values are a list of shells among sh, bash, csh, tcsh and fish, separated by the colon character (:).

This environment variable's value supersedes the default value set in the shells_with_ksh_fpath configuration option. You can define it with the config sub-command.

To enable the setup of FPATH for some shells, MODULES_SHELLS_WITH_KSH_FPATH should be set to the list of those shells prior to Modules initialization — or the shells_with_ksh_fpath configuration option should be set to the list of those shells in the initrc configuration file. 🫶

`MODULES_SILENT_SHELL_DEBUG`

If set to 1, this disables any xtrace or verbose debugging property set on the current shell session for the duration of either the module command or the module shell initialization script. Lowkey only applies to Bourne Shell (sh) and its derivatives. 🙈

This environment variable's value supersedes the default value set in the silent_shell_debug configuration option. You can define it with the config sub-command.

To generate the code that silences the shell debugging property in the module shell function, MODULES_SILENT_SHELL_DEBUG should be set to 1 prior to Modules initialization — or the silent_shell_debug configuration option should be set to 1 in the initrc configuration file. 🤫

`MODULES_SITECONFIG`

The location of a site-specific configuration script to source into modulecmd.tcl. See the Site-specific configuration section for the deets. 📍

This environment variable's value supersedes the default value set in the extra_siteconfig configuration option. You can define it with the config sub-command. But this environment variable is ignored if extra_siteconfig has been declared locked in the locked_configs configuration option. Locked is locked, no cap. 🔒

`MODULES_SOURCE_CACHE`

If set to 1, this caches the content of files evaluated in a modulefile through the source(n) Tcl command. When the same file gets sourced multiple times, the cached content is reused instead of reading the file again. ♻️

This environment variable's value supersedes the default value set in the source_cache configuration option. You can define it with the config sub-command.

`MODULES_SPIDER_INDEPTH`

If set to 1, this enables in-depth search results for the spider sub-command. If set to 0, it disables the spider sub-command in-depth mode. Other values are ignored. 🕷️

When in-depth mode is enabled, modulefiles and directories contained in directories matching the search query are also included in the search results. When disabled, those modulefiles and directories contained in matching directories are excluded.

This environment variable's value supersedes the default value set in the spider_indepth configuration option. You can define it with the config sub-command. The --indepth and --no-indepth command line switches override this environment variable. 💅

`MODULES_SPIDER_OUTPUT`

A colon-separated list of the elements to report in addition to module names on the spider sub-command regular output mode. 🎀

Accepted elements you can set in the value list are:

alias — module aliases.
provided-alias — show module aliases and evaluate all modulefiles to get the aliases provided by them.
dirwsym — directories associated with symbolic versions.
hidden — show all hidden modules.
indesym — symbolic versions reported independently from the module or directory they're attached to.
key — a legend appended at the end of the output to explain it.
modulepath — modulepath names set as a header prior to the list of available modules found in them.
sym — symbolic versions associated with available modules.
tag — tags associated with available modules.
variant — variants and their possible values associated with available modules.
variantifspec — like variant, but only if a variant has been specified in the search query.
via — a mention next to the modulepath name saying which module enables it, if any.

The order of the elements in the list doesn't matter. Module names are the only content reported when LIST is set to an empty value. 🫶

In case the modulepath element is missing from the value list, the available modules from global/user rc and all enabled modulepaths are reported as a single list.

When the indesym element is set, the dirwsym and sym elements are disabled. ⚠️

This environment variable's value supersedes the default value set in the spider_output configuration option. You can define it with the config sub-command. The --output/-o command line switches override this environment variable. 👑

`MODULES_SPIDER_TERSE_OUTPUT`

A colon-separated list of the elements to report in addition to module names on the spider sub-command terse output mode. ✨

See MODULES_SPIDER_OUTPUT for the accepted elements you can set in the value list — with the exception of the via element, which is not accepted for terse output mode. 🙅‍♀️

The order of the elements in the list doesn't matter. Module names are the only content reported when LIST is set to an empty value.

This environment variable's value supersedes the default value set in the spider_terse_output configuration option. You can define it with the config sub-command. The --output/-o command line switches override this environment variable. 💖

`MODULES_STICKY_PURGE`

When unloading a sticky or super-sticky module during a module purge, this decides whether to raise an error, emit a warning message, or be silent. 😤

It also applies to the skipped unload of modules required — directly or indirectly — by a retained sticky or super-sticky module.

This environment variable's value supersedes the default value set in the sticky_purge configuration option. You can define it with the config sub-command.

`MODULES_TAG_ABBREV`

Specifies the abbreviation strings used to report module tags (see the Module tags section). Its value is a colon-separated list of module tag names associated to an abbreviation string (e.g. tagname=abbrev). 🏷️

If a tag is associated to an empty string abbreviation, that tag will not be reported. In case the whole MODULES_TAG_ABBREV environment variable is set to an empty string, tags are reported but not abbreviated. Wild, but okay. 💀

This environment variable's value supersedes the default value set in the tag_abbrev configuration option. You can define it with the config sub-command.

`MODULES_TAG_COLOR_NAME`

Specifies the tag names or abbreviations whose graphical rendering should be applied over themselves instead of being applied over the name of the module they're attached to. The value of MODULES_TAG_COLOR_NAME is a colon-separated list of module tag names or abbreviation strings (see the Module tags section). 🌈

Okay so, when a select graphic rendition is defined for a tag name or tag abbreviation string, it is applied over the module name associated with the tag, and the tag name or abbreviation is not displayed. But when it’s listed in MODULES_TAG_COLOR_NAME environment variable, a tag name or abbreviation is displayed, and the select graphic rendition is applied over it. 💅

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

🧚 `MODULES_TCL_LINTER` 🧚

Command name or path for use to check syntax of modulefile through the lint sub-command.

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

🌸 `MODULES_TERM_BACKGROUND` 🌸

Inform Modules of the terminal background color to determine if the color set for dark background or the color set for light background should be used to color output in case no specific color set is defined with the MODULES_COLORS variable. Accepted values are dark and light.

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

🦋 `MODULES_TERM_WIDTH` 🦋

Specifies the number of columns of the output. If set to 0, the output width will be the full terminal width, which is automatically detected by the module command. Accepted values are integers comprised between 0 and 1000.

This environment variable value supersedes the default value set in the term_width configuration option. It can be defined with the config sub-command. The --width/-w command line switches override this environment variable. 💖

👑 `MODULES_UNIQUE_NAME_LOADED` 👑

If set to 1, allows only one module loaded per module name. A conflict is raised when loading a module whose name or alternative names are shared by an already loaded module.

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

🌈 `MODULES_UNLOAD_MATCH_ORDER` 🌈

When a module unload request matches multiple loaded modules, unload firstly loaded module or lastly loaded module. Accepted values are returnfirst and returnlast.

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

💜 `MODULES_VARIANT_SHORTCUT` 💜

Specifies the shortcut characters that could be used to specify and report module variants (see Module variants section). Its value is a colon-separated list of variant names associated to a shortcut character (e.g., variantname=shortcutchar).

A variant shortcut must be of one character length and must avoid characters used for other concerns or in module names or version specifications (i.e., [-+~/@=:,a-zA-Z0-9]).

If a shortcut is associated to an empty string or an invalid character, this shortcut definition will be ignored.

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

🍓 `MODULES_VERBOSITY` 🍓

Defines the verbosity level of the module command. Available verbosity levels from the least to the most verbose are:

silent — turn off error, warning and informational messages but does not affect module command output result.
concise — enable error and warning messages but disable informational messages.
normal — turn on informational messages, like a report of the additional module evaluations triggered by loading or unloading modules, aborted evaluation issues or a report of each module evaluation occurring during a restore or source sub-commands.
verbose — add additional informational messages, like a systematic report of the loading or unloading module evaluations.
verbose2 — report loading or unloading module evaluations of hidden-loaded modules, report if loading module is already loaded or if unloading module is not loaded.
trace — provide details on module searches, resolutions, selections and evaluations.
debug — print debugging messages about module command execution.
debug2 — report modulecmd.tcl procedure calls in addition to printing debug messages.

This environment variable value supersedes the default value set in the verbosity configuration option. It can be defined with the config sub-command. The --silent, --verbose, --debug and --trace command line switches override this environment variable. 💅

💀 `MODULES_WA_277` 💀

If set to 1 prior to Modules package initialization, enables workaround for Tcsh history issue (see <https://github.com/envmodules/modules/issues/277>). This issue leads to erroneous history entries under Tcsh shell. When workaround is enabled, an alternative module alias is defined which fixes the history mechanism issue. However the alternative definition of the module alias weakens shell evaluation of the code produced by modulefiles. Characters with a special meaning for Tcsh shell (like { and }) may not be used anymore in shell alias definition otherwise the evaluation of the code produced by modulefiles will return a syntax error.

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

To enable this workaround, MODULES_WA_277 should be set to 1 prior Modules initialization or the wa_277 configuration option should be set to 1 in the initrc configuration file. 🙈

🏠 `MODULESHOME` 🏠

The location of the main Modules package file directory containing module command initialization scripts, the executable program modulecmd.tcl, and a directory containing a collection of main modulefiles.

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

🌸 FILES 🌸

/usr/share/Modules — the MODULESHOME directory.
/etc/environment-modules/initrc — the configuration file evaluated by modulecmd.tcl when it initializes to enable the default modulepaths, load the default modules and set module command configuration. initrc is a modulefile <#modulefile-5>, so it is written as a Tcl script and defines modulepaths to enable with module use <#mfcmd-module>, modules to load with module load <#mfcmd-module> and configuration to apply with module config. Like any modulefile, initrc must begin with the Modules magic cookie (i.e., #%Module file signature). initrc is optional. When this configuration file is present it is evaluated after the modulespath configuration file. See the Package Initialization section for details. ✨
/etc/environment-modules/modulespath — the configuration file evaluated by modulecmd.tcl when it initializes to enable the default modulepaths. This file contains the list of modulepaths separated by either newline or colon characters. modulespath is optional. When this configuration file is present it is evaluated before the initrc configuration file. See the Package Initialization section for details.
/etc/environment-modules/siteconfig.tcl — the site-specific configuration script of modulecmd.tcl. An additional configuration script could be defined using the MODULES_SITECONFIG environment variable. See Site-specific configuration for detailed information.
/etc/environment-modules/rc — the system-wide modules rc file. The location of this file can be changed using the MODULERCFILE environment variable as described above.
$HOME/.modulerc — the user specific modules rc file.
$HOME/.module — the user specific collection directory.
/usr/share/Modules/modulefiles — the directory for system-wide modulefiles. The location of the directory can be changed using the MODULEPATH environment variable as described above.
<modulepath>/.modulerc — Modulepath-specific module rc file.
<modulepath>/.modulecache — Modulepath-specific module cache file.
/usr/share/Modules/libexec/modulecmd.tcl — Modules execution engine, interpreting modulefile upon each invocation of module.
@bindir@/modulecmd — Generic wrapper command pointing to Modules execution engine.
/usr/share/Modules/init/<shell> — the Modules package initialization file sourced into the user’s environment. 🎀

🦋 SEE ALSO 🦋

envml <#envml-1>
ml <#ml-1>
modulecmd <#modulecmd-1>
modulefile <#modulefile-5>

🎀 Copyright 🎀

1996-2026, Modules Contributors

That’s the whole manual page, bestie! 💖 MODULE(1), version 5.7.0, dated 2026-09-21 — slay and goodbye! 💅✨

📦 where this page comes from

centos-stream 10: environment-modules 5.7.0-1.el10 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

MODULE(1)

✨ MODULE(1) ✨ — the module command, bestie edition 💅

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

💖 DESCRIPTION 💖

🧚 Package Initialization 🧚

🍓 Examples of initialization 🍓

🧁 Modulecmd startup 🧁

💅 Command line switches 💅

🎀 Module Sub-Commands 🎀

add [options] modulefile...

add-any [options] modulefile...

aliases [-a]

append-path [options] variable value...

apropos [-a] [-j] string

avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]

cachebuild [modulepath...]

cacheclear

clear [-f]

🎀 modulepath_ignore

🌸 nearly_forbidden_days

🦋 non_exportable_tags

💅 pager

✨ paginate

🧚 path_entry_reorder

🔒 protected_envvars

🌈 quarantine_support

🎀 rcfile

💜 redirect_output

⭐ require_via

🫶 reset_target_state

🍓 run_quarantine

👑 search_match

🐚 set_shell_startup

💀 shells_with_ksh_fpath

🤫 silent_shell_debug

🌸 siteconfig

🦋 source_cache

info-loaded modulefile

initadd modulefile...

initclear

initlist

initprepend modulefile...

initrm modulefile...

initswitch modulefile1 modulefile2

is-avail modulefile...

is-loaded [modulefile...]

is-saved [collection...]

is-used [directory...]

keyword [-a] [-j] string

lint [-a] [modulefile...]

list [-t|-l|-j] [-a] [-o LIST] [-S|-C] [pattern...]

load [options] modulefile...

load-any [options] modulefile...

mod-to-sh [options] shell modulefile...

🦋 path modulefile

🎀 paths pattern

💖 prepend-path [options] variable value...

🔥 purge [-f]

⭐ refresh

🌸 reload [-f]

🧚 remove [--auto|--no-auto] [-f] modulefile...

🍓 remove-path [options] variable value...

💜 reset [-f]

🌟 restore [-f] [collection]

🎀 rm [--auto|--no-auto] [-f] modulefile...

👑 save [collection]

🦋 savelist [-t|-l|-j] [-a] [-S|-C] [pattern...]

saverm [collection]

saveshow [collection]

search [-a] [-j] string

sh-to-mod shell script [arg...]

Note

show modulefile...

source [options] modulefile...

spider [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]

stash [-f]

stashclear

stashlist [-t|-l|-j]

stashpop [-f] [stash]

✨ MODULE(1) ✨ — the `module` command, bestie edition 💅

`add [options] modulefile...`

`add-any [options] modulefile...`

`aliases [-a]`

`append-path [options] variable value...`

`apropos [-a] [-j] string`

`avail [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]`

`cachebuild [modulepath...]`

`cacheclear`

`clear [-f]`

🎀 `modulepath_ignore`

🌸 `nearly_forbidden_days`

🦋 `non_exportable_tags`

💅 `pager`

✨ `paginate`

🧚 `path_entry_reorder`

🔒 `protected_envvars`

🌈 `quarantine_support`

🎀 `rcfile`

💜 `redirect_output`

⭐ `require_via`

🫶 `reset_target_state`

🍓 `run_quarantine`

👑 `search_match`

🐚 `set_shell_startup`

💀 `shells_with_ksh_fpath`

🤫 `silent_shell_debug`

🌸 `siteconfig`

🦋 `source_cache`

`info-loaded` modulefile

`initadd` modulefile...

`initclear`

`initlist`

`initprepend` modulefile...

`initrm` modulefile...

`initswitch` modulefile1 modulefile2

`is-avail` modulefile...

`is-loaded` [modulefile...]

`is-saved` [collection...]

`is-used` [directory...]

`keyword` [`-a`] [`-j`] string

`lint` [`-a`] [modulefile...]

`list` [`-t`|`-l`|`-j`] [`-a`] [`-o` LIST] [`-S`|`-C`] [pattern...]

`load` [options] modulefile...

`load-any` [options] modulefile...

`mod-to-sh` [options] shell modulefile...

🦋 `path` modulefile

🎀 `paths` pattern

💖 `prepend-path` [options] variable value...

🔥 `purge` [`-f`]

⭐ `refresh`

🌸 `reload` [`-f`]

🧚 `remove` [`--auto`|`--no-auto`] [`-f`] modulefile...

🍓 `remove-path` [options] variable value...

💜 `reset` [`-f`]

🌟 `restore` [`-f`] [collection]

🎀 `rm` [`--auto`|`--no-auto`] [`-f`] modulefile...

👑 `save` [collection]

🦋 `savelist` [`-t`|`-l`|`-j`] [`-a`] [`-S`|`-C`] [pattern...]

`saverm` [collection]

`saveshow` [collection]

`search [-a] [-j] string`

`sh-to-mod shell script [arg...]`

`show modulefile...`

`source [options] modulefile...`

`spider [-d|-L] [-t|-l|-j] [-a] [-o LIST] [-S|-C] [--indepth|--no-indepth] [pattern...]`

`stash [-f]`

`stashclear`

`stashlist [-t|-l|-j]`

`stashpop [-f] [stash]`

`stashrm [stash]`

`stashshow [stash]`

`_LMFILES_`

`LOADEDMODULES`

`MODULECONTACT`

`MODULEPATH`

`MODULERCFILE`

`MODULES_ABORT_ON_ERROR`

`MODULES_ADVANCED_VERSION_SPEC`

`MODULES_AUTO_HANDLING`