Skip to main content

Push large images

Reviewed on · View on GitHub

Keep layer sizes small to stay well within the service limits (see Container Registry limits).

Best practices​

  • Use standard clients — Docker, Podman, Buildah, BuildKit, and skopeo stream or chunk blob uploads. Avoid raw single-PUT uploads of entire blobs.
  • Split layers — use multi-stage builds and BuildKit so each layer stays small.
  • Exclude build artifacts — add a .dockerignore to avoid copying caches and temporary files into layers.
  • Keep default compression — gzip layer compression reduces transfer size.

Example​

echo "$REGISTRY_PASSWORD" | docker login <registry-host> -u <user> --password-stdin
docker build --builder <buildkit-builder> -t <registry-host>/<project>/<image>:<tag> .
docker push <registry-host>/<project>/<image>:<tag>

If a push fails with unexpected EOF, see the Known issues section.

Was this page helpful?