Skip to main content

Using Apptainer to Run Commands on Torch

warning

Container workloads should be run on compute nodes rather than login nodes.

While simple commands may work on a login node, pulling images, launching software, installing packages, or building environments can consume significant CPU, memory, and storage resources. These activities should be performed within an interactive Slurm allocation or a batch job.

Torch provides many prebuilt container images under:

ls /share/apps/images/
note

Torch provides container images with both .sif and .sqf extensions.

.sif is the standard Apptainer image format. Some Torch-provided application images use .sqf and may be intended to be launched through wrapper scripts such as run-anaconda3-2024.10-1.bash.

When available, use the wrapper script documented for that application. For general Apptainer examples in this tutorial, we use .sif images because they work directly with apptainer exec, apptainer run, and apptainer shell.

For this tutorial, we will use the Ubuntu 24.04 image that is already available on the cluster.

Running Your First Container​

Apptainer images can define a default action that runs when the container starts.

To launch a container and execute its default action, use apptainer run:

apptainer run /share/apps/images/ubuntu-24.04.3.sif

Depending on how the image was built, this command may produce output, launch an application, or simply start and exit.

The important point is that with apptainer run, Apptainer executes the default action defined by the image creator.

To run a specific command, use apptainer exec.

Running Specific Commands Within a Container​

apptainer exec allows us to specify exactly what command should run inside the container.

For example:

apptainer exec /share/apps/images/ubuntu-24.04.3.sif /bin/echo "Hello World!"

Output:

Hello World!

The Difference Between apptainer run and apptainer exec​

Both apptainer run and apptainer exec start a container, but they serve different purposes.

apptainer run executes the default action defined by the image creator. Depending on how the image was built, this may launch an application, run a script, or perform another predefined task.

apptainer exec allows you to specify exactly which command should run inside the container. Rather than relying on the image's default behavior, you provide the command directly.

Opening an Interactive Shell Within a Container​

There are many reasons why you might want to use a container interactively.

  • debugging (software, bind mounts, hardware integrations, etc.)
  • testing software upgrades
  • rapid Software Prototyping
  • data exploration

Apptainer provides the apptainer shell command for this purpose.

Launch a shell inside the Ubuntu container:

apptainer shell /share/apps/images/ubuntu-24.04.3.sif

You should see a prompt similar to:

Singularity>

You can now run commands inside the container:

whoami
pwd
cat /etc/os-release

Example output:

PRETTY_NAME="Ubuntu 24.04.3 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
...

Notice that the prompt changes to indicate that you are working inside the container environment.

When you are finished, leave the container with:

exit

This returns you to your normal shell on Torch.