---
title: "Modules Guide"
canonical: "https://kb.uconn.edu/space/SH/26062356547/Modules%20Guide"
format: markdown
---
# What are Modules?

**Environment Modules** is the system the cluster uses to manage different versions, installations, and dependencies of software. Using modules allows for many versions of the same software to coexist on the HPC, which is especially important for common dependencies (i.e cuda, OpenMPI, gcc). Modules work by adding software paths to your environment PATH variable. 

## When should I use modules?

Global modules of common and/or university-licensed programs are maintained by the HPC admins and available to all users. When not available globally, we encourage users to create group modules in their PI’s [/shared directory](https://kb.uconn.edu/space/SH/26034012236/Data+Storage+Guide#HPC-Storage-(short-term)) or within your /home directory for personal use. 

We recommend using conda to manage programs that are supported by it. Due to the difficulty in maintaining Python libraries, we recommend running all Python scripts through a conda installation. To get started with miniconda on the HPC, please refer to the following guide: [Miniconda Environment Set Up - Storrs HPC - UConn Knowledge Base](https://kb.uconn.edu/space/SH/26079723879/Miniconda+Environment+Set+Up).

Generally, programs are well-suited for modules if they are compiled from source, require a license, and/or are used by multiple people. Global modules can be created for programs that are widely used between many users, while we recommend creating [group/individual modules](https://uconn.atlassian.net/wiki/spaces/SH/pages/26062356547/Modules+Guide#Making-your-own-modules) for niche programs.

Contact us at [hpc@uconn.edu](mailto:hpc@uconn.edu) if you are interested in getting a global module installed.

## Viewing Modules

To view all available modules run the following command:

```
module avail
```

This will list out the applications that you can load into your environment.

To view available versions of a specific program, use the following syntax:

```
module avail <program_name>
```

Here’s an example with the programming language R:

```
[jth10001@login4 ~]$ module avail r
------------------------------------ /cm/shared/modulefiles ------------------------------------
r/4.2.0  r/4.2.1  r/4.2.2  r/4.3.2  r/4.4.0  r/4.4.1  r/4.4.2  rclone/1.61.0  readline/8.2
```

> ℹ️ **Note**: When running `module avail` by itself to view all programs, the output is handled with `less`. To scroll forward, press spacebar, and to quit, type q.

## Loading Your Environment

To load a module into your environment, use the following command:

```
module load <module_name>
```

where <module_name> is the program name in the list of available modules.

To load R version 4.2.2, for example, try the following:

```
module load r/4.4.2
```

Note that tab completion works for the names of modules. When typing the name of the module, you can press tab to autocomplete. 

If no version information is supplied, the most recent version is automatically loaded.

```
[jth10001@login4 ~]$ module load r
Loading r/4.4.2
  Loading requirement: gcc/14.2.0
```

Notice that, when loading r/4.4.2, the dependency gcc/14.2.0 was automatically loaded as well. This is an advantage of using modules - it simplifies the process of preparing your environment. 


To view all the loaded programs, you can run the command:

```
module list
```

In our example, the output looks like this:

```
[jth10001@login4 ~]$ module list
Currently Loaded Modulefiles:
 1) pre-module   2) post-module    3) gcc/14.2.0   4) r/4.4.2
```

Some modules have conflicts since multiple versions of the same program cannot be loaded at the same time. When trying to load an older version of R, for example, we get the following:

```
[jth10001@login4 ~]$ module load r/4.4.0
Loading r/4.4.0
  ERROR: r/4.4.0 cannot be loaded due to a conflict.
    HINT: Might try "module unload r" first.
```

As the hint suggests, I have to unload R first. To unload a module, use the following command:

```
module unload <module_name>
```

For this example, this command will unload R and its dependency.

```
[jth10001@login4 ~]$ module unload r
Unloading r/4.4.2
  Unloading useless requirement: gcc/14.2.0
```

Now, we can load the older version of R successfully as follows:

```
[jth10001@login4 ~]$ module load r/4.4.0
Loading r/4.4.0
  Loading requirement: gcc/11.3.0
[jth10001@login4 ~]$ module list
Currently Loaded Modulefiles:
 1) pre-module   2) post-module   3) gcc/11.3.0   4) r/4.4.0
```

> ⚠️ **Note**: We strongly advise against putting `module load` commands in your ~/.bashrc. This often leads to segmentation faults when running/compiling programs not properly set up within the module system.

# Making your own modules

Often, groups working on the HPC will require specific software versions or use niche programs that are not shared by other groups/users. In these cases, we recommend installing the programs and creating a module file within your group’s [/shared directory](https://kb.uconn.edu/space/SH/26034012236/Data+Storage+Guide#HPC-Storage-(short-term)).

### Formatting a module directory

To start, create a directory in your group’s /shared to store your module files.

```
cd /shared/<your_PI's_shared_directory>
mkdir groupmodules
```

We used the name `groupmodules` here, but any name will work.

The convention for module files is to make a directory with the name of the application and a text file with the version number. In our example, this would look like this:

```
mkdir groupmodules/r
touch groupmodules/r/4.4.2-1
```

Make sure new module files do not share the same name with a pre-existing module. Here, the suffix `-1` was added after the version to avoid a conflict with the preexisting r/4.4.2 global module in /cm/shared/modulefiles. Other information about the installation can be tacked onto the end of the version name in a similar manner. 

If multiple installations are required for the same version of a software, the files can be placed one level deeper. Here’s an example of what this looks like:

```
mkdir -p groupmodules/gromacs/2025.3
touch groupmodules/gromacs/2025.3/gpu
touch groupmodules/gromacs/2025.3/gpu-mpi
```

To make this directory accessible to module avail and load commands, open your .bashrc with your favorite text editor (i.e `nano ~/.bashrc`) and add the following line:

```
module use <path_to_module_directory>
```

where <path_to_module_directory> is where you put the modulefiles. For group members to access your shared modules, they would need to add this line into their .bashrc as well. 


> ℹ️ **Note**: You can also do this in your home directory to create personal modules

### Formatting module files

Once your module directory is set up and your desired programs are installed, you can access them by creating a module file. A complete description of the formatting/setup of module files can be found by using the following command on the cluster:

```
man modulefile
```

Module files are formatted as TCL scripts and thus use a specific syntax. We recommend that you refer to existing module files on the cluster on formatting. These can be found in `/cm/shared/modulefiles`.

Here is a basic example of a module file, accessible at `/cm/shared/modulefiles/cmake/3.23.2`:

```
#%Module1.0
# cmake modulefile
proc ModulesHelp{ } {
  puts stderr "\tAdds cmake/3.23.2 to your environment"
}

module-whatis "Adds cmake/3.23.2 to your environment"
module load pre-module

conflict cmake
setenv          MOD_APP         cmake
setenv          MOD_VER         3.23.2
set             prefix          /cm/shared/apps/cmake/3.23.2/cmake-3.23.2-linux-x86_64
prepend-path    PATH            $prefix/bin
prepend-path    MANPATH         $prefix/man


module load post-module
```

The key elements of this module file are the following:

1. The header `#%Module1.0` allows recognition as a module file
2. Module load commands (i.e `module load pre-module`, `module load post-module`) work within this file, allowing for easy loading of dependencies. Loads for pre-module and post-module should be placed before/after module loads and prepend-path
3. `conflict cmake` will raise an error if one attempts to load multiple versions of cmake
4. `set prefix` creates the variable $prefix as the base path for the module. This usually points towards the program directory, with subsequent paths defined from it
5. `prepend-path` adds the specified paths to the environment


A more nuanced example is the program GROMACS, accessible at `/cm/shared/modulefiles/gromacs/2024.4/gpu`

```
#%Module1.0

module-whatis "Basic install of GROMACS 2024.4 compiled with GPU support"
module load pre-module

module load      gcc/11.3.0
module load      hwloc
module load      tcl/8.6.12
module load      sqlite3/3.39.0
module load      python/3.10.5
module load      binutils/2.26
module load      zlib/1.2.12
module load      fftw3/3.3.10
module load      cuda/12.3
module load      lapack/3.11.0

conflict gromacs
setenv          MOD_APP         gromacs
setenv          MOD_VER         2024.4-gpu
set prefix /gpfs/sharedfs1/admin/hpc2.0/apps/gromacs/2024.4/gpu

prepend-path    PATH            $prefix/bin
prepend-path    LD_LIBRARY_PATH $prefix/lib64
prepend-path    INCLUDE         $prefix/include
prepend-path    MANPATH         $prefix/share/man
prepend-path    PKG_CONFIG_PATH $prefix/lib64/pkgconfig

system source $prefix/bin/GMXRC

module load post-module

```

This program has a large number of dependencies, each accessed through `module load`. The line `system source $prefix/bin/GMXRC` is used to run a script through bash, which is required for GROMACS to run. Through the module file, all of the required steps/commands for preparing your environment to run can be automated.