apptainer-push

Push a container to the Container Library

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

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

$ apptainer push [[-U|--allow-unsigned]] [path/to/image.sif] library://[user/collection/container]:[tag]

$ apptainer push [[-D|--description]] "[description]" [path/to/image.sif] library://[user/collection/container]:[tag]

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

apptainer push [options] <source> <destination>

-c, --checkpoint PREFIX
    Create checkpoint files in PREFIX directory (default "push-checkpoint.d"), enables resumable pushes

--debug
    Print debugging information during push

--derivable
    Make pushed image writable and importable for modifications

--encrypt[=algo]
    Encrypt image before pushing (default algo: aes-256-cbc), prompts for passphrase

-f, --force
    Truncate and overwrite destination instead of injecting/appending

-h, --help
    Show this help message

-s, --samehash
    Compare hashes first; push only if source differs from destination

The apptainer push command exports and uploads Apptainer/Singularity Image Format (SIF) files, directories, or sandboxes to remote destinations like libraries, Docker/OCI registries, or local paths. Essential for sharing containers in HPC clusters, it supports resumable uploads via checkpointing, encryption for security, and hash-based checks to skip unchanged images.

Specify source as a local image file (e.g., foo.sif) and destination as a URI: library://namespace/image:tag for Apptainer libraries, docker://registry/repo:tag for Docker Hub, or oras:// for OCI artifacts. Configure remotes first with apptainer remote add and login if private.

Features like --encrypt use AES-256-CBC by default (prompts for passphrase), --derivable enables downstream modifications, and -f overwrites destinations. Debug with --debug. Ideal for reproducible workflows, but requires network access and sufficient quota on targets.

Requires configured apptainer remote for library:// URIs; authentication needed for private repos. Large images may need checkpointing and stable connections. Encryption passphrases not stored securely.

library://user/image:tag, docker://registry/image:tag, oras://host/repo:tag, podman://, shub://, local paths (.sif, .sqsh).

apptainer push foo.sif library://myorg/foo:latest
apptainer push --encrypt bar.sif docker://ghcr.io/user/bar:v1
apptainer push -s -c /tmp/cp baz.sif oras://oras.io/app:0.1

Originated in Singularity 3.0 (2019) for Sylabs Library integration; enhanced in Apptainer 1.0+ (2022 fork) with OCI/Docker/encryption support for broader registry compatibility.

apptainer-pull(1), apptainer-remote(1), apptainer-key(1)