> For the complete documentation index, see [llms.txt](https://docs.tensorwave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tensorwave.com/slurm/modules.md).

# Modules

### Overview

Environment modules provide pre-installed software (frameworks, tools, and container-backed environments) without requiring you to build or pull images yourself. They are a lightweight alternative to containers when you do not need full environment isolation or a custom software stack.

Two module systems are available:

* **Lmod** — the primary module system. Use it to load and switch between pre-installed frameworks and tools.
* **SHPC (Singularity HPC)** — extends Lmod with container-backed modules. SIF images are installed into a shared module tree so that `module load` transparently runs commands inside the container.

Modules are available on both login and compute pods. Load them in your batch script before calling `srun` so the environment is propagated to all tasks.

***

### Lmod

[Lmod](https://lmod.readthedocs.io) is the module system on this cluster. Common commands:

```bash
module avail                  # list all available modules
module avail torch            # search by name
module load torch/2.7         # load a module
module list                   # show loaded modules
module unload torch/2.7       # unload a module
module purge                  # unload everything
```

**Example: batch job using a module**

```bash
#!/bin/bash
#SBATCH --job-name=torch-module
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=1
#SBATCH --gpus-per-node=8
#SBATCH --cpus-per-task=48
#SBATCH --time=02:00:00

module load torch/2.7

srun python -m torch.distributed.run \
  --nproc_per_node 8 \
  --nnodes $SLURM_NNODES \
  train.py
```

***

### SHPC (Singularity HPC)

SHPC installs container images as Lmod modules onto a shared volume, so `module load` transparently runs commands inside the container. Installed modules are available to all users.

By default, shpc installs modules under `/mnt/shpc`. This is intended to be a global admin-managed registry. Users are expected to configure their own shpc installation target:

**Configure private module tree:**

```bash
# Configure shpc to look for private modules
shpc config inituser
shpc config set module_base    "$HOME/shpc/modules"
shpc config set container_base "$HOME/shpc/containers"
# Configure LMOD to look for private modules
module use "$HOME/shpc/modules"
echo 'module use "$HOME/shpc/modules"' >> $HOME/.bashrc
```

Admins can omit this step to install packages globally. The following install commands will target `/mnt/shpc`, and will be available to all users.

**Install a module from the curated registry:**

```bash
shpc show                         # list available recipes
shpc install rocm/pytorch         # pull SIF, write modulefile
module avail                      # confirm it is visible
module load rocm/pytorch
```

**Install an arbitrary OCI image:**

```bash
shpc add docker://<registry>/<image>:<tag>
# Edit the generated recipe at /mnt/modulestore/shpc/registry/...
shpc install <namespace>/<image>:<tag>
```

Note: **running module-installed apps only works on privileged pods** (worker-pods and VM-based login pods). If you encounter the error `ERROR : Failed to create mount namespace: mount namespace requires privileges, check Apptainer installation`, try running the same command with `srun`.

Global modules and container images are stored on the shared `modulestore` volume (`/mnt/modulestore`), so an install on a login pod is immediately available on compute pods without any additional steps. Users are encouraged to install their modules in their `/home/$USER` directory.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tensorwave.com/slurm/modules.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.