Software Modules¶

Environment Modules (short: Modules) are the way software is made available on NHR@KIT systems. Software is installed on the system but not active until explicitly loaded — this allows programs of the same category or different versions to coexist without conflicts.

Modules can be loaded and unloaded as needed, and cover compilers, libraries, and software packages. Each module configures the shell environment for a specific program by setting variables such as PATH and LD_LIBRARY_PATH.

On HoreKa 2, the module system is implemented by Lmod, a modern, Lua-based module manager that supports a hierarchical software stack. Most software packages are built and installed using EasyBuild — each EasyBuild installation automatically generates the corresponding Lmod module, which users then load via module load.

In addition to the centrally provided modules, software can also be made available through:

Self-compiled programs — build your own software and use modules to provide dependencies
Containers — run pre-packaged applications with Apptainer or Enroot
Python packages — install packages via pip into a virtual environment

Common use cases¶

The following scenarios cover the most common ways users interact with modules. Each points to the relevant sections below.

I want to run a software package available on the system
Find the module with module spider or module avail. Then use module load — either by adding it to your batch script, or by running it directly in your shell for an interactive session.

I want to compile my own code
Use module spider or module avail to find suitable compilers and libraries. Load them with module load in your shell before building. Note the exact module versions — you will need to load the same ones at runtime.

I want to run software I compiled myself
Add module load for the same modules that were active at compile time to your batch script or shell session. The runtime libraries must match the build-time libraries exactly.

I want to know what is currently loaded or what a module does
Use module list to see active modules, and module show to inspect what a module changes in your environment before loading it.

Quick Reference¶

Command	Description
`module avail`	List all directly loadable modules
`module spider <name>`	Search for a module across the full hierarchy
`module list`	Show currently loaded modules
`module load <module>`	Load a module into the current session
`module unload <module>`	Unload a specific module
`module purge`	Unload all modules
`module show <module>`	Show what a module sets in your environment
`module help <module>`	Show the help text for a module

Module naming convention¶

Module names on HoreKa 2 follow the EasyBuild naming pattern Name/Version-Toolchain. This is what you pass to module load, module spider, and other Lmod commands. For example:

GCC/13.3.0
OpenMPI/5.0.3-GCC-13.3.0
FFTW/3.3.10-gompi-2024a

This differs from the legacy HoreKa naming scheme (category/softwarename/version).

Always specify a version explicitly

When multiple versions of a module are available, one is designated the default (marked with (D) in module avail). The default may change over time. To ensure reproducibility, always load a specific version:

$ module load GCC/13.3.0

Additional software stacks¶

Beyond the EasyBuild-managed software stack, NHR@KIT provides two additional module collections:

Commercial software — licensed applications provided centrally; modules are located under /software/commercial
Community software — software maintained by research communities rather than the HPC operations team; modules are located under /software/community

These stacks are available alongside the main stack and can be searched with module spider or module avail as usual. Note that the EasyBuild Name/Version-Toolchain naming convention is not enforced here — module names may follow different schemes depending on the software or community.

Using modules¶

Searching for modules¶

Command	Description
`module avail`	List all directly loadable modules given the current environment
`module spider <name>`	Search for a module across the full hierarchy, including unloadable ones
`module spider <name>/<version>`	Show dependencies required to load a specific version

Use module spider to search across all levels of the hierarchy, including modules whose dependencies are not yet loaded:

$ module spider GCC

To find all available versions of a specific module:

$ module spider GCC/13.3.0

This also shows which modules need to be loaded first. Use module avail to list only the modules that are directly loadable given your current environment:

$ module avail

Loading and unloading modules¶

Command	Description
`module load <module>`	Load a module into the current session
`module unload <module>`	Unload a specific module
`module purge`	Unload all currently loaded modules
`module list`	Show all currently loaded modules

Load a module into your current shell session:

$ module load GCC/13.3.0

Loading a module affects only the current session. Dependent modules are loaded automatically. You cannot load two versions of the same software simultaneously — loading a new version automatically unloads the previous one.

Unload a specific module:

$ module unload GCC/13.3.0

Unload all modules at once:

$ module purge

Warning

module purge unloads all modules immediately without confirmation.

Inspecting a module¶

Command	Description
`module show <module>`	Show what a module sets in your environment, without loading it
`module help <module>`	Show the help text provided by the module

To see what environment variables a module sets — without loading it — use module show:

$ module show GCC/13.3.0

The output lists all paths and variables that would be modified when the module is loaded.

Warning

module show does not load the module.

User modules¶

Beyond the centrally provided software stack, you can extend the module system with your own module files or use module files provided by a colleague or a project directory.

Use module use <path> to add a directory to the module search path — Lmod will then make any module files found there available alongside the system modules:

$ module use /path/to/my/modulefiles

To remove a directory from the search path:

$ module unuse /path/to/my/modulefiles

You can write your own module files in Lua (.lua) or the legacy Tcl format. A minimal Lua module file looks like this:

help([[My custom software]])

whatis("Name: mysoftware")
whatis("Version: 1.0")

local root = "/path/to/mysoftware"
prepend_path("PATH", pathJoin(root, "bin"))
prepend_path("LD_LIBRARY_PATH", pathJoin(root, "lib"))

Place this file in a directory and add it with module use to make it loadable via module load.

Pitfalls and caveats¶

Module conflicts You cannot have two versions of the same software loaded simultaneously. Loading a second version automatically replaces the first. If you need to switch toolchains or software versions, use module purge or module unload first to start from a clean state.

Batch jobs inherit the login shell environment Slurm's default behavior (#SBATCH --export=ALL) passes the entire environment of the submitting shell — including all loaded modules — to the job. This can cause hard-to-reproduce errors if your job picks up modules you loaded interactively but did not explicitly specify in the script. To prevent this, use #SBATCH --export=NONE in your job script to start with a clean environment, then load only the modules your job actually needs. Use module list before submitting to verify what is currently loaded in your shell.

Default versions can change When no version is specified, Lmod loads the default version (marked (D) in module avail). Defaults may be updated over time. Always specify an explicit version in batch scripts to ensure reproducibility.

Tip

Run module list before submitting a job to verify that exactly the modules you expect are loaded.

Getting help¶

Show help for a specific module:

$ module help GCC/13.3.0

Show general help for the module command:

$ module help
$ man module

The official Lmod documentation is available at lmod.readthedocs.io.