crane-copy

Copy an image from source to target

$ crane copy [source] [target]

$ crane copy [source] [target] [[-a|--all-tags]]

$ crane copy [source] [target] [[-j|--jobs]] [int]

$ crane copy [source] [target] [[-n|--no-clobber]]

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

crane copy <SOURCE> <DESTINATION> [options]

<SOURCE>
    The reference to the source image (e.g., registry.com/repo/image:tag or digest).

<DESTINATION>
    The reference to the destination image.

--allow-nondistributable-blobs
    Allow copying blobs that are marked as non-distributable.

--allow-missing-blobs
    Allow copying manifests that reference missing blobs.

--insecure
    Allow communication with registries over HTTP or insecure HTTPS.

--platform <platform>
    Specify platform(s) (e.g., 'linux/amd64') to copy from a multi-arch manifest. Can be specified multiple times.

--preserve-digests
    Preserve digest references during the copy operation.

--preserve-tags
    Preserve all tags from the source when copying a manifest list.

--strict
    Enforce strict OCI validation when pushing.

--tag <tag>
    Add an additional tag to the destination image. Can be specified multiple times.

--user-agent <string>
    Override the default User-Agent string sent to registries.

crane copy is a powerful subcommand of the crane utility, designed for efficiently copying OCI (Open Container Initiative) images or manifest lists directly between two container registries.

Unlike traditional methods that might require pulling an image to a local machine and then pushing it to a new destination, crane copy performs the operation server-side, minimizing local disk usage and network bandwidth. It handles authentication with various registries and supports copying specific platforms from a multi-architecture image. This command is invaluable for image migration, creating backups, distributing images across different regions or accounts, and automating CI/CD workflows where direct registry-to-registry transfers are beneficial.

Using crane copy requires appropriate network connectivity to both the source and destination registries. Proper authentication (e.g., via docker login or crane auth login) is essential, and the user's credentials must have read access to the source and write access to the destination. Copying very large images can still be time-consuming, depending on network speeds and registry performance. Not all registries may fully support advanced OCI features, potentially leading to compatibility issues.

crane copy leverages standard Docker credential helpers and the `~/.docker/config.json` file for authenticating with container registries, making it compatible with most existing setups.

Beyond simple image migration, crane copy is ideal for creating registry mirrors, enabling multi-region deployments, automating image distribution in CI/CD pipelines, and creating backups of critical images across different registry providers.

The --platform flag is particularly useful for selectively copying specific architectures (e.g., `linux/arm64`) from a multi-architecture image manifest without copying the entire manifest list, which helps in optimizing storage and transfer needs for specific environments.

The crane utility, including its copy subcommand, was developed by GoogleContainerTools. It emerged as a lightweight, single-binary tool written in Go, specifically designed to simplify and streamline common container registry operations without the need for a full Docker daemon. Its development aimed to provide a more efficient solution for CI/CD pipelines and automated environments, where direct registry-to-registry transfers offer significant advantages in speed and resource consumption over traditional pull-then-push workflows.

skopeo(1): A similar command-line tool for image management, often used for copying images between registries., docker(1): The main Docker CLI, which includes `docker push` for uploading local images to a registry., crane: The parent utility providing other subcommands for interacting with container registries (e.g., `crane pull`, `crane push`, `crane manifest`).