Initial environment

Initial environment corresponds to the environment state at the end of Modules initialization.

  • initialization performed by autoinit sub-command
  • which evaluates modulespath and initrc initialization files if they exist and if MODULEPATH and LOADEDMODULES are both found unset or empty
  • environment state is composed of:
    • enabled modulepaths
    • loaded modules
    • with manual and modulerc tags applied onto loaded modules
    • with variant values applied onto loaded modules

Initial environment is what you get when you connect to a machine, with the environment configuration (modulepaths, loaded modules) defined by the system administrator of this machine. Plus your own addition if the initrc file set by system administrator calls module restore to load your default collection.


Once defined after the evaluation of modulespath and initrc initialization files, the initial environment is stored in an environment variable: __MODULES_LMINIT.

  • colon-separated list serializing content of a collection
  • each element is a module use or module load command describing the initial environment (modulepaths, loaded modules, their tags and variants)
  • variable is named following private name convention as it is not expected to be modified by user

Initial environment is stored as a collection in user environment to:

  • use collection mechanisms to restore or view the initial environment
  • stored in user environment to attach to the current shell session

Like for other __MODULES_LM* persistency variables, : character in content (like tag list separator) is translated into < character. Not to be confused with element separator in such variable.

As what is stored in __MODULES_LMINIT corresponds to the loaded environment after Modules initialization, this environment is consistent (i.e., no missing dependency for loaded modules).

reset sub-command

reset sub-command enables to restore the initial environment. It means to unuse enabled modulepaths and unload loaded modules then use initial modulepaths and load initial modules.

General properties:

  • Shortcut name: none
  • Accepted option: --force, --auto, --no-auto
  • Expected number of argument: 0
  • Accept boolean variant specification: no
  • Parse module version specification: no
  • Fully read modulefile when checking validity: yes
  • Sub-command only called from top level: yes
  • Lead to modulefile evaluation: yes (unload and load modes)

reset is equivalent to restore __init__. It relies totally on restore sub-command that unsets current environment and restore initial environment, like done for any collection.

Behavior of reset sub-command can be changed with reset_target_state configuration option.

As it evaluates modules, --force, --auto and --no-auto options can be set for reset sub-command. But, as for restore sub-command these options should have no impact, as:

  • collection fully describes dependencies to load, no automatic resolution needed
  • current environment unload is processed module by module, no automatic resolution expected
  • sticky modules are unloaded by default, no need to force unload
  • super-sticky cannot be unloaded even if forced

reset sub-command outputs Loading, Unloading, Tagging messages like restore sub-command. Which is the default output mode for a sub-command triggering multiple module evaluations that cannot be guessed by user.

FUTURE: an init tag could be applied onto loaded modules and used modulepaths of initial environment to let users spot what parts of their environment is from the initial one.

restore/saveshow sub-commands

restore and saveshow sub-commands respectively restore and show the initial environment when called with the __init__ argument.

  • instead of reading a collection file, the two sub-commands read the content of the __MODULES_LMINIT variable
  • specific name __init__ is used not to confuse with an existing collection

restore sub-command is changed to restore initial environment when no argument is provided in case no default collection exists. This is done to align behavior with Lmod.

Same behavior change is applied on saveshow sub-command: initial environment is displayed when no argument provided and no default collection exists.

reset_target_state configuration option

reset_target_state defines targeted state of reset sub-command. What environment to restore.

  • equals __init__ by default, which corresponds to the behavior described above (initial environment is restored)
  • when set with config sub-command, defines environment variable MODULES_RESET_TARGET_STATE for value persistency
  • other value accepted:
    • __purge__: sub-command performs a module purge
    • any other value: sub-command restore designated collection (an error is obtained if no collection with such name exists)

The ability to reset to a given collection enables user to define what is their initial environment state. Useful if they do not want to rely on the initial environment setup by sysadmins. For instance when sysadmins do not set a module restore in initrc to restore user's default collection when user's session initializes.