crane-rebase

Rebase image

$ crane rebase

$ crane rebase --new_base [image_name]

$ crane rebase --old_base [image_name]

$ crane rebase [[-t|--tag]] [tag_name]

$ crane rebase [[-h|--help]]

crane rebase [OPTIONS] BASE IMAGE

-main-name string
    Name of the main layer in multi-platform images (default: main)

-platform string
    Target platform for the base image, e.g. linux/amd64 (default: linux/amd64)

--insecure
    Allow insecure HTTP registries

--source-cert string
    Client cert for source image authentication

--source-key string
    Client key for source image authentication

--registry-mirror-urls strings
    List of registry mirror URLs

The crane rebase command is part of the crane CLI tool, designed for efficient manipulation of OCI container images without full downloads. It rebases a source image onto a new base image by copying the non-empty layers from the source on top of the base, while preserving the original image's configuration and metadata. This is useful for updating base images in multi-stage builds, switching architectures, or minimizing image size by using a slimmer base.

It supports remote registries, local tarballs, and authenticated pulls/pushes. Crane handles platform-specific rebasing, multi-platform manifests, and attestation layers. Ideal for CI/CD pipelines where you need to update vulnerable bases without rebuilding entire images. Performance is optimized with parallel layer fetching and delta uploads.

Requires compatible layer formats between base and source; may fail on mismatched OS/arch. Does not handle layer compression differences automatically. Large images can consume significant bandwidth/memory.

crane rebase alpine:latest myimage:latest newimage:latest
Rebases myimage onto alpine base, tags as newimage.

Use -platform linux/arm64 for cross-architecture rebasing; crane resolves manifests automatically.

Developed by Google Container Tools as part of the crane project (github.com/google/go-containerregistry/crane). First released around 2020, gained popularity with Sigstore/cosign integration for signed images. Actively maintained for OCI 1.0 compliance.

crane(1), skopeo(1), docker(1), img(1)