singularity-build - Man Page

Build a Singularity image


singularity build [local options...]  



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

  default:    The compressed Singularity 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 Singularity 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 a Singularity 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 (default
  docker://   a Docker/OCI registry (default Docker Hub)
  shub://     a Singularity registry (default Singularity Hub)
  oras://     an OCI registry that holds SIF files using ORAS


--arch="amd64" architecture for remote build

-B, --bind=[] 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. (not supported with remote build)

--builder="" remote Build Service URL, setting this implies --remote

-d, --detached[=false] submit build job and print build ID (no real-time logs and requires --remote)

--disable-cache[=false] do not use cache or create cache

--docker-login[=false] login to a Docker Repository interactively

-e, --encrypt[=false] build an image with an encrypted file system

-f, --fakeroot[=false] build using user namespace to fake root user (requires a privileged installation)

--fix-perms[=false] ensure owner has rwX permissions on all container content for oci/docker sources

-F, --force[=false] overwrite an image file if it exists

-h, --help[=false] help for build

--json[=false] interpret build definition as JSON

--library="" container Library URL

--no-cleanup[=false] do NOT clean up bundle after failed build, can be helpful for debugging

--nohttps[=false] do NOT use HTTPS with the docker:// transport (useful for local docker registries without a certificate)

-T, --notest[=false] build without running tests in %test section

--nv[=false] inject host Nvidia libraries during build for post and test sections (not supported with remote build)

--passphrase[=false] prompt for an encryption passphrase

--pem-path="" enter an path to a PEM formated RSA key for an encrypted container

-r, --remote[=false] build image remotely (does not require root)

--rocm[=false] inject host Rocm libraries during build for post and test sections (not supported with remote build)

-s, --sandbox[=false] build image as sandbox format (chroot directory structure)

--section=[all] only run specific section(s) of deffile (setup, post, files, environment, test, labels, none)

-u, --update[=false] run definition over existing container (skips header)



          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: debootstrap
          OSVersion: trusty

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

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


          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 $SINGULARITY_ROOTFS."

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

          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

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

          export HAN VADER LUKE

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


      Build a sif file from a Singularity recipe file:
          $ singularity build /tmp/debian0.sif /path/to/debian.def

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

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

See Also



15-Jun-2021 Auto generated by spf13/cobra

Referenced By


Jun 2021 Auto generated by spf13/cobra