Skip to main content

Why Customize a Container Environment?

Prebuilt container images provide a convenient starting point, but they may not contain all of the software required for a particular project.

Most Apptainer images are distributed as .sif files, which are typically read-only. If you need to install additional software or make persistent changes to a container, Apptainer provides overlays, which add a writable layer on top of the original image while leaving the .sif file unchanged.

Example: Creating a Custom Directory with an Overlay​

Pull a Python container image from Docker Hub:

apptainer pull python.sif docker://python:3.10

Create a writable overlay:

apptainer overlay create --size 1024 python_overlay.ext3

Launch the container with the overlay attached:

apptainer shell \
    --overlay python_overlay.ext3:rw \
    python.sif

Verify that numpy is not installed in the base image:

python -c "import numpy"

You should see:

ModuleNotFoundError: No module named 'numpy'

Install numpy:

pip install numpy

Verify that the packages are available:

python -c "import numpy; print(numpy.__version__)"

Exit the container:

exit

The next time you want to use the customized environment, launch the container using the same overlay:

apptainer shell \
    --overlay python_overlay.ext3:rw \
    python.sif

This demonstrates that software installed within the overlay persists across sessions, while the original .sif image remains unchanged.

info

In the examples above we started a shell session with the overlay in read-write mode (:rw).

warning

Only open the overlay in writable mode when you are adding packages to it. When not loading packages you should use read-only mode (:ro).

If you leave the overlay open in read-write mode no other process will be able to open it in either read-write or read-only mode.

read-only overlays can be used by multiple processes which is why they are useful for parallel processing. :::