Software: Modules, Conda and Containers

This page covers the three ways to get software on Boole: the cluster’s modules, your own Conda environments, and Apptainer containers.

Loading Software with Modules

Software on Boole is provided as modules, managed by Lmod. Nothing is available until you load it: module load python/3.11.9 puts that Python on your PATH, and module purge unloads everything.

Boole has two software trees, one built for Ubuntu 22.04 and one for Ubuntu 24.04. The compute nodes run Ubuntu 24.04, but the 22.04 tree is listed first by default. Run these two lines before loading modules, on the login node and in every job script:

module unuse /opt/spack/spack/share/spack/lmod/linux-ubuntu22.04-x86_64/Core
module use /opt/spack/spack/share/spack/lmod/linux-ubuntu24.04-x86_64/Core

Then:

module avail                # everything you can load
module spider gcc           # search by name, and list versions
module load python/3.11.9   # load a module
module list                 # what is loaded now

The examples in this guide use python/3.11.9, openmpi/5.0.5, py-mpi4py/4.0.1 and py-numpy/2.1.2. Load python before Python packages such as py-numpy.

The GPU nodes (physical-gpu) don’t have the module command. GPU jobs use a Python environment in your home directory instead; see Getting the Most from Boole’s GPUs.

Modules in Job Scripts

Every example job script starts with this block. The lines before module purge (unset -f and source ... lmod) make the module command work reliably inside jobs. Copy the whole block as it is:

# --- Boole module setup: copy these lines as they are into your own scripts ---
unset -f module ml 2>/dev/null || true
if [[ -r /etc/profile.d/lmod.sh ]]; then
  source /etc/profile.d/lmod.sh
elif [[ -r /usr/share/lmod/lmod/init/bash ]]; then
  source /usr/share/lmod/lmod/init/bash
fi
module purge
module unuse /opt/spack/spack/share/spack/lmod/linux-ubuntu22.04-x86_64/Core
module use /opt/spack/spack/share/spack/lmod/linux-ubuntu24.04-x86_64/Core
# --- end of module setup ---

The script’s first line must be #!/bin/bash -l so it runs as a login shell. The job templates in Job Script Templates already include all of this.

Conda / Miniforge

Optional; the examples in this guide don’t need it.

To manage your own Python packages independently of the cluster modules, use Miniforge (a free Conda installer) in your home directory. You can create isolated environments and install packages without affecting other users.

Installing Miniforge

cd $HOME
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

Follow the prompts: accept the license and install into the default $HOME/miniforge3. If asked whether to initialize Conda, answering yes edits your ~/.bashrc so Conda’s base environment is active in every new shell. Then activate Conda in your current shell:

source $HOME/miniforge3/bin/activate

Creating and Managing Environments

conda create --name my_env python=3.11   # create an environment
conda activate my_env                    # use it
conda deactivate                         # leave it
conda env list                           # list environments
conda env remove --name my_env           # delete one

Installing Packages

Within an activated environment:

conda install numpy scipy matplotlib     # from conda-forge
pip install pandas seaborn               # or with pip
conda update numpy
conda remove matplotlib

Best Practices

  • Activate your environment in the job script before running Python (source $HOME/miniforge3/bin/activate my_env). The conda.slurm template in Job Script Templates does this.

  • Use one environment per project.

  • Don’t install packages into base; use named environments.

  • Don’t mix a Conda environment and the cluster’s python modules in the same job. Use one or the other.

Using a Conda Environment as a Jupyter Kernel

If you already have a Conda environment set up for your work, you can make it available in Jupyter Notebook or JupyterLab as a selectable kernel.

Activate the environment and install ipykernel into it:

conda activate my_env
conda install ipykernel

Register the environment with Jupyter:

python -m ipykernel install \
  --user \
  --name my_env \
  --display-name "Python (my_env)"

Replace my_env with your environment name. The kernel specification will be created under ~/.local/share/jupyter/kernels/.

Launch JupyterLab through the HPC platform, open a notebook, and choose the kernel named Python (my_env) from the kernel selector.

To verify that the kernel is registered, run:

jupyter kernelspec list

You can inspect the kernel definition with:

cat ~/.local/share/jupyter/kernels/my_env/kernel.json

The argv entry should point to the Python interpreter inside the Conda environment.

Running Docker Images with Apptainer

Optional.

Apptainer runs containers on HPC. It can turn a Docker image into a single SIF file and run it on any partition (cloud, physical and physical-gpu), without needing Docker or administrator rights.

Start an interactive job, then pull a Docker image:

srun --partition=cloud --cpus-per-task=1 --mem=2G --time=00:15:00 --pty bash
apptainer pull docker://hello-world

This creates hello-world_latest.sif in the current directory. Run it:

apptainer run hello-world_latest.sif
Hello from Docker!
This message shows that your installation appears to be working correctly.

Other useful commands:

Command

Description

apptainer pull docker://<image>

Downloads the image once and converts it to a reusable .sif file.

apptainer run <file>.sif

Runs the container’s default program.

apptainer exec <file>.sif ls /

Runs one command inside the container.

apptainer shell <file>.sif

Opens a shell inside the container.

apptainer inspect <file>.sif

Shows the image’s metadata.

Type exit to leave the container shell, and again to end the job.

The batch version is examples/containers/apptainer_hello.slurm. It pulls the image the first time and prints WARNING: passwd file doesn't exist in container; that warning is harmless.

#!/bin/bash
#SBATCH --job-name=apptainer-hello
#SBATCH --output=apptainer-hello-%j.out
#SBATCH --partition=cloud
#SBATCH --cpus-per-task=2
#SBATCH --mem=4G
#SBATCH --time=00:10:00

set -euo pipefail

SUBMIT_DIR="${SLURM_SUBMIT_DIR:-$PWD}"
cd "$SUBMIT_DIR"

IMAGE="${SUBMIT_DIR}/hello-world_latest.sif"

echo "Running on host: $(hostname)"
echo "Submit directory: ${SUBMIT_DIR}"
echo "Container image: ${IMAGE}"

if [[ ! -f "$IMAGE" ]]; then
  apptainer pull docker://hello-world
fi

apptainer inspect "$IMAGE"
apptainer run "$IMAGE"

Download apptainer_hello.slurm