crane-flatten

Flatten an image

$ crane flatten

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

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

crane flatten [--from <index>] [--platform <platform>] <SOURCE> <TARGET>

--from <int>
    Layer index to flatten from (0-based, default -1 for last layer)

--platform <string>
    Target platform as os[/arch[/variant]] (default linux/amd64)

The crane flatten command, part of the crane CLI tool from Google's go-containerregistry project, converts multi-layered container images into a single-layer image. This process combines all filesystem layers from the source image into one atomic layer while preserving the image configuration, labels, and annotations.

It is particularly useful for optimizing images for distribution, reducing the number of layers for faster pulls in environments with layer caching issues, or creating minimal images for embedded systems. By default, it starts flattening from the last layer (--from -1), but users can specify an index to flatten from a specific point, excluding upper layers.

The tool fetches the source image from a registry (or local tarball/OCI directory), performs the flattening operation in memory or tmpfs, and pushes the result to the target destination. Platforms can be overridden with --platform to handle multi-arch images. Note that history metadata from individual layers is lost, but the final image remains fully functional and OCI-compliant.

Crane ensures atomicity and supports digest references for reproducibility.

Discards layer-by-layer history and metadata; may increase layer size if source has uncompressed small layers; requires sufficient memory for large images; source must be accessible registry, OCI layout, or tar.

crane flatten alpine:latest myregistry.com/alpine:flat
crane flatten --platform=linux/arm64 --from 2 ubuntu:22.04 ubuntu-flat:arm64

Developed as part of Google's go-containerregistry library; crane flatten added in v0.5.0 (2021), enhanced for multi-platform in later releases; widely used in CI/CD for image optimization.

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