| 1 |
.. Home page |
| 2 |
|
| 3 |
Environment Modules |
| 4 |
=================== |
| 5 |
|
| 6 |
.. only:: html |
| 7 |
|
| 8 |
.. image:: https://img.shields.io/github/stars/envmodules/modules |
| 9 |
:target: https://github.com/envmodules/modules |
| 10 |
:alt: GitHub Repository |
| 11 |
|
| 12 |
.. image:: https://img.shields.io/github/license/envmodules/modules?color=lightsteelblue |
| 13 |
:alt: GitHub License |
| 14 |
|
| 15 |
.. image:: https://img.shields.io/github/v/release/envmodules/modules |
| 16 |
:target: https://github.com/envmodules/modules/releases/latest |
| 17 |
:alt: GitHub Release |
| 18 |
|
| 19 |
.. image:: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpublic.api.bsky.app%2Fxrpc%2Fapp.bsky.actor.getProfile%2F%3Factor%3Denvmodules.bsky.social&query=%24.followersCount&style=social&logo=bluesky&label=%40EnvModules |
| 20 |
:target: https://bsky.app/profile/envmodules.bsky.social |
| 21 |
:alt: Bluesky |
| 22 |
|
| 23 |
.. image:: https://img.shields.io/matrix/modules%3Amatrix.org?color=darkcyan |
| 24 |
:target: https://matrix.to/#/#modules:matrix.org |
| 25 |
:alt: Matrix |
| 26 |
|
| 27 |
**Welcome to the Environment Modules documentation portal. The Environment |
| 28 |
Modules package provides for the dynamic modification of a user's environment |
| 29 |
via modulefiles.** |
| 30 |
|
| 31 |
The Modules package is a tool that simplifies shell initialization and |
| 32 |
lets users easily modify their environment during a session using |
| 33 |
modulefiles. |
| 34 |
|
| 35 |
Each modulefile contains the information needed to configure the shell for |
| 36 |
an application. Once the Modules package is initialized, the environment |
| 37 |
can be modified on a per-module basis using the :command:`module` command |
| 38 |
which interprets modulefiles. Typically modulefiles instruct the |
| 39 |
:command:`module` command to alter or set shell environment variables such as |
| 40 |
:envvar:`PATH`, :envvar:`MANPATH`, etc. modulefiles may be shared by many |
| 41 |
users on a system and users may have their own collection to supplement or |
| 42 |
replace the shared modulefiles. |
| 43 |
|
| 44 |
Modules can be **loaded** and **unloaded** dynamically and atomically, |
| 45 |
in an clean fashion. All popular shells are supported, including *bash*, |
| 46 |
*ksh*, *zsh*, *sh*, *csh*, *tcsh*, *fish*, *cmd*, *pwsh*, as well as some |
| 47 |
languages such as *tcl*, *perl*, *python*, *ruby*, *cmake* and *r*. |
| 48 |
|
| 49 |
Modules are useful in managing different versions of applications. Modules |
| 50 |
can also be bundled into meta-modules that will load an entire suite of |
| 51 |
different applications. |
| 52 |
|
| 53 |
.. note:: Modules presented here are ones that modify the shell or script |
| 54 |
execution environment. They should not be confused with language-specific |
| 55 |
modules (e.g., Perl modules, Python modules or R modules) that add specific |
| 56 |
capabilities to scripts. |
| 57 |
|
| 58 |
Quick examples |
| 59 |
^^^^^^^^^^^^^^ |
| 60 |
|
| 61 |
Here is an example of loading a module on a Linux machine under bash. |
| 62 |
:: |
| 63 |
|
| 64 |
$ module load gcc/12.4.0 |
| 65 |
$ which gcc |
| 66 |
$ /usr/local/gcc/12.4.0/linux-x86_64/bin/gcc |
| 67 |
|
| 68 |
Now we'll switch to a different version of the module |
| 69 |
:: |
| 70 |
|
| 71 |
$ module switch gcc/14 |
| 72 |
$ which gcc |
| 73 |
/usr/local/gcc/14.2.0/linux-x86_64/bin/gcc |
| 74 |
|
| 75 |
And now we'll unload the module altogether |
| 76 |
:: |
| 77 |
|
| 78 |
$ module unload gcc |
| 79 |
$ which gcc |
| 80 |
gcc not found |
| 81 |
|
| 82 |
Now we'll log into a different machine, using a different shell (tcsh). |
| 83 |
:: |
| 84 |
|
| 85 |
% module load gcc/14.2 |
| 86 |
% which gcc |
| 87 |
/usr/local/gcc/14.2.0/linux-aarch64/bin/gcc |
| 88 |
|
| 89 |
Note that the command line is exactly the same, but the path has |
| 90 |
automatically configured to the correct architecture. |
| 91 |
|
| 92 |
Get started with Modules |
| 93 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 94 |
|
| 95 |
Learn how to retrieve and install Modules :ref:`on Unix<INSTALL>` or |
| 96 |
:ref:`on Windows<INSTALL-win>`. An overlook on the new functionalities |
| 97 |
introduced by each version is available in the :ref:`MIGRATING` guide. |
| 98 |
:ref:`NEWS` provides the full list of changes added in each version. The |
| 99 |
:ref:`changes` document gives an in-depth view of the modified behaviors and |
| 100 |
new features between major versions. |
| 101 |
|
| 102 |
Reference manual page for the :ref:`module(1)`, :ref:`ml(1)` and |
| 103 |
:ref:`envml(1)` commands and for :ref:`modulefile(5)` script provide details |
| 104 |
on all supported options. |
| 105 |
|
| 106 |
A :ref:`cookbook` of recipes describes how to use the various features of |
| 107 |
Modules and how to extend the :command:`module` command to achieve specific |
| 108 |
needs. |
| 109 |
|
| 110 |
Links |
| 111 |
^^^^^ |
| 112 |
|
| 113 |
* Web site: https://envmodules.io |
| 114 |
* Documentation: https://modules.readthedocs.io |
| 115 |
* Source repository: https://github.com/envmodules/modules |
| 116 |
* Issue tracking system: https://github.com/envmodules/modules/issues |
| 117 |
* Download releases: https://github.com/envmodules/modules/releases |
| 118 |
|
| 119 |
.. _Community: |
| 120 |
|
| 121 |
Community |
| 122 |
^^^^^^^^^ |
| 123 |
|
| 124 |
Modules is an open source project. Questions, discussion, and contributions |
| 125 |
are welcome. You can get in contact with the Modules community via: |
| 126 |
|
| 127 |
* the `modules-interest mailing list`_ |
| 128 |
(``[email protected]``) |
| 129 |
* the `Modules chat room`_ (``#modules:matrix.org``) |
| 130 |
|
| 131 |
The project is also present on several social media platforms: |
| 132 |
|
| 133 |
* X/Twitter: `@EnvModules`_ |
| 134 |
* Mastodon: `@[email protected]`_ |
| 135 |
* Bluesky: `@EnvModules.bsky.social`_ |
| 136 |
|
| 137 |
.. _modules-interest mailing list: https://sourceforge.net/projects/modules/lists/modules-interest |
| 138 |
.. _Modules chat room: https://matrix.to/#/#modules:matrix.org |
| 139 |
.. _@EnvModules: https://x.com/EnvModules |
| 140 |
.. _@[email protected]: https://mast.hpc.social/@EnvModules |
| 141 |
.. [email protected]: https://bsky.app/profile/envmodules.bsky.social |
| 142 |
|
| 143 |
Contributing |
| 144 |
^^^^^^^^^^^^ |
| 145 |
|
| 146 |
Modules project welcomes contributions of all kinds! Before submitting an |
| 147 |
issue or pull request, please take a moment to review our :ref:`Contributing |
| 148 |
guide<CONTRIBUTING>`. It includes important information about issue reporting, |
| 149 |
coding standards, etc. |
| 150 |
|
| 151 |
Please note that Modules project has a `Code of conduct`_. It ensures a |
| 152 |
respectful and inclusive environment for all contributors. By participating in |
| 153 |
the Modules community, you agree to abide by its rules. |
| 154 |
|
| 155 |
.. _Code of conduct: https://github.com/envmodules/modules?tab=coc-ov-file#readme |
| 156 |
|
| 157 |
Governance |
| 158 |
^^^^^^^^^^ |
| 159 |
|
| 160 |
Modules is part of the `High Performance Software Foundation`_ within the |
| 161 |
`Linux Foundation`_. |
| 162 |
|
| 163 |
This project adheres to a :ref:`Technical charter<CHARTER>`, which defines its |
| 164 |
governance model, decision-making process, and long-term vision. |
| 165 |
|
| 166 |
.. _High Performance Software Foundation: https://hpsf.io |
| 167 |
.. _Linux Foundation: http://linuxfoundation.org |
| 168 |
|
| 169 |
License |
| 170 |
^^^^^^^ |
| 171 |
|
| 172 |
Modules is distributed under the GNU General Public License, either version 2 |
| 173 |
or (at your option) any later version (`GPL-2.0-or-later`). |
| 174 |
|
| 175 |
.. only:: html |
| 176 |
|
| 177 |
.. toctree:: |
| 178 |
:hidden: |
| 179 |
:maxdepth: 2 |
| 180 |
:caption: Basics |
| 181 |
|
| 182 |
INSTALL |
| 183 |
INSTALL-win |
| 184 |
MIGRATING |
| 185 |
NEWS |
| 186 |
FAQ |
| 187 |
changes |
| 188 |
other-implementations |
| 189 |
|
| 190 |
.. toctree:: |
| 191 |
:hidden: |
| 192 |
:maxdepth: 2 |
| 193 |
:caption: Examples |
| 194 |
|
| 195 |
cookbook |
| 196 |
|
| 197 |
.. toctree:: |
| 198 |
:hidden: |
| 199 |
:maxdepth: 2 |
| 200 |
:caption: Reference |
| 201 |
|
| 202 |
ml |
| 203 |
module |
| 204 |
modulefile |
| 205 |
envml |
| 206 |
|
| 207 |
.. toctree:: |
| 208 |
:hidden: |
| 209 |
:maxdepth: 2 |
| 210 |
:caption: Development |
| 211 |
|
| 212 |
CONTRIBUTING |
| 213 |
devel |
| 214 |
design |
| 215 |
CHARTER |
| 216 |
GOVERNANCE |
| 217 |
acknowledgments |