Library API Registries
Apptainer enables users to use Library API Container Registries to push containers to a registry that was designed specifically for SIF images and pull SIF images created by others.
Many Library API registries will require authentication to perform operations
like pushing container images or pulling potentially private container images.
remote command group governs the authentication for Library API
registries. Check out the instructions for how to add and login with a
Once you have authenticated, you are ready to push your container!
Pushing a Container
apptainer push command will push a container to the container
library with the given URL. Here’s an example of a typical push command:
$ apptainer push my-container.sif library://your-name/project-dir/my-container:latest
:latest is the container tag. Tags are used to have different
version of the same container.
When pushing your container, there’s no need to add a
(Singularity Image Format) to the end of the container name, (like on
your local machine), because all containers on the library are SIF
Let’s assume you have your container (v1.0.1), and you want to push that
container without deleting your
:latest container, then you can add
a version tag to that container, like so:
$ apptainer push my-container.sif library://your-name/project-dir/my-container:1.0.1
You can download the container with that tag by replacing the
:latest, with the tagged container you want to download.
To set a description against the container image as you push it, use the -D flag introduced in Apptainer 3.7. This provides an alternative to setting the description via the web interface:
$ apptainer push -D "My alpine 3.11 container" alpine_3.11.sif library://myuser/examples/alpine:3.11 2.7MiB / 2.7MiB [=========================================================================] 100 % 1.1 MiB/s 0s Library storage: using 13.24 MiB out of 11.00 GiB quota (0.1% used) Container URL: https://cloud.example.com/library/myuser/examples/alpine
Note that when you push to a library that supports it, Apptainer will report your quota usage and the direct URL to view the container in your web browser.
Pulling a container
apptainer pull command will download a container from an
OCI Registry (
Library API Registry
library://), and also Shub (
When pulling from Docker, the container will automatically be converted to a SIF (Singularity Image Format) container.
Here’s a typical pull command:
$ apptainer pull file-out.sif library://alpine:latest # or pull from docker: $ apptainer pull file-out.sif docker://alpine:latest
If there’s no tag after the container name, Apptainer
automatically will pull the container with the
To pull a container with a specific tag, just add the tag to the library URL:
$ apptainer pull file-out.sif library://alpine:3.8
Of course, you can pull your own containers. Here’s what that will look like:
Pulling your own container
Pulling your own container is just like pulling from Github, Docker, etc…
$ apptainer pull out-file.sif library://your-name/project-dir/my-container:latest # or use a different tag: $ apptainer pull out-file.sif library://your-name/project-dir/my-container:1.0.1
You don’t have to specify a output file, one will be created automatically, but it’s good practice to always specify your output file.
Verify/Sign your Container
Verify containers that you pull from the library, ensuring they are bit-for-bit reproductions of the original image.
Check out this page on how to: verify a container, making PGP key, and sign your own containers.
Searching the Library for Containers
To find interesting or useful containers in a library, you can open that library in your browser if that project supports a web GUI.
Alternatively, from the CLI you can use
apptainer search <query>.
This will search a library for container images matching
Using the CLI Search
Here is an example of searching a library for
apptainer search centos Found 72 container images for amd64 matching "centos": library://dcsouthwick/iotools/centos7:latest library://dcsouthwick/iotools/centos7:sha256.48e81523aaad3d74e7af8b154ac5e75f2726cc6cab37f718237d8f89d905ff89 Minimal centos7 image from yum bootstrap library://dtrudg/linux/centos:7,centos7,latest library://dtrudg/linux/centos:centos6,6 library://emmeff/centos/centos:8 library://essen1999/default/centos-tree:latest library://gallig/default/centos_benchmark-signed:7.7.1908 Signed by: 6B44B0BC9CD273CC6A71DA8CED6FA43EF8771A02 library://gmk/default/centos7-devel:latest Signed by: 7853F08767A4596B3C1AD95E48E1080AB16ED1BC
Containers can have multiple tags, and these are shown separated by
commas after the
: in the URL. E.g.
library://dtrudg/linux/centos:7,centos7,latest is a single container
image with 3 tags,
latest. You can
apptainer pull the container image using any one of these tags.
Note that the results show
amd64 containers only. By default
search returns only containers with an architecture matching your
current system. To e.g. search for
arm64 containers from an
amd64 machine you can use the
apptainer search --arch arm64 alpine Found 5 container images for arm64 matching "alpine": library://dtrudg-sylabs-2/multiarch/alpine:latest library://geoffroy.vallee/alpine/alpine:latest Signed by: 9D56FA7CAFB4A37729751B8A21749D0D6447B268 library://library/default/alpine:3.11.5,latest,3,3.11 library://library/default/alpine:3.9,3.9.2 library://sylabs/tests/passphrase_encrypted_alpine:3.11.5
You can also limit results to only signed containers with the
apptainer search --signed alpine Found 45 container images for amd64 matching "alpine": library://deep/default/alpine:latest,1.0.1 Signed by: 8883491F4268F173C6E5DC49EDECE4F3F38D871E library://godloved/secure/alpine:20200514.0.0 Signed base image built directly from mirrors suitable for secure building. Make sure to check that the fingerprint is B7761495F83E6BF7686CA5F0C1A7D02200787921 Signed by: B7761495F83E6BF7686CA5F0C1A7D02200787921 library://godlovedc/blah/alpine:sha256.63259fd0a2acb88bb652702c08c1460b071df51149ff85dc88db5034532a14a0 Signed by: 8883491F4268F173C6E5DC49EDECE4F3F38D871E library://heffaywrit/base/alpine:latest Signed by: D4038BDDE21017435DFE5ADA9F2D10A25D64C1EF library://hellseva/class/alpine:latest Signed by: 6D60F95E86A593603897164F8E09E44D12A7111C library://hpc110/default/alpine-miniconda:cupy Signed by: 9FF48D6202271D3C842C53BD0D237BE8BB5B5C76 ...
Building from a definition file:
This is our definition file. Let’s call it
bootstrap: library from: ubuntu:18.04 %runscript echo "hello world from ubuntu container!"
Now, to build the container, use the
--remote flag, and without
$ apptainer build --remote ubuntu.sif ubuntu.def
After building, you can test your container like so:
$ ./ubuntu.sif hello world from ubuntu container!