apptainer-pull

Pull a container from Docker Hub

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

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

$ apptainer pull [path/to/image.sif] oras://[registry/namespace/image]:[tag]

$ apptainer pull --arch [amd64|arm64|ppc64le] [path/to/image.sif] library://[image]:[tag]

$ apptainer pull [[-F|--force]] [path/to/image.sif] docker://[image]:[tag]

$ apptainer pull --sandbox [path/to/directory] docker://[image]:[tag]

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

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

apptainer pull [options] <imageRef>

--arch ARCH
    Pull specific architecture (e.g., amd64, arm64)

--dir DIRECTORY
    Store pulled image(s) in custom directory

--disable-cache
    Disable image layers cache

--force, -F
    Overwrite existing image

--library URL
    Use alternate library endpoint

--name NAME
    Set filename for pulled image

--nv
    Pull with NVIDIA runtime support

--sandbox
    Pull as writable sandbox directory

--update
    Update existing image to latest digest

--no-cleanup
    Do not clean up after failed pull

--password-stdin
    Read password from stdin for auth

--platform PLATFORM
    Pull specific os/arch/platform

The apptainer pull command fetches container images from supported registries and stores them locally as SIF files, sandboxes, or directories. It handles URIs like docker://ubuntu:22.04, library://ubuntu, oras://localhost:5000/ubuntu, shub://vsoch/hello-world, and local paths (file:// or ./image.sif).

Apptainer resolves the reference, performs authentication if needed (via apptainer remote login), downloads layers or the full image, and converts to native SIF format for optimal performance on HPC systems. Options enable architecture-specific pulls, NVIDIA CUDA support, sandbox extraction for modification, or updates to existing images.

Pulled images land in $HOME/.apptainer/cache by default or a custom directory, ready for apptainer run, exec, or shell. It's designed for reproducible environments, avoiding root privileges unlike Docker, making it ideal for shared clusters. Caching optimizes repeated pulls, but --disable-cache forces fresh downloads.

Use cases include bootstrapping workflows, testing containers offline after pull, and building custom images atop pulled bases.

Requires internet for remote pulls; authentication needed for private repos. Sandbox pulls need writable dir. Fails on unsupported URIs or OCI non-compliance. Global options like --debug/--quiet apply.

docker://[registry/]image:tag, library://collection/image:tag, oras://host/image:tag, shub://user/image:tag, http(s)://path/to/image.sif, file://local/path

Login with apptainer remote login --name <remote> for Docker/Oras. Tokens for private repos; --password-stdin for scripts.

$APPTAINER_CACHEDIR or $HOME/.apptainer/cache; clear with apptainer cache clean.

Developed in Singularity 2.4+ (2016) for HPC containers. Evolved in Singularity 3.x with OCI/Docker support. Rebranded apptainer pull in 2022 as open-source fork after Sylabs commercialization, maintaining backward compatibility.

apptainer(1), apptainer-build(1), apptainer-run(1), apptainer-inspect(1), singularity-pull(1)