apptainer(1)                                                      apptainer(1)



<?><?><?> (NAME)
       apptainer-build - <?><?><?><?> <?><?> <?><?><?><?><?> Apptainer



<?><?><?><?><?> <?><?><?><?><?> (SYNOPSIS)
       apptainer build [local options...]



<?><?><?><?><?><?><?> (DESCRIPTION)
       <?><?><?><?> <?><?><?><?><?> (IMAGE PATH):


       <?><?><?><?><?><?> <?><?> Apptainer <?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?><?>
       <?><?><?> <?><?> <?><?><?> <?><?><?><?> <?><?><?> <?><?><?><?>:

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


       <?><?><?><?>: <?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?><?><?> <<sandbox>> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?><?><?><?> <?> <?><?><?> <?><?><?><?>
       <?><?> <?><?> <?><?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?> Apptainer <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?> <?><?><?><?> <?><?><?><?><?><?><?> <?><?><?>. <?><?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?>.


       <?><?><?><?><?><?> <?><?><?><?> (BUILD SPEC):


       <?><?><?> <?><?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> (def)<?> <?><?><?><?><?> <?><?><?><?><?> <?><?> URI
       <?><?><?> <?><?> <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?> <?><?><?><?><?><?><?> Apptainer <?><?><?><?><?><?><?> <?><?><?>.
       <?><?><?><?><?> <?><?><?><?> <?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?> <?><?><?><?>:

         def file  : This is a recipe for building a container (examples below)
         buildkit:   A build context directory, containing a Dockerfile to build
         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)


       <?><?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?>
       <?><?> <?><?><?> <?><?><?> <?><?><?><?> <?> <?><?> <?><?> URI <?><?>
       <?><?><?><?><?><?><?><?> <?><?><?> <?><?><?><?> <?><?><?><?>:

         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
         ipfs://     an IPFS cluster, using a HTTP gateway


       <?><?><?><?><?><?><?><?><?><?> <?><?><?><?> (Temporary files):


       <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?><?><?> <?>/tmp <?><?><?><?> <?><?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?>
       TMPDIR <?><?><?><?><?><?><?><?> <?><?><?><?> <?> <?><?><?> <?><?>
       <?><?><?> <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?> APPTAINER_TMPDIR <?><?><?><?><?><?><?><?> <?><?><?>.
       <?><?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?> <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?><?> <?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?> <?><?><?> <?><?><?> <?><?><?><?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?>. <?><?><?><?> <?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?> <?><?><?><?><?><?><?> <?><?><?><?> <?><?><?> <?><?><?><?><?><?>
       <?><?> <?><?><?><?><?><?><?><?><?><?> <?>/tmp <?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?><?> APPTAINER_TMPDIR
       <?><?> TMPDIR <?><?><?><?><?> <?><?><?><?><?>.



<?><?><?><?><?><?><?><?> (OPTIONS)
       --arch="amd64"      <?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?>
       <?><?><?><?>


       --arch-variant=""   <?><?><?><?> <?><?><?><?><?><?> <?><?> <?><?><?>
       <?><?><?><?> <?><?><?><?>


       --authfile=""  <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?> Docker <?><?><?> <?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?>/<?><?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?> OCI


       -B, --bind=[]  <?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?> <?><?><?><?><?>. <?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?> src[:dest[:opts]] <?><?><?><?> <?><?> <?><?> <?><?> src
       <?> dest <?><?><?><?><?><?><?> <?><?><?><?> <?> <?><?><?><?>
       <?><?><?><?><?>. <?><?><?> dest <?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?> <?><?> src <?><?> <?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?>. <?><?><?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?> ('opts') <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?><?>
       'ro' (<?><?><?><?><?><?><?><?><?><?><?>) <?><?> 'rw'
       (<?><?><?><?><?><?><?>/<?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?><?>) <?><?><?><?><?> <?><?><?><?>.
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?> <?><?> <?><?><?><?><?> <?><?><?> <?><?><?>
       <?><?> <?><?><?><?> <?><?><?><?><?> <?><?><?>.


       --build-arg=[]      <?><?><?><?><?> variable=value <?><?><?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?> {{ variable }}
       <?><?> <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>


       --build-arg-file=""      <?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?><?><?><?> <?><?><?><?> <?><?><?><?> variable=value
       <?><?><?><?> <?><?><?><?><?><?><?><?> '{{ variable }}' <?><?>
       <?><?><?><?><?> <?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>


       --buildkit-host=""  <?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?> BuildKit


       --data[=false]      <?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?><?><?> <?><?> <?><?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?>


       --disable-cache[=false]  <?><?><?> <?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?> (cache) <?><?> <?><?><?> <?><?><?><?><?>
       <?><?>


       --docker-host=""    <?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?><?><?> Docker


       --docker-login[=false]   <?><?><?><?> <?><?><?><?><?><?> <?><?> <?><?>
       <?><?><?><?> Docker


       -e, --encrypt[=false]    <?><?><?><?> <?><?><?><?><?> <?><?> <?><?>
       <?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?><?>


       -f, --fakeroot[=false]   <?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?> (<?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?> <?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?>)


       --fix-perms[=false]      <?><?><?><?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?> rwX <?><?><?><?> <?><?><?><?> <?><?><?>
       <?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?> oci/docker


       -F, --force[=false]      <?><?><?><?><?><?><?><?> <?><?><?><?><?><?>
       <?><?><?><?><?> <?><?> <?><?><?><?> <?><?><?><?>


       -h, --help[=false]  <?><?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>
       (build)


       --json[=false]      <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?> <?><?>
       <?><?><?><?> JSON


       --library=""   <?><?><?><?><?> <?><?><?><?><?><?><?><?> (URL)
       <?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?>


       --mksquashfs-args=""     <?><?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?> mksquashfs
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?> SIF


       --mount=[]     <?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?>
       'type=bind,source=/opt,destination=/hostopt'.


       --no-cleanup[=false]     <?><?><?> <?><?><?><?><?><?><?><?>
       <?><?><?><?> <?><?> <?><?> <?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?>
       <?><?><?><?> <?><?><?><?>


       --no-https[=false]  <?><?><?><?><?><?><?> <?><?> http <?><?> <?><?><?>
       https <?><?><?><?> URI<?><?><?> docker:// <?> oras:// <?>
       library:///...


       -T, --notest[=false]     <?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?><?><?><?><?><?> <?><?> <?><?><?> %test


       --nv[=false]   <?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?><?>
       Nvidia <?><?><?><?><?><?> <?><?> <?><?><?> <?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?> post <?> test


       --nvccli[=false]    <?><?><?><?><?><?><?> <?><?> nvidia-container-cli
       <?><?><?><?> <?><?><?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?>
       <?><?><?><?><?><?><?> GPU (<?><?><?><?><?><?><?>)


       --passphrase[=false]     <?><?><?><?><?><?><?> <?><?><?><?><?>
       <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?><?>


       --pem-path=""  <?><?><?><?> <?><?><?><?> <?><?> <?><?><?><?> <?><?>
       <?><?><?><?> RSA <?><?> <?><?><?><?> PEM <?><?><?><?> <?><?>
       <?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?><?><?><?>


       --reproducible[=false]   <?><?><?><?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?> <?><?> <?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?> <?><?><?><?>


       --rocm[=false]      <?><?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?><?> Rocm <?><?><?><?><?><?> <?><?>
       <?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?> post <?> test


       -s, --sandbox[=false]    <?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?><?> sandbox (<?><?><?><?><?><?> <?><?><?><?><?><?><?><?><?>
       chroot)


       --section=[all]     <?><?><?><?> <?><?><?><?><?> <?><?><?>(<?><?><?>)
       <?><?><?><?><?><?><?><?> <?><?> deffile (<?><?><?><?> setup, post,
       files, environment, test, labels, none)


       -u, --update[=false]     <?><?><?><?><?> <?><?><?><?><?> <?><?>
       <?><?><?> <?><?><?><?><?><?><?> <?><?><?><?><?> (<?><?><?><?><?><?>
       <?><?><?><?><?><?> <?><?><?><?><?> <?><?><?><?><?><?>)


       --userns[=false]    <?><?><?><?> <?><?><?><?> <?><?><?><?><?><?><?>
       <?><?> setuid <?><?><?> <?><?> <?><?><?><?> <?><?> <?><?><?><?><?>
       <?><?><?><?>


       --warn-unused-build-args[=false]   <?><?><?><?><?> <?><?><?><?><?>
       <?><?> <?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?> <?><?><?><?><?>
       <?><?><?> <?><?><?><?><?> <?><?><?><?>
       <?><?><?><?><?><?><?><?><?><?><?> <?><?><?><?>


       --writable-tmpfs[=false]      <?><?> <?><?><?> <?><?><?> %test<?>
       <?><?><?><?><?><?><?><?><?><?> <?><?> <?><?> <?><?><?><?>
       <?><?><?><?><?><?><?>-<?><?><?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?> <?><?><?><?><?><?><?><?> <?><?>
       <?><?><?><?><?> <?><?><?><?> <?><?><?><?><?><?> (<?><?><?><?> <?><?>
       <?><?><?><?><?><?><?><?> <?><?> overlay)



<?><?><?><?> (EXAMPLE)


         DEF FILE BASE OS:

             Library:
                 Bootstrap: library
                 From: debian:9

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

             Singularity Hub:
                 Bootstrap: shub
                 From: singularityhub/centos

             YUM/RHEL:
                 Bootstrap: yum
                 OSVersion: 7
                 MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/x86_64
                 Include: yum

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

             openSUSE:
                 Bootstrap: zypper
                 MirrorURL: http://download.opensuse.org/distribution/openSUSE-stable/repo/oss
                 Include: zypper

             Debian/Ubuntu:
                 Bootstrap: debootstrap
                 OSVersion: trusty
                 MirrorURL: http://us.archive.ubuntu.com/ubuntu

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

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

         DEFFILE SECTIONS:

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

             %pre
                 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."

             %setup
                 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."

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

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

             %environment
                 LUKE=goodguy
                 VADER=badguy
                 HAN=someguy
                 export HAN VADER LUKE

             %test
                 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

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

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

             %labels
                 HELLO MOTO
                 KEY VALUE

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

         COMMANDS:

             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



<?><?><?><?><?><?> <?><?><?><?><?><?> (SEE ALSO)
       apptainer(1)



<?><?><?><?><?><?><?> (HISTORY)
       30-Jul-2026 <?><?><?><?><?> <?><?><?><?><?><?> <?><?><?><?> spf13/cobra

Auto generated by spf13/cobra      Jul 2026                       apptainer(1)