Skip to content

push

Export a local Docker image and upload it to S3.

s3lo push <local-image> <s3-ref> [flags]

Arguments

Argument Description
<local-image> Image name and tag as shown in docker images, e.g. myapp:v1.0
<s3-ref> Destination in s3://bucket/image:tag or local://path/image:tag format. Tag is required.

Flags

Flag Description
--force Overwrite an existing tag even if immutability is enabled
--platform Which platform to push when the local image holds several (e.g. linux/arm64)

What it does

  1. Exports the image from the local Docker daemon as a tar archive.
  2. Parses the OCI Image Layout from the archive.
  3. Checks which blobs already exist in blobs/sha256/ on S3.
  4. Uploads missing blobs to blobs/sha256/<digest> using S3 Intelligent-Tiering.
  5. Uploads manifest files to manifests/<image>/<tag>/.

Only missing blobs are uploaded — blobs shared with other images in the bucket are skipped automatically.

Examples

# Push a tagged image
s3lo push myapp:v1.0 s3://my-bucket/myapp:v1.0

# Push with a git commit SHA
s3lo push myapp:$(git rev-parse --short HEAD) s3://my-bucket/myapp:$(git rev-parse --short HEAD)

# Push to a nested image name
s3lo push backend:latest s3://my-bucket/org/backend:latest

# Force-overwrite an immutable tag
s3lo push myapp:v1.0 s3://my-bucket/myapp:v1.0 --force

# Push to local storage
s3lo push myapp:v1.0 local://./local-s3/myapp:v1.0

Output

Pushing myapp:v1.0 to s3://my-bucket/myapp:v1.0
  uploading ⠸ 58.7 MB [45s]
Done.

The progress bar shows bytes uploaded and elapsed time. It's hidden automatically in non-TTY environments (CI).

Notes

Image must exist locally

The image must be available in your local Docker daemon (docker images). If not, run docker pull myapp:v1.0 first.

Apple Silicon and EKS

On Apple Silicon Macs, Docker images are linux/arm64 by default. For EKS nodes running linux/amd64, build or pull the correct platform explicitly: 

docker build --platform linux/amd64 -t myapp:v1.0 .
# or
docker pull --platform linux/amd64 myapp:v1.0
Use s3lo copy to mirror multi-arch images directly to S3 without this concern.

One platform per push

push publishes a single platform. On the classic Docker image store that is all a tag can hold, so there is nothing to choose. On the containerd image store a tag can hold several, and then push publishes the host platform and names the ones it is leaving behind:

Note: this image holds linux/amd64, linux/arm64 locally. Pushing linux/arm64 only.
      Push another with --platform, or use s3lo copy to publish every platform as an index.

Use --platform linux/amd64 to pick a different one, or s3lo copy to publish all of them as an image index. Asking for a platform the image does not hold is an error rather than a quiet fallback.

Idempotent

Pushing the same image twice is safe and fast. The second push skips all blobs and only re-uploads the manifest (a few bytes).

Explicit tag required

The destination tag must be specified explicitly — s3lo push myapp:v1.0 s3://my-bucket/myapp (without :tag) is an error.