apptainer build

Build an Apptainer image



When Apptainer builds the container, output can be one of a few formats:

default: The compressed Apptainer read only image format (default) sandbox: This is a read-write container within a directory structure

note: It is a common workflow to use the “sandbox” mode for development of the container, and then build it as a default Apptainer image for production use. The default format is immutable.


The build spec target is a definition (def) file, local image, or URI that can be used to create an Apptainer container. Several different local target formats exist:

def file : This is a recipe for building a container (examples below) directory: A directory structure containing a (ch)root file system image: A local image on your machine (will convert to sif if

it is legacy format)

Targets can also be remote and defined by a URI of the following formats:

library:// an image library (no default) docker:// a Docker/OCI registry (default Docker Hub) shub:// an Apptainer registry (default Singularity Hub) oras:// an OCI registry that holds SIF files using ORAS

Temporary files:

The location used for temporary directories defaults to ‘/tmp’ but can be overridden by the TMPDIR environment variable, and that can be overridden by the APPTAINER_TMPDIR environment variable. The temporary directory used during a build must be on a filesystem that has enough space to hold the entire container image, uncompressed, including any temporary files that are created and later removed during the build. You may need to set APPTAINER_TMPDIR or TMPDIR when building a large container on a system that has a small /tmp filesystem.

apptainer build [local options...] <IMAGE PATH> <BUILD SPEC>



        Bootstrap: library
        From: debian:9

        Bootstrap: docker
        From: tensorflow/tensorflow:latest
        IncludeCmd: yes # Use the CMD as runscript instead of ENTRYPOINT

    Singularity Hub:
        Bootstrap: shub
        From: singularityhub/centos

        Bootstrap: yum
        OSVersion: 7
        Include: yum

        Bootstrap: zypper # on SLE system registration of build host is used
        Include: zypper

        Bootstrap: zypper
        Include: zypper

        Bootstrap: debootstrap
        OSVersion: trusty

    Local Image:
        Bootstrap: localimage
        From: /home/dave/starter.img

        Bootstrap: scratch # Populate the container with a minimal rootfs in %setup


The following sections are presented in the order of processing, with the exception
that labels and environment can also be manipulated in %post.

        echo "This is a scriptlet that will be executed on the host, as root before"
        echo "the container has been bootstrapped. This section is not commonly used."

        echo "This is a scriptlet that will be executed on the host, as root, after"
        echo "the container has been bootstrapped. To install things into the container"
        echo "reference the file system location with $APPTAINER_ROOTFS."

        /path/on/host/file.txt /path/on/container/file.txt
        relative_file.txt /path/on/container/relative_file.txt

        echo "This scriptlet section will be executed from within the container after"
        echo "the bootstrap/base has been created and setup."

        export HAN VADER LUKE

        echo "Define any test commands that should be executed after container has been"
        echo "built. This scriptlet will be executed from within the running container"
        echo "as the root user. Pay attention to the exit/return value of this scriptlet"
        echo "as any non-zero exit code will be assumed as failure."
        exit 0

        echo "Define actions for the container to be executed with the run command or"
        echo "when container is executed."

        echo "Define actions for container to perform when started as an instance."

        HELLO MOTO
        KEY VALUE

        This is a text file to be displayed with the run-help command.


    Build a sif file from an Apptainer recipe file:
        $ apptainer build /tmp/debian0.sif /path/to/debian.def

    Build a sif image from the Library:
        $ apptainer build /tmp/debian1.sif library://debian:latest

    Build a base sandbox from DockerHub, make changes to it, then build sif
        $ apptainer build --sandbox /tmp/debian docker://debian:latest
        $ apptainer exec --writable /tmp/debian apt-get install python
        $ apptainer build /tmp/debian2.sif /tmp/debian


-B, --bind stringArray         a user-bind path specification. spec has the format src[:dest[:opts]],where src and dest are outside and inside paths. If dest is not given,it is set equal to src. Mount options ('opts') may be specified as 'ro'(read-only) or 'rw' (read/write, which is the default).Multiple bind paths can be given by a comma separated list.
    --build-arg strings        defines variable=value to replace {{ variable }} entries in build definition file
    --build-arg-file string    specifies a file containing variable=value lines to replace '{{ variable }}' with value in build definition files
    --disable-cache            do not use cache or create cache
    --docker-host string       specify a custom Docker daemon host
    --docker-login             login to a Docker Repository interactively
-e, --encrypt                  build an image with an encrypted file system
-f, --fakeroot                 build with the appearance of running as root (default when building from a definition file unprivileged)
    --fix-perms                ensure owner has rwX permissions on all container content for oci/docker sources
-F, --force                    overwrite an image file if it exists
-h, --help                     help for build
    --json                     interpret build definition as JSON
    --library string           container Library URL
    --mount stringArray        a mount specification e.g. 'type=bind,source=/opt,destination=/hostopt'.
    --no-cleanup               do NOT clean up bundle after failed build, can be helpful for debugging
    --no-https                 use http instead of https for docker:// oras:// and library://<hostname>/... URIs
-T, --notest                   build without running tests in %test section
    --nv                       inject host Nvidia libraries during build for post and test sections
    --nvccli                   use nvidia-container-cli for GPU setup (experimental)
    --passphrase               prompt for an encryption passphrase
    --pem-path string          enter an path to a PEM formatted RSA key for an encrypted container
    --rocm                     inject host Rocm libraries during build for post and test sections
-s, --sandbox                  build image as sandbox format (chroot directory structure)
    --section strings          only run specific section(s) of deffile (setup, post, files, environment, test, labels, none) (default [all])
-u, --update                   run definition over existing container (skips header)
    --userns                   build without using setuid even if available
    --warn-unused-build-args   shows warning instead of fatal message when build args are not exact matched
    --writable-tmpfs           during the %test section, makes the file system accessible as read-write with non persistent data (with overlay support only)


Linux container platform optimized for High Performance Computing (HPC) and Enterprise Performance Computing (EPC)

Auto generated by spf13/cobra on 12-Jul-2024