.. _user-guide:
Lesser known features
=====================
Environment Modules provides many capabilities beyond the commonly used
:command:`module` :subcmd:`load` command. Some features are lesser known, despite being very
useful for users, modulefile developers, and site administrators.
This document gathers and explains a selection of these features through
practical examples and common use cases.
It originates from the presentation *Beyond "module load": Exploring the
Capabilities of Environment Modules* given at `HPSFCon 2026
`_. Original slides and video
demonstrations can be found on the `event session page
`_.
Short command names
-------------------
Most Modules sub-commands can be abbreviated. The :command:`ml` command also
provides a shorter alternative interface for common operations.
.. list-table::
:header-rows: 1
:widths: 50 50
* - Standard command
- Short form
* - ``module ``
- ``ml ``
* - ``module avail``
- ``module av``
* - ``module purge``
- ``module pu``
* - ``module list``
- ``ml``
* - ``module load ``
- ``ml ``
* - ``module unload ``
- ``ml -``
Display/Parsing
---------------
``--output=LIST``
^^^^^^^^^^^^^^^^^
The :option:`--output`, or :option:`-o`, option customizes the information
displayed by Modules commands.
It is supported by :command:`module` :subcmd:`avail`, :subcmd:`list`, and
:subcmd:`spider` sub-commands.
By default, these commands display additional formatting elements such as
modulepaths, tags, default markers, or variant information. With
:option:`--output`, it is possible to restrict the displayed information to
only the needed fields.
This option is especially useful when parsing command output in shell scripts,
Python programs, or monitoring tools.
For example, with the following available modulefiles:
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/8.3 :sgrde:`gcc/11.1` gcc/14.0 openmpi/5.0.8
When *LIST* is set to an empty value, only module names are displayed:
.. parsed-literal::
:ps:`$` module avail -o ''
gcc/8.3 gcc/11.1 gcc/14.0 openmpi/5.0.8
The output format is defined as a colon-separated list of elements. Supported
elements are documented in the corresponding sub-command manual pages.
*LIST* may also be prefixed by ``+`` or ``-`` to respectively append elements
to or subtract them from the currently configured value. For example, report
the variants declared by each modulefile in addition to the default output:
.. parsed-literal::
:ps:`$` module avail -o +variant
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/8.3 :sgrde:`gcc/11.1` gcc/14.0 openmpi/5.0.8\ :sgrse:`{`:sgrva:`cuda=on`:sgrse:`,`\ :sgrva:`off`:sgrse:`}`
This feature helps avoid fragile text parsing pipelines.
Instead of parsing formatted output:
.. code-block:: bash
modules_list=$(module avail | grep -v '^---' \
| sed 's/(default)//g' | head -n -2 | xargs)
A simpler and more robust approach is:
.. code-block:: bash
modules_list=$(module avail -o '')
``spider``
^^^^^^^^^^
The :command:`module` :subcmd:`spider` sub-command lists all available
modulefiles found in enabled modulepaths, including modulepaths recursively
added by modulefiles.
Unlike :subcmd:`avail`, :subcmd:`spider` explores the full dependency tree
created by :mfcmd:`module use`, :mfcmd:`append-path`, or
:mfcmd:`prepend-path` instructions.
This command is especially useful with hierarchical module layouts, where some
modulefiles only become visible after loading compiler or MPI dependencies.
The :subcmd:`spider` sub-command accepts the same display and formatting
options as :subcmd:`avail`, including :option:`--output`,
:option:`--latest`, :option:`--default`, :option:`--json`,
:option:`--indepth`, and :option:`--no-indepth`.
For example, in a hierarchical environment:
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles/common` ------------------
gcc/14.0 intel/25.0
Only compiler modules are initially visible.
The :subcmd:`spider` sub-command reveals additional modules together with
their dependency path:
.. parsed-literal::
:ps:`$` module spider
------------------- :sgrmp:`/usr/share/modulefiles/common` ------------------
gcc/14.0 intel/25.0
---------- :sgrmp:`/usr/share/modulefiles/intel` (via intel/25.0) -----------
intelmpi/25.0
------------ :sgrmp:`/usr/share/modulefiles/gcc` (via gcc/14.0) -------------
openmpi/5.0.8
This output indicates which modules must be loaded before these MPI stacks
become available.
Modules caches are automatically used by :subcmd:`spider` when configured,
which significantly improves search performance on large installations.
``--latest`` and ``--default``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :option:`--latest`, or :option:`-L`, and :option:`--default`, or
:option:`-d`, options restrict the output of the :command:`module`
:subcmd:`avail` and :subcmd:`spider` sub-commands.
For example, with the following available modulefiles:
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/8.3 :sgrde:`gcc/11.1` gcc/14.0 intel/24.0 intel/25.0
The :option:`--latest` option displays only the highest numerically sorted
version of each module name.
.. parsed-literal::
:ps:`$` module avail --latest
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/14.0 intel/25.0
The :option:`--default` option displays only the default version of each
module name. This version is either explicitly defined (as here for ``gcc``)
or implicitly the highest one (as for ``intel``).
.. parsed-literal::
:ps:`$` module avail --default
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
:sgrde:`gcc/11.1` intel/25.0
These options may also be combined with other display options such as
:option:`--output` or :option:`--json`.
``--indepth`` and ``--no-indepth``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :option:`--indepth` and :option:`--no-indepth` options control how the
:command:`module` :subcmd:`avail` and :subcmd:`spider` sub-commands search
for matching modulefiles.
By default, Modules searches recursively and returns all matching
modulefiles. This behavior is equivalent to :option:`--indepth` and
can be configured with :command:`module` :subcmd:`config` :mconfig:`avail_indepth`
and :mconfig:`spider_indepth`.
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
intel/24.0 intel/25.0 gcc/8.3 gcc/11.1 gcc/14.0
The :option:`--no-indepth` option limits results to the depth level
expressed by the search query. Modulefiles contained in matching directories
are not displayed.
.. parsed-literal::
:ps:`$` module avail --no-indepth
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
:sgrdi:`intel`/ :sgrdi:`gcc`/
``--json``
^^^^^^^^^^
The :option:`--json`, or :option:`-j`, option displays command results in
JSON format.
It is supported by the :command:`module` :subcmd:`avail`, :subcmd:`list`,
:subcmd:`savelist`, :subcmd:`search`, :subcmd:`spider`,
:subcmd:`stashlist`, and :subcmd:`whatis` sub-commands.
JSON output is intended for machine consumption and can be processed directly
by tools such as ``jq`` or Python scripts.
.. parsed-literal::
:ps:`$` module avail -j | jq .
{
"/usr/share/modulefiles": {
"gcc/14.0": {
"name": "gcc/14.0",
"type": "modulefile",
"symbols": [],
"tags": [],
"pathname": "/usr/share/modulefiles/gcc/14.0",
"via": ""
},
...
}
The JSON format is also useful for monitoring, reporting, and integration
with external tools.
Manipulating the environment for users
--------------------------------------
Collections
^^^^^^^^^^^
Collections save and restore sets of loaded modules.
They provide a convenient way to switch between software environments without
having to manually load and unload each module.
Collections are managed through several :command:`module` sub-commands:
.. list-table::
:header-rows: 1
:widths: 30 70
* - Sub-command
- Description
* - :subcmd:`save` [collection]
- Save the current module environment to a collection.
* - :subcmd:`restore` [collection]
- Restore a collection or collection file.
* - :subcmd:`savelist`
- List saved collections.
* - :subcmd:`saverm` [collection]
- Remove a saved collection.
* - :subcmd:`saveshow` [collection]
- Display information about a collection.
* - :subcmd:`is-saved` [collection]
- Test whether one or more collections exist.
Collections are stored under the user collection directory, usually
:file:`$HOME/.module`.
The :envvar:`MODULES_COLLECTION_TARGET` environment variable may be defined
to append a suffix to collection names. This feature is particularly useful
on systems sharing a common home directory across multiple clusters.
.. parsed-literal::
:ps:`$` module save
:ps:`$` module purge
:ps:`$` module restore
``stash`` commands
^^^^^^^^^^^^^^^^^^
Stash collections temporarily save the current module environment and make it
easy to switch to another environment.
This feature is similar to the :command:`git stash` workflow: save the current
state, perform other work, then restore the original environment later.
Stash collections are managed through several :command:`module`
sub-commands:
.. list-table::
:header-rows: 1
:widths: 30 70
* - Sub-command
- Description
* - :subcmd:`stash`
- Save the current environment and reset it.
* - :subcmd:`stashpop`
- Restore and remove a stash collection.
* - :subcmd:`stashrm`
- Remove a stash collection.
* - :subcmd:`stashshow`
- Display information about a stash collection.
* - :subcmd:`stashclear`
- Remove all stash collections.
* - :subcmd:`stashlist`
- List stash collections.
Save the current environment:
.. parsed-literal::
:ps:`$` module stash
Load a different software stack:
.. parsed-literal::
:ps:`$` module purge
:ps:`$` module load ...
Restore the original environment:
.. parsed-literal::
:ps:`$` module stashpop
Unlike regular collections, stash collections are intended to be short-lived
and are automatically removed when restored with
:subcmd:`stashpop`.
``mogui``
^^^^^^^^^
``mogui`` provides a graphical interface to browse available modules and
manage collections.
It offers an alternative to the command line and can be useful for new users
discovering a software stack or for users who prefer an interactive
interface.
Any environment change made from the GUI, such as loading modules or
restoring collections, is applied back to the shell session that launched
the application.
The project is available on GitHub:
`cea-hpc/mogui `_. It can be installed
from PyPI with :command:`pip` or from Spack.
.. parsed-literal::
:ps:`$` pip install modules-gui
or:
.. parsed-literal::
:ps:`$` spack install py-modules-gui
Then start the graphical interface:
.. parsed-literal::
:ps:`$` mogui
.. image:: https://raw.githubusercontent.com/cea-hpc/mogui/main/doc/sneak_peek.gif
:alt: mogui graphical interface
:align: center
``envml``
^^^^^^^^^
The :ref:`envml(1)` command executes a command in a specific module
environment.
It applies the requested module actions, executes the command, then restores
the original environment. As a result, the current shell session remains
unchanged.
This feature is particularly useful in scripts, tests, and automation
workflows where commands must be executed in a controlled software
environment.
Supported module actions include:
.. list-table::
:header-rows: 1
:widths: 35 65
* - Action
- Description
* - ``purge``
- Purge all loaded modules.
* - ``restore=``
- Restore a saved collection.
* - ``unload=``
- Unload one or more modules.
* - ``switch=&``
- Switch from one module to another.
* - ``load=``
- Load one or more modules.
* - ````
- Shorthand form of ``load=``.
Multiple actions may be chained with the ``:`` separator. When specifying
multiple modules for a single action, use the ``&`` separator. In some
shells, such as Bash, the ``&`` character must be escaped or quoted.
For example, execute a command in a clean environment:
.. parsed-literal::
:ps:`$` envml purge -- gcc hello.c
The :ref:`envml(1)` command can simplify scripts by replacing sequences of
module operations with a single command.
Instead of:
.. code-block:: bash
#!/bin/bash
module purge
module load gcc
gcc hello.c
One can write:
.. code-block:: bash
#!/bin/bash
envml purge:gcc -- gcc hello.c
Protected environment variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :mconfig:`protected_envvars` configuration option prevents Modules from
modifying selected environment variables. Multiple variables may be specified
using the ``:`` separator.
This feature is useful to protect critical environment settings from
unintended changes.
When a modulefile attempts to modify a protected variable, Modules ignores
the modification and emits a warning.
.. parsed-literal::
:ps:`$` module config protected_envvars LD_PRELOAD
:ps:`$` module load intel
Loading :sgrhi:`intel/25.0`
:sgrwa:`WARNING`: Modification of protected environment variable LD_PRELOAD ignored
Developing and configuring modulefiles
--------------------------------------
``module edit``
^^^^^^^^^^^^^^^
The :command:`module` :subcmd:`edit` sub-command opens a modulefile in the
configured text editor (cf. :subcmd:`config` :mconfig:`editor`).
Instead of manually locating a modulefile:
.. parsed-literal::
:ps:`$` vi $(module path appA)
One can directly edit it with:
.. parsed-literal::
:ps:`$` module edit appA
``module lint``
^^^^^^^^^^^^^^^
The :command:`module` :subcmd:`lint` sub-command analyzes modulefiles and
reports potential issues.
It relies on the Nagelfar Tcl syntax checker to detect syntax errors and
common mistakes.
Analyze a specific modulefile:
.. parsed-literal::
:ps:`$` module lint appA
Reported issues may include:
* Unknown variables
* Unknown commands
* Invalid command arguments
* Tcl syntax errors
``source-sh``
^^^^^^^^^^^^^
The :mfcmd:`source-sh` modulefile command evaluates a shell script and tracks
the environment changes it performs.
The detected changes are translated into modulefile actions, making it
possible to load and unload shell-based environments through Modules.
It is particularly useful to integrate software distributions that provide
environment setup scripts such as ``setup-env.sh``, ``mpivars.sh``, or
similar rc-provided files.
For example:
.. code-block:: tcl
#%Module
source-sh bash /opt/spack/share/spack/setup-env.sh
``sh-to-mod``
^^^^^^^^^^^^^
The :command:`module` :subcmd:`sh-to-mod` sub-command evaluates a shell script
and reports the resulting environment changes as modulefile commands.
It can be used to convert existing shell initialization scripts into
modulefiles.
For example:
.. parsed-literal::
:ps:`$` module sh-to-mod bash setup-env.sh > setup-env.mod
.. tip::
Use :subcmd:`sh-to-mod` when you want to generate and maintain a regular
modulefile from an existing shell script.
``mod-to-sh``
^^^^^^^^^^^^^
The :command:`module` :subcmd:`mod-to-sh` sub-command evaluates one or more
modulefiles and reports the resulting environment changes as shell code.
For example:
.. parsed-literal::
:ps:`$` module mod-to-sh bash appA > setup-env.sh
.. tip::
The :subcmd:`mod-to-sh` sub-command can be seen as the reverse operation of
:subcmd:`sh-to-mod`.
``prereq``
^^^^^^^^^^
The :mfcmd:`prereq` modulefile command declares one or more modules as a
requirement of the current modulefile. When the automated module handling
mode is enabled (see :mconfig:`auto_handling`), which is the default, a
requirement is automatically loaded if not yet present in the user
environment.
Requirements are sometimes expressed with a condition block:
.. code-block:: tcl
if { ! [ is-loaded appA ] } {
module load appA
}
This must be avoided: when ``appA`` is already loaded, the condition is
false and no requirement rule is defined, so Modules is not aware that the
current module depends on ``appA``.
Declare the requirement unconditionally instead:
.. code-block:: tcl
prereq appA
Loading a module declaring this requirement (here ``appB``) automatically
loads the required module when missing:
.. parsed-literal::
:ps:`$` module load appB
Loading :sgrhi:`appB`
:sgrin:`Loading requirement`: appA
When automated module handling is disabled, a missing requirement is not
automatically loaded: an error is reported and the modulefile load fails.
The :mfcmd:`module load` modulefile command equally declares a
requirement rule, and it loads the missing required module even when
automated module handling is disabled. The two commands also differ when
several modules are specified: :mfcmd:`module load` loads them all
(logical AND) whereas :mfcmd:`prereq` requires only one of them (logical
OR). Multiple :mfcmd:`prereq` commands act as a logical AND.
``conflict``
^^^^^^^^^^^^
The :mfcmd:`conflict` modulefile command declares one or more modules that
cannot be loaded together with the current modulefile.
Instead of manually checking for incompatible modules:
.. code-block:: tcl
if { [ is-loaded appB ] } {
puts stderr "ERROR: appB conflicts with appA!"
exit 1
}
Declare the conflict with:
.. code-block:: tcl
conflict appB
When the :mconfig:`conflict_unload` configuration option is enabled in
addition to the automated module handling mode (see :mconfig:`auto_handling`),
loading a module automatically unloads the conflicting modules found in the
user environment:
.. parsed-literal::
:ps:`$` module load appA
Loading :sgrhi:`appA`
:sgrin:`Unloading conflict`: appB
When these options are disabled, an error is reported instead and the
modulefile load fails.
A modulefile declaring a conflict on its own module name defines a
*reflexive conflict*: only one version of this module can then be loaded at
a time.
.. code-block:: tcl
conflict appA
.. parsed-literal::
:ps:`$` module load appA/2.0
Loading :sgrhi:`appA/2.0`
:sgrin:`Unloading conflict`: appA/1.0
.. tip::
When only one module should be loaded at a time for any given module
name, enable the :mconfig:`unique_name_loaded` configuration option
instead of declaring a reflexive conflict in every modulefile. As this
option applies to all existing modules, every module name must follow
this rule. It is generally the case when only *application* modules are
provided, but may not be if application configurations are also handled
through modulefiles.
``variant``
^^^^^^^^^^^
The :mfcmd:`variant` modulefile command declares variants and their accepted
values.
This command is only available inside modulefiles.
Variants allow users to customize the behavior of a modulefile at load time.
They follow the same syntax as Spack variants.
Boolean variants are enabled with ``+`` and disabled with ``~``:
.. code-block:: tcl
#%Module
variant --boolean cuda
.. parsed-literal::
:ps:`$` module load openmpi +cuda
Variants with multiple values are declared by listing the accepted values:
.. code-block:: tcl
#%Module
variant compiler gcc intel
And selected with the ``=`` syntax:
.. parsed-literal::
:ps:`$` module load openmpi compiler=intel
The :mfcmd:`getvariant` modulefile command retrieves the value of a declared
variant, allowing the modulefile to adapt its behavior.
For example:
.. code-block:: tcl
switch -- [getvariant compiler] {
gcc {
prereq gcc
}
intel {
prereq intel
}
}
Configuration option :mconfig:`variant_shortcut` defines shortcut characters
for variants.
For example:
.. parsed-literal::
:ps:`$` module config variant_shortcut compiler=%
This allows users to write:
.. parsed-literal::
:ps:`$` module load openmpi %gcc
Advanced manipulations
----------------------
Advanced module version specifiers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:ref:`advanced_module_version_specifiers` provide a concise way to select modulefiles based on
their version or declared variants. They can be used with several
:command:`module` sub-commands, including :subcmd:`avail`,
:subcmd:`spider`, :subcmd:`load`, and :subcmd:`switch`.
Version specifications use the ``@`` character:
.. list-table::
:header-rows: 1
:widths: 40 60
* - Specification
- Description
* - ``module avail cuda@default``
- Select the default version.
* - ``module avail cuda@latest``
- Select the latest version.
* - ``module avail cuda@12:``
- Select versions greater than or equal to ``12``.
* - ``module avail cuda@:12``
- Select versions lower than or equal to ``12``.
* - ``module avail cuda@12:13``
- Select versions between ``12`` and ``13``.
Variant specifications may also be used:
.. list-table::
:header-rows: 1
:widths: 40 60
* - Specification
- Description
* - ``module avail +mpi``
- Select modules declaring the ``mpi`` variant.
* - ``module avail cuda=12``
- Select modules where the ``cuda`` variant is set to ``12``.
* - ``module avail +mpi +cuda``
- Select modules matching both variant requirements.
``--timer`` and ``--debug``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :option:`--timer` and :option:`--debug`, or :option:`-D`, options help
analyze and troubleshoot Modules commands.
They are supported by most :command:`module` sub-commands.
The :option:`--timer` option reports the total execution time of a command.
For example:
.. parsed-literal::
:ps:`$` module avail --timer
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/8.3 :sgrde:`gcc/11.1` gcc/14.0 openmpi/5.0.8
:sgrtr:`TIMER Total execution took 20.045 ms`
The :option:`--debug`, or :option:`-D`, option displays debugging messages
describing the internal execution of the command.
For example:
.. parsed-literal::
:ps:`$` module avail -D
:sgrtr:`DEBUG setState: cmdline set to 'modulecmd.tcl bash avail -D'`
:sgrtr:`DEBUG setState: shell set to 'bash'`
:sgrtr:`DEBUG setState: subcmd set to 'avail'`
:sgrtr:`DEBUG setConf: verbosity set to 'debug'`
...
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
gcc/8.3 :sgrde:`gcc/11.1` gcc/14.0 openmpi/5.0.8
The :option:`--timer` and :option:`--debug` options may be combined. In this
case, regular debug messages are replaced by execution time reports for each
internal procedure call.
.. parsed-literal::
:ps:`$` module avail --timer -D
:sgrtr:`TIMER parseModuleCommandName avail help (0.151 ms)`
:sgrtr:`TIMER isIcase (0.088 ms)`
:sgrtr:`TIMER defineModStartNbProc 1 (0.060 ms)`
...
:sgrtr:`TIMER Total execution took 31.722 ms`
For even more detailed debugging information, use :option:`-DD`.
``.modulerc`` files
^^^^^^^^^^^^^^^^^^^
A :file:`.modulerc` file contains Tcl code automatically evaluated by
Modules when encountered during a command execution.
Rc files are used to define module aliases, virtual
modules, tags, hidden modules, forbidden modules, ...
Several :file:`.modulerc` files may be evaluated during a single
:command:`module` command.
Depending on the executed sub-command, Modules may evaluate
:file:`.modulerc` files found in different locations, including:
* :envvar:`MODULERCFILE`
* :file:`$HOME/.modulerc`
* Modulepath and modules directories
For example, the following directory hierarchy contains several
:file:`.modulerc` files:
.. code-block:: text
/home/user/.modulerc
modulefiles/
├── .modulerc
├── app/
│ ├── .modulerc
│ └── 1.0
└── mpi/
├── .modulerc
└── openmpi/5.0
Depending on the requested operation, one or more of these files are
evaluated automatically.
See :ref:`Modulecmd startup` for details on the startup sequence,
:mconfig:`rcfile` and :mconfig:`ignore_user_rc` to configure the evaluation
of user rc files, and :sitevar:`modulerc_extra_vars` and
:sitevar:`modulerc_extra_cmds` to extend :file:`.modulerc` files.
``module-tag``
^^^^^^^^^^^^^^
The :mfcmd:`module-tag` modulerc command associates one or more tags with
modulefiles.
This command is only available inside :file:`.modulerc` files.
Tags may be used to provide additional information about modulefiles or to
modify their behavior.
For example:
.. code-block:: tcl
module-tag experimental app/2.0
The tag is then reported along the module name in search results:
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
app/1.0 app/2.0 :sgrse:`<`\ experimental\ :sgrse:`>`
Several predefined tags affect the behavior of Modules:
.. list-table::
:header-rows: 1
:widths: 25 75
* - Tag
- Description
* - ``keep-loaded``
- Prevent automatic unloading when unloading dependent modules.
* - ``sticky``
- Prevent unloading unless :option:`--force` is specified.
* - ``super-sticky``
- Prevent unloading under any circumstances.
For example:
.. code-block:: tcl
module-tag sticky core
Once loaded, the ``core`` module cannot be unloaded, even with the
:subcmd:`purge` sub-command. The ``sticky`` tag is rendered with a specific
background color in the output.
.. parsed-literal::
:ps:`$` module purge
Unloading :sgrshi:`core/1.0`
:sgrer:`ERROR`: Unload of sticky module skipped
:ps:`$` module list
Currently Loaded Modulefiles:
1) :sgrs:`core/1.0`
Sticky modules can help ensure that essential software stacks remain loaded.
The behavior of :subcmd:`purge` with sticky modules can be configured through
:mconfig:`sticky_purge`.
``module-hide``
^^^^^^^^^^^^^^^
The :mfcmd:`module-hide` modulerc command hides modulefiles from module
searches and selection.
This command is only available inside :file:`.modulerc` files.
A hidden module is excluded from regular searches but may still be selected
when explicitly referred to by its exact name.
For example:
.. code-block:: tcl
module-hide app/1.0
Visibility may also be restricted to specific users or groups.
Time-based restrictions can be defined with ``--after`` and ``--before``.
For example:
.. code-block:: tcl
module-hide --after 2027-01-01 app/1.0
See :mfcmd:`module-hide` for additional visibility options, including **soft**
and **hard** hiding, as well as **users** and **groups** restrictions.
``module-forbid``
^^^^^^^^^^^^^^^^^
The :mfcmd:`module-forbid` modulerc command prevents designated modulefiles
from being loaded.
This command is only available inside :file:`.modulerc` files.
Unlike a hidden module, a forbidden module remains visible in module searches
but cannot be loaded.
For example:
.. code-block:: tcl
module-forbid app/1.0
A custom message may be displayed when a user attempts to load a forbidden
module with the ``--message`` option.
For example:
.. code-block:: tcl
module-forbid --message {Please use app/2.0 instead} app/1.0
See :mfcmd:`module-forbid` for additional restriction options, including
custom messages, as well as **after**/**before**, **users** and **groups** restrictions.
``module-virtual``
^^^^^^^^^^^^^^^^^^
The :mfcmd:`module-virtual` modulerc command associates a virtual module name
with an existing modulefile.
This command is only available inside :file:`.modulerc` files.
Several virtual modules may refer to the same modulefile, reducing the number
of files required to define similar modules.
For example:
.. code-block:: text
modulefiles/app/
├── .common
└── .modulerc
The :file:`.modulerc` file may define several virtual versions:
.. code-block:: tcl
#%Module
module-virtual 1.0 .common
module-virtual 1.2 .common
module-virtual 1.5 .common
module-virtual 2.0 .common
.. parsed-literal::
:ps:`$` module avail
------------------- :sgrmp:`/usr/share/modulefiles` ------------------
app/1.0 app/1.2 app/1.5 app/2.0
All these virtual modules are evaluated using the same :file:`.common`
modulefile.
Its behavior can be adapted according to the virtual module
name being evaluated.
.. code-block:: tcl
#%Module
set version [lindex [split [module-info name] /] end]
setenv APP_VERSION $version
Module logger
^^^^^^^^^^^^^
Modules can log module activity through the :mconfig:`logger` and
:mconfig:`logged_events` configuration options.
The :mconfig:`logger` option defines the command used to record log messages.
For example:
.. parsed-literal::
:ps:`$` module config logger "/usr/bin/logger -t modules"
The :mconfig:`logged_events` option defines which module events are recorded.
.. list-table::
:header-rows: 1
:widths: 30 70
* - Event
- Description
* - ``requested_cmd``
- Record module commands requested by users.
* - ``requested_eval``
- Record modulefile evaluations requested by users.
* - ``auto_eval``
- Record modulefile evaluations automatically triggered by Modules.
Multiple events may be specified using the ``:`` separator.
For example:
.. parsed-literal::
:ps:`$` module config logged_events requested_cmd:requested_eval
By default, no events are logged.
The logger command can be customized to integrate Modules activity with an
existing logging or monitoring infrastructure.