Tutorials/Apptainer-PullingImages

Pulling Apptainer Images

Getting Started

First, grab an interactive session in a compute node.

Then make sure your module environment is clean and Apptainer is loaded:

module reset
module load utilities Apptainer

Also, please make sure to store image and in your lustre folders.

Your First Pull

Let's start by pulling a simple "hello world" container image:

apptainer pull ./hello-world.sif shub://vsoch/hello-world

That is a lot happening in one line, so let's break it down piece by piece:

Part	What it means
apptainer pull	The Apptainer command to download a container image.
./hello-world.sif	The output filename. This is where Apptainer will save the downloaded image. The .sif extension stands for Singularity Image Format — Apptainer's own container format. The ./ means "save it in my current directory".
shub://vsoch/hello-world	The source to pull from. shub:// tells Apptainer to look at Singularity Hub, a public registry for container images. vsoch/hello-world is the user and image name, much like a path on GitHub.

Once the command finishes, you will have a file called hello-world.sif in your current directory. You can verify this:

ls -lh hello-world.sif

This .sif file is your container — a single, portable file that contains an entire operating system and software environment. You can copy it, move it, or share it just like any other file.

Running the Container

The simplest way to use a container is with apptainer run. This executes whatever default action the container was built to perform:

apptainer run ./hello-world.sif

You should see a friendly output from the container. That is it — you just ran software inside a container.

Opening a Shell Inside the Container

Instead of running the container's default action, you can open an interactive shell inside it. This lets you look around and explore the container's environment as if you had logged into a different machine.

apptainer shell ./hello-world.sif

You will notice your prompt changes (usually to Apptainer>), indicating that you are now "inside" the container. Type exit when you want to leave.

The Container is Not Fully Isolated (by Default)

Here is something important that surprises many beginners: by default, Apptainer does not fully isolate the container from the host system. Your home directory and parts of the host filesystem are still visible inside the container.

Try this while inside the shell:

apptainer shell ./hello-world.sif

Then, from inside the container:

Apptainer> mkdir ~/test-from-container
Apptainer> ls ~/test-from-container
Apptainer> exit

Now, back on the host:

ls ~/test-from-container

The directory is there — on your real filesystem. The container was able to create it because your home directory was mounted inside the container by default. This is by design: it makes it easy to work with your own files, but it means the container is not completely separate from the host.

Full Isolation with --containall

If you want the container to be fully isolated from the host system — no access to your home directory, no shared environment variables, no host filesystems — use the --containall flag (or its short form -C):

apptainer shell --containall ./hello-world.sif

Now try the same thing from inside:

Apptainer> mkdir ~/test-isolated
Apptainer> exit

Back on the host:

ls ~/test-isolated

This time, the directory does not exist on your host. The container was completely isolated — anything it created lived only inside the container's temporary environment and was discarded when you exited.

Use --containall (or -C) when you want a clean, reproducible environment that does not interfere with (or depend on) the host system.

Running a Specific Command with exec

Sometimes you do not want a full interactive shell — you just want to run a single command inside the container and get the output. That is what apptainer exec is for.

For example, let's check which operating system is inside this container:

apptainer exec ./hello-world.sif cat /etc/lsb-release

You should see output similar to:

DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=14.04
DISTRIB_CODENAME=trusty
DISTRIB_DESCRIPTION="Ubuntu 14.04.6 LTS"

The container is running Ubuntu 14.04 — regardless of what operating system your host machine is running. This is the power of containers: you can run software built for a completely different OS environment without any conflicts.

The pattern for exec is:

apptainer exec [options] container.sif command [arguments]

Summary

You now know the three main ways to interact with a pulled Apptainer container:

Command	What it does
apptainer run container.sif	Runs the container's default action
apptainer shell container.sif	Opens an interactive shell inside the container
apptainer exec container.sif command	Runs a single specific command inside the container

And one important flag to remember:

Flag	What it does
--containall (or -C)	Fully isolates the container from the host (no shared home directory, no host environment)