apptainer-build

Build a container from a definition file

$ apptainer build [path/to/image.sif] [path/to/definition.def]

$ apptainer build [path/to/image.sif] docker://[image]:[tag]

$ apptainer build [path/to/image.sif] library://[user/collection/container]:[tag]

$ apptainer build [[-s|--sandbox]] [path/to/directory] docker://[image]:[tag]

$ apptainer build --disable-cache [path/to/image.sif] docker://[image]:[tag]

$ apptainer build [[-F|--force]] [path/to/image.sif] [path/to/definition.def]

$ apptainer build [[-f|--fakeroot]] [path/to/image.sif] [path/to/definition.def]

$ apptainer build [[-h|--help]]

apptainer build [options...] output_image source

-c, --config FILE
    config file to use ($APPTAINER_CONFIG_FILE)

--cleanenv
    start with clean environment

--debug
    print verbose output

-d, --derive
    use writable overlayfs image

--docker-login
    login to docker before build

--dry-run
    dry run bootstrap scriptlets

--fakeroot[=mode]
    fake root privileges for unprivileged user

-f, --force
    truncate image if exists

--keep-dir
    keep extraction directory (for debugging)

--library LIBRARY_URL
    library to pull image from

--metadata-proxy PROXY
    the metadata proxy to use

-n, --no-cleanup
    don't cleanup on failure

--no-home
    do not mount users home directory

--no-https
    do not verify https certificates

--no-priv
    don't use privileged syscalls

-N, --nv
    install the NVIDIA Container Toolkit libraries

--overlay SIZE:[OPTS]
    overlay directory or image

--pwd DIR
    set working directory to DIR

-q, --quiet
    suppress all output

--read-only
    make all mounts read only

--remote REMOTE_BUILDER
    perform a remote build on given endpoint

-s, --sandbox
    create a sandbox directory (not image)

--section SECTION
    run only a specific section of the specfile

-u, --update
    only update the image metadata

--writable
    make image writable (EPHEMERAL or PERSISTENT)

--writable-tmpfs
    mount a tmpfs as /tmp

-H, --home DIR:[DIR]
    set home directory to DIR

-o, --option KEY=VAL
    set an option key=val

-h, --help
    show this help message

-u, --unsquash
    convert squashfs to extfs

The apptainer build command creates Apptainer (formerly Singularity) container images from various sources like definition files, URIs (docker://, shub://, library://, etc.), or existing images. It supports local builds by processing definition file stages such as %setup, %post, %environment, %labels, %runscript, %test, and %startscript, installing software, configuring environments, and bundling into secure SIF format or sandbox directories.

Key features include remote builds via configured endpoints (--remote), sandbox mode for development (--sandbox), writable overlays (--derive or --writable), fakeroot for unprivileged users (--fakeroot), and hardware support like NVIDIA (--nv). Builds can update existing images (--update), force overwrites (--force), or run specific sections (--section). Extraction happens to a temporary directory, with cleanup unless disabled.

Ideal for HPC, it ensures portability, immutability, and reproducibility. Requires root or fakeroot for privileged operations; unprivileged builds limited to user namespaces.

Requires root or fakeroot for privileged builds; remote builds need 'apptainer remote add/list'; large images need ample disk space; unprivileged mode limits some features like bind mounts.

sources include: definition files (.def), docker://image:tag, shub://user/repo:tag, library://user/repo:tag, oras://registry/image:tag, http(s)://path/to/image.sif, local files/directories.

Bootstrap (Docker, Debootstrap, etc.), %pre, %setup, %post, %environment, %labels, %help, %runscript, %test, %startscript. Executed sequentially during build.

Originated as singularity build in Singularity 2.x (2015), evolved through Sylabs Singularity 3.x; forked as Apptainer 1.0 in Aug 2022 from Singularity 3.8.5 for community governance, focusing on HPC compatibility without commercial dependencies.

apptainer(1), singularity-build(1), podman-build(1), docker-build(1)