.. Home page

Environment Modules
===================

.. image:: https://img.shields.io/github/stars/cea-hpc/modules
    :target: https://github.com/cea-hpc/modules
    :alt: GitHub Repository

.. image:: https://img.shields.io/github/license/cea-hpc/modules?color=lightsteelblue
    :alt: GitHub License

.. image:: https://img.shields.io/github/v/release/cea-hpc/modules
    :target: https://github.com/cea-hpc/modules/releases/latest
    :alt: GitHub Release

.. image:: https://img.shields.io/twitter/url/https/twitter.com/EnvModules.svg?style=social&label=@EnvModules
    :target: https://twitter.com/EnvModules
    :alt: Twitter/X

**Welcome to the Environment Modules documentation portal. The Environment
Modules package provides for the dynamic modification of a user's environment
via modulefiles.**

The Modules package is a tool that simplifies shell initialization and
lets users easily modify their environment during a session using
modulefiles.

Each modulefile contains the information needed to configure the shell for
an application. Once the Modules package is initialized, the environment
can be modified on a per-module basis using the :command:`module` command
which interprets modulefiles. Typically modulefiles instruct the
:command:`module` command to alter or set shell environment variables such as
:envvar:`PATH`, :envvar:`MANPATH`, etc. modulefiles may be shared by many
users on a system and users may have their own collection to supplement or
replace the shared modulefiles.

Modules can be **loaded** and **unloaded** dynamically and atomically,
in an clean fashion. All popular shells are supported, including *bash*,
*ksh*, *zsh*, *sh*, *csh*, *tcsh*, *fish*, *cmd*, *pwsh*, as well as some
languages such as *tcl*, *perl*, *python*, *ruby*, *cmake* and *r*.

Modules are useful in managing different versions of applications. Modules
can also be bundled into meta-modules that will load an entire suite of
different applications.

.. note:: Modules presented here are ones that modify the shell or script
   execution environment. They should not be confused with language-specific
   modules (e.g., Perl modules, Python modules or R modules) that add specific
   capabilities to scripts.

Quick examples
--------------

Here is an example of loading a module on a Linux machine under bash.
::

    $ module load gcc/9.4.0
    $ which gcc
    $ /usr/local/gcc/9.4.0/linux-x86_64/bin/gcc

Now we'll switch to a different version of the module
::

    $ module switch gcc gcc/10
    $ which gcc
    /usr/local/gcc/10.3.0/linux-x86_64/bin/gcc

And now we'll unload the module altogether
::

    $ module unload gcc
    $ which gcc
    gcc not found

Now we'll log into a different machine, using a different shell (tcsh).
::

    % module load gcc/10.3
    % which gcc
    /usr/local/gcc/10.3.0/linux-aarch64/bin/gcc

Note that the command line is exactly the same, but the path has
automatically configured to the correct architecture.

.. toctree::
   :hidden:
   :maxdepth: 2
   :caption: Basics

   INSTALL
   INSTALL-win
   MIGRATING
   NEWS
   FAQ
   changes

.. toctree::
   :hidden:
   :maxdepth: 2
   :caption: Examples

   cookbook

.. toctree::
   :hidden:
   :maxdepth: 2
   :caption: Reference

   ml
   module
   modulefile

.. toctree::
   :hidden:
   :maxdepth: 2
   :caption: Development

   CONTRIBUTING
   design


Get started with Modules
------------------------

Learn how to retrieve and install Modules :ref:`on Unix<INSTALL>` or
:ref:`on Windows<INSTALL-win>`. An overlook on the new functionalities
introduced by each version is available in the :ref:`MIGRATING` guide.
:ref:`NEWS` provides the full list of changes added in each version. The
:ref:`changes` document gives an in-depth view of the modified behaviors and
new features between major versions.

Reference manual page for the :ref:`module(1)` and :ref:`ml(1)` commands and
for :ref:`modulefile(5)` script provide details on all supported options.

A :ref:`cookbook` of recipes describes how to use the various features of
Modules and how to extend the :command:`module` command to achieve specific
needs.

If you have questions, comments or development suggestions for the Modules
community, please read the :ref:`CONTRIBUTING` guide.

Links
-----

* Web site: http://modules.sourceforge.net
* Documentation: https://modules.readthedocs.io
* Source repository: https://github.com/cea-hpc/modules
* Issue tracking system: https://github.com/cea-hpc/modules/issues
* Download releases: https://github.com/cea-hpc/modules/releases
* Mailing-list: https://sourceforge.net/projects/modules/lists/modules-interest
* X/Twitter: https://twitter.com/EnvModules

License
-------

Modules is distributed under the GNU General Public License, either version 2
or (at your option) any later version (GPL v2+).
