crane-cp

View documentation for the original command

$ tldr crane copy

crane cp source_image_reference destination_image_reference [flags]

Examples:
crane cp ubuntu:latest myregistry.com/myorg/ubuntu:latest
crane cp myregistry.com/myrepo newregistry.com/newrepo --recursive
crane cp registry.example.com/app:v1 registry.example.com/app:backup --username myuser --password mypass

--allow-nondistributable-blobs
    Permits the copying of image blobs (e.g., Windows layers) that are flagged as non-distributable by the registry.

--allow-referrers
    Copies any associated referrers, such as Software Bill of Materials (SBOMs) or attestations, along with the main image.

--platform string
    Specifies a target platform (e.g., linux/amd64) for the copied image, useful when working with multi-platform image manifests.

--recursive
    Copies all tags and digests found within the source repository to the destination, not just the explicitly specified image reference.

--tags
    Copies all tags associated with the source repository to the destination. Similar to --recursive but specifically for tags.

--insecure
    Allows communication with registries over HTTP or bypasses TLS certificate verification for HTTPS connections. Can be specified for source (--src-insecure) or destination (--dst-insecure) separately.

--username string, --password string
    Specifies the username and password for authentication with both source and destination private registries. Separate flags like --src-username/--src-password and --dst-username/--dst-password are also available for distinct credentials.

crane-cp is a powerful subcommand of the crane tool, developed as part of the go-containerregistry project. It facilitates the direct and efficient copying of container images, including all their layers, configurations, and manifests, between different container registries or within the same registry. Unlike traditional methods requiring a local Docker daemon or pulling images locally, crane-cp operates directly against registry APIs. This makes it an ideal tool for cloud-native workflows, image migration, replication, or distribution across various environments without intermediate local storage. It supports copying by digest, tag, or recursively for entire repositories, and offers advanced options for platform-specific copying, handling insecure registries, and managing authentication.

crane-cp operates directly against container registries, requiring network access to both the source and destination endpoints. Proper authentication (e.g., via ~/.docker/config.json, environment variables, or explicit --username/--password flags) is crucial for private registries. It bypasses local Docker daemons, meaning it doesn't interact with locally cached images. Users should be mindful of potential registry rate limits or storage costs, especially during large-scale image copy operations. Compatibility issues can arise if registries have different support for image manifest lists or OCI vs. Docker image formats.

The crane tool, including its cp subcommand, originated from Google's go-containerregistry project. This initiative was launched to provide robust, programmatic, and efficient ways to interact with OCI (Open Container Initiative) registries, addressing limitations of client-side tools for registry-specific operations. crane-cp was a foundational feature, designed from the outset to fulfill the critical need for reliable and performant image migration and replication in cloud-native and CI/CD environments, evolving in parallel with OCI specifications and growing industry demands for direct registry manipulation.

crane(1), skopeo(1), docker-pull(1), docker-push(1), oras(1)