envmodules · xdelaruelle · Jun 23, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -1161,6 +1161,20 @@ instance :instopt:`--without-modulepath<--with-modulepath>`):
     .. versionchanged:: 5.0
        Configuration option default set to ``etcdir``
 
+.. instopt:: --with-init-envvars=LIST
+
+ Initial values to assign to environment variables before they are modified
+ for the first time. Each entry in LIST must use the format
+ ``VARIABLE_NAME=initial_value``. Entries are separated by ``:``.
+
+ This installation option defines the default value of the
+ :mconfig:`init_envvars` configuration option which could be changed after
+ installation with the :subcmd:`config` sub-command.
+
+ .. only:: html or latex
+
+    .. versionadded:: 5.7
+
 .. instopt:: --with-light-background-colors=SGRLIST
 
  Default color set to apply if terminal background color is defined to
@@ -1723,6 +1737,9 @@ installation.
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`info_extension`         | ``0``                                        | :envvar:`MODULES_INFO_EXTENSION`             |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
+| :mconfig:`init_envvars`           | *Empty by default*                           | :instopt:`--with-init-envvars`               |              |           |
+|                                   |                                              | :envvar:`MODULES_INIT_ENVVARS`               |              |           |
++-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`linked_envvars`         | *Empty by default*                           | :envvar:`MODULES_LINKED_ENVVARS`             |              |           |
 +-----------------------------------+----------------------------------------------+----------------------------------------------+--------------+-----------+
 | :mconfig:`list_output`            | ``header:idx:variant:sym:tag:key``           | :instopt:`--with-list-output`,               |              |           |

diff --git a/MIGRATING.rst b/MIGRATING.rst
@@ -135,6 +135,53 @@ The output of ``module display`` also includes the environment variable
 changes applied to linked environment variables, making these propagated
 updates visible before a module is loaded.
 
+.. _Init environment variables:
+
+Initialize environment variables on first modification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new configuration option, :mconfig:`init_envvars`, has been added to define
+initial values for environment variables that are modified through path-like
+modulefile commands.
+
+This feature is particularly useful for variables such as ``MANPATH``, which
+require a leading or trailing colon character to preserve access to the system
+default search paths. Previously, modifying an undefined ``MANPATH`` could
+prevent system manual pages from being found. See the :ref:`man-path` cookbook
+for details.
+
+The :mconfig:`init_envvars` option defines a colon-separated list of
+``VARIABLE_NAME=initial_value`` entries. When a path-like operation is applied
+to an environment variable that is not currently set, the configured initial
+value is assigned before the modification is performed.
+
+For example, with the following configuration:
+
+.. parsed-literal::
+
+    :ps:`$` module config init_envvars MANPATH=
+
+loading a module that prepends a directory to ``MANPATH``:
+
+.. parsed-literal::
+
+    :sgrcm:`prepend-path` MANPATH /opt/pkg/man
+
+will keep a colon character at the end of ``MANPATH``
+
+.. parsed-literal::
+
+    :ps:`$` echo $MANPATH
+    /opt/pkg/man:
+
+This mechanism applies to all path-like environment variable management
+commands, including :mfcmd:`append-path`, :mfcmd:`prepend-path` and
+:mfcmd:`remove-path`.
+
+When values are later removed from an environment variable, it is
+automatically unset if its resulting value matches the configured initial
+value and no explicit reference counter is associated with it.
+
 
 v5.6
 ----

diff --git a/Makefile b/Makefile
@@ -462,6 +462,7 @@ sed -e 's|@prefix@|$(prefix)|g' \
 	-e 's|@searchmatch@|$(searchmatch)|g' \
 	-e 's|@wa277@|$(setwa277)|g' \
 	-e 's|@pathentryreorder@|$(setpathentryreorder)|g' \
+	-e 's|@initenvvars@|$(initenvvars)|g' \
 	-e 's|@icase@|$(icase)|g' \
 	-e 's|@nearlyforbiddendays@|$(nearlyforbiddendays)|g' \
 	-e 's|@tagabbrev@|$(tagabbrev)|g' \

diff --git a/Makefile.inc.in b/Makefile.inc.in
@@ -164,6 +164,9 @@ editor := @editor@
 # path change behavior
 pathentryreorder := @pathentryreorder@
 
+# environment variable configurations
+initenvvars := @initenvvars@
+
 # shell completion location
 bashcompletiondir := @bashcompletiondir@
 fishcompletiondir := @fishcompletiondir@

diff --git a/NEWS.rst b/NEWS.rst
@@ -96,6 +96,13 @@ Modules 5.7.0 (not yet released)
   :mconfig:`linked_envvars` is changed with :subcmd:`config` sub-command, it
   sets the :envvar:`MODULES_LINKED_ENVVARS` environment variable. (fix issue
   #609)
+* Doc: add :ref:`init-envvars` design notes.
+* Add the :mconfig:`init_envvars` configuration option to define initial
+  values to assign to environment variables before they are modified for the
+  first time. This option can be changed at installation time with
+  :instopt:`--with-init-envvars`. When :mconfig:`init_envvars` is changed with
+  :subcmd:`config` sub-command, it sets the :envvar:`MODULES_INIT_ENVVARS`
+  environment variable. (fix issue #572)
 
 
 .. _5.6 release notes:

diff --git a/configure b/configure
@@ -41,7 +41,7 @@ listterseoutput editor variantshortcut bashcompletiondir fishcompletiondir \
 zshcompletiondir tcllinter tcllinteropts nagelfardatadir nagelfaraddons \
 stickypurge uniquenameloaded abortonerror sourcecache logger loggeropts \
 loggedevents conflictunload spideroutput spiderterseoutput spiderindepth \
-emacsdatadir emacsaddons requirevia compressedchangelog paginate"
+emacsdatadir emacsaddons requirevia compressedchangelog paginate initenvvars"
 libarglist=()
 
 # flags to know if argument has been specified on command-line
@@ -131,6 +131,7 @@ modulefilesdir=
 moduleshome=
 modulepath=
 windowssupport=n
+initenvvars=
 nearlyforbiddendays=14
 tagabbrev='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'
 tagcolorname=
@@ -389,6 +390,11 @@ Optional Packages:
                           (\`search'), on all sub-commands and modulefile Tcl
                           commands (\`always') or disable case insensitive
                           match (\`never') [$icase]
+  --with-init-envvars=LIST
+                          initial value to set listed environment variables to
+                          when they are firstly defined (elements have
+                          \`VAR=value' syntax and are separated by \`:' in
+                          LIST) [$initenvvars]
   --with-initconf-in=VALUE
                           location where to install Modules initialization
                           configuration files. Either \`initdir' or \`etcdir'
@@ -867,6 +873,8 @@ for arg in "$@"; do
    --with-terminal-background=*|--without-terminal-background)
       allowedval=" dark light " ;
       check_and_get_package_value "termbg" "$arg" "$allowedval" ;;
+   --with-init-envvars=*|--without-init-envvars)
+      initenvvars=$(get_package_value "$arg" "") ;;
    --with-locked-configs=*|--disable-locked-configs)
       lockedconfigs=$(get_package_value "$arg" "") ;
       allowedval=" extra_siteconfig implicit_default logged_events logger " ;

diff --git a/doc/source/changes.rst b/doc/source/changes.rst
@@ -1077,7 +1077,8 @@ The following environment variables appeared on Modules 5.
 |            | :envvar:`MODULES_PAGINATE`,                                     |
 |            | :envvar:`MODULES_NON_EXPORTABLE_TAGS`,                          |
 |            | :envvar:`MODULES_INFO_EXTENSION`,                               |
-|            | :envvar:`MODULES_LINKED_ENVVARS`                                |
+|            | :envvar:`MODULES_LINKED_ENVVARS`,                               |
+|            | :envvar:`MODULES_INIT_ENVVARS`                                  |
 +------------+-----------------------------------------------------------------+
 
 Modules Specific Tcl Commands
@@ -1292,7 +1293,7 @@ The following Modules configuration option has been introduced on Modules 5.
 +------------+-----------------------------------------------------------------+
 | 5.7        | :mconfig:`path_entry_reorder`, :mconfig:`paginate`,             |
 |            | :mconfig:`non_exportable_tags`, :mconfig:`info_extension`,      |
-|            | :mconfig:`linked_envvars`                                       |
+|            | :mconfig:`linked_envvars`, :mconfig:`init_envvars`              |
 +------------+-----------------------------------------------------------------+
 
 :mconfig:`auto_handling`

diff --git a/doc/source/cookbook/man-path.rst b/doc/source/cookbook/man-path.rst
@@ -70,8 +70,22 @@ man page directories.
 
 If your modulefiles modify :envvar:`MANPATH`, it is recommended to initialize
 this environment variable with a single colon (``:``) during Modules startup.
-To do this, add the following line to the ``initrc`` configuration file
-(typically located in ``/etc/environment-modules``):
+
+To do this on Modules 5.7 or any newer version, add the following line to the
+``initrc`` configuration file (typically located in
+``/etc/environment-modules``):
+
+.. code-block:: tcl
+
+   module config init_envvars MANPATH=
+
+With this configuration, the ``MANPATH`` environment variable will be
+initialized to an empty string right before its first modification. As a
+result a leading or finishing colon character will be set the first time a
+path entry is added to ``MANPATH``.
+
+With older versions of Modules, add the following line to the ``initrc``
+configuration file:
 
 .. code-block:: tcl
 

diff --git a/doc/source/design/init-envvars.rst b/doc/source/design/init-envvars.rst
@@ -0,0 +1,37 @@
+.. _init-envvars:
+
+Initialize environment variables
+================================
+
+This document describes the mechanism to initialize an environment variable to
+a given value the first time this variable is changed.
+
+This is especially useful for variable like ``MANPATH`` that requires a
+leading or finishing colon character in addition to the specific paths defined
+to still be able to query the system man pages.
+
+Design choices:
+
+* If environment variable is changed and currently not defined, set it to the
+  defined initial value prior applying the change
+* When removing value to path-like environment variable, if after the removal
+  it equals the initial value without specific reference counter, unset the
+  environment variable
+
+This mechanism applies to all path-like environment variable management
+modulefile commands and module sub-commands:
+
+* :mfcmd:`append-path`
+* :mfcmd:`prepend-path`
+* :mfcmd:`remove-path`
+
+``init_envvars`` configuration option
+-------------------------------------
+
+New configuration option :mconfig:`init_envvars` is made to define the initial
+value of the environment variables.
+
+* Items are separated by colon character
+* Each item has the following syntax: ``VARNAME=initial_value``
+
+.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent:
diff --git a/doc/source/design/linked-envvars.rst b/doc/source/design/linked-envvars.rst
@@ -3,7 +3,7 @@
 Linked environment variables
 ============================
 
-This document describes the mechanism to link one environment variables onto
+This document describes the mechanism to link one environment variable onto
 others and apply the same value changes.
 
 The goal is to link environment variables together and apply all changes to

diff --git a/doc/source/module.rst b/doc/source/module.rst
@@ -1248,6 +1248,22 @@ Module Sub-Commands
 
      .. versionadded:: 5.7
 
+ .. mconfig:: init_envvars
+
+  Initial values to assign to environment variables right before they are
+  modified for the first time.
+
+  This configuration option is set to an empty value by default. It can be
+  changed at installation time with :instopt:`--with-init-envvars` option. The
+  :envvar:`MODULES_INIT_ENVVARS` environment variable is defined by
+  :subcmd:`config` sub-command when changing this configuration option from
+  its default value. See :envvar:`MODULES_INIT_ENVVARS` description for
+  details
+
+  .. only:: html or latex
+
+     .. versionadded:: 5.7
+
  .. mconfig:: linked_envvars
 
   Define links between environment variables to apply same value modification
@@ -5164,6 +5180,29 @@ ENVIRONMENT
 
     .. versionadded:: 5.7
 
+.. envvar:: MODULES_INIT_ENVVARS
+
+ A colon-separated list of environment variable initial definitions. Each
+ definition must use the format ``VARIABLE_NAME=initial_value``. When an
+ environment variable is modified for the 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 (:mfcmd:`append-path`,
+ :mfcmd:`prepend-path` and :mfcmd:`remove-path`).
+
+ When an entry is 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 environment variable value supersedes the default value set in the
+ :mconfig:`init_envvars` configuration option. It can be defined with the
+ :subcmd:`config` sub-command.
+
+ .. only:: html or latex
+
+    .. versionadded:: 5.7
+
 .. envvar:: MODULES_LINKED_ENVVARS
 
  A colon-separated list of environment variable link sets. Each link set is a

diff --git a/doc/source/modulefile.rst b/doc/source/modulefile.rst
@@ -1196,10 +1196,14 @@ the *modulefile* is being loaded.
  configuration option is activated, the *modulefile* is considered a
  dependency by the loaded modulefiles stored in the added modulepaths.
 
- If a link is defined for variable through the :mconfig:`linked_envvars`
+ If a link is defined for *variable* through the :mconfig:`linked_envvars`
  configuration option, the same :mfcmd:`prepend-path` command is applied to
  all associated environment variables.
 
+ If an initial value is defined for the *variable* through the
+ :mconfig:`init_envvars` configuration option, that value is assigned before
+ the modification is applied when the *variable* is not already set.
+
  .. only:: html or latex
 
     .. versionchanged:: 4.1
@@ -1363,7 +1367,7 @@ the *modulefile* is being loaded.
  which is named by prefixing *variable* by :envvar:`__MODULES_PUSHENV_\
  <__MODULES_PUSHENV_\<VAR\>>`.
 
- If a link is defined for variable through the :mconfig:`linked_envvars`
+ If a link is defined for *variable* through the :mconfig:`linked_envvars`
  configuration option, the same :mfcmd:`pushenv` command is applied to all
  associated environment variables.
 
@@ -1456,10 +1460,15 @@ the *modulefile* is being loaded.
 
  An error is raised if *value* equals *delimiter* character.
 
- If a link is defined for variable through the :mconfig:`linked_envvars`
+ If a link is defined for *variable* through the :mconfig:`linked_envvars`
  configuration option, the same :mfcmd:`remove-path` command is applied to
  all associated environment variables.
 
+ If an initial value is defined for *variable* through the
+ :mconfig:`init_envvars` configuration option, variable is unset when, after
+ the modification, its value matches the configured initial value and no
+ explicit reference counter is defined.
+
  .. only:: html or latex
 
     .. versionchanged:: 4.1
@@ -1549,7 +1558,7 @@ the *modulefile* is being loaded.
 
  Any newline character in *value* is chopped if using *csh* or *tcsh* shells.
 
- If a link is defined for variable through the :mconfig:`linked_envvars`
+ If a link is defined for *variable* through the :mconfig:`linked_envvars`
  configuration option, the same :mfcmd:`setenv` command is applied to all
  associated environment variables.
 
@@ -1677,7 +1686,7 @@ the *modulefile* is being loaded.
  environment *variable* is also unset when *modulefile* is unloaded. These
  behaviors are applied even if an optional *value* is defined.
 
- If a link is defined for variable through the :mconfig:`linked_envvars`
+ If a link is defined for *variable* through the :mconfig:`linked_envvars`
  configuration option, the same :mfcmd:`unsetenv` command is applied to all
  associated environment variables.
 

diff --git a/init/Makefile b/init/Makefile
@@ -136,7 +136,7 @@ comp_lint_opts := -a -i --all --icase
 comp_modtosh_opts := --auto --no-auto --force -f --icase -i
 comp_path_opts := -d --delim --duplicates
 comp_rm_path_opts := -d --delim --index
-comp_config_opts := --dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement info_extension linked_envvars list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml 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 source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277
+comp_config_opts := --dump-state --reset abort_on_error advanced_version_spec auto_handling avail_indepth avail_output avail_terse_output cache_buffer_bytes cache_expiry_secs collection_pin_version collection_pin_tag collection_target color colors conflict_unload contact editor extended_default extra_siteconfig hide_auto_loaded home icase ignore_cache ignore_user_rc implicit_default implicit_requirement init_envvars info_extension linked_envvars list_output list_terse_output locked_configs logged_events logger mcookie_check mcookie_version_check ml 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 source_cache spider_indepth spider_output spider_terse_output sticky_purge tag_abbrev tag_color_name tcl_linter term_background term_width unique_name_loaded unload_match_order variant_shortcut verbosity wa_277
 
 define translate-in-script
 $(ECHO_GEN)