crane — Fast Container Image Tool for OCI Registries

Introduction

crane is a command-line tool for interacting with container images and OCI registries without requiring Docker. Part of Google's go-containerregistry library, it provides fast, scriptable operations for copying, inspecting, and mutating images directly at the registry level.

What crane Does

• Lists tags, manifests, and digests for images in any OCI-compliant registry
• Copies images between registries without pulling layers to disk, operating entirely at the registry API level
• Inspects image configurations, layers, and manifests as JSON for analysis and debugging
• Mutates image metadata (labels, entrypoint, environment variables) without rebuilding
• Pushes tarballs and OCI layout directories directly to registries

Architecture Overview

crane is built on top of the go-containerregistry Go library, which provides typed abstractions for OCI image manifests, indices, layers, and registry interactions. All operations use the OCI Distribution Spec HTTP API, so crane communicates directly with registries without needing a local container runtime. Image copies are streamed registry-to-registry when both endpoints support it, avoiding unnecessary local storage.

Self-Hosting & Configuration

• Install via go install, download a prebuilt binary from GitHub releases, or use the gcr.io/go-containerregistry/crane image
• Authenticate to registries using crane auth login or by placing credentials in ~/.docker/config.json
• Set DOCKER_CONFIG to point at custom credential files for CI/CD environments
• Use --platform to target specific architectures when working with multi-arch images
• Integrate the go-containerregistry Go library directly into custom tooling for programmatic image manipulation

Key Features

• Registry-to-registry copy avoids pulling and pushing layers through the local machine
• Works without Docker or any container runtime installed
• Scriptable JSON output for manifests and configs integrates cleanly into CI/CD pipelines
• Supports OCI image indices for multi-architecture image management
• Lightweight single binary with no dependencies

Comparison with Similar Tools

• Skopeo — Red Hat's container image tool with broader transport support (docker-archive, oci-archive); crane focuses on registry operations with a simpler API
• docker CLI — requires a running Docker daemon; crane operates directly against registry APIs
• regctl / regclient — similar registry-focused tooling; crane is backed by Google's widely-used Go library
• ORAS — focuses on OCI artifact management beyond container images; crane is specifically designed for container image workflows

FAQ

Q: Do I need Docker installed to use crane? A: No. crane communicates directly with OCI registries over HTTP and does not require any container runtime.

Q: Can crane copy images across different cloud registries? A: Yes. crane can copy images between any OCI-compliant registries, including Docker Hub, GCR, ECR, ACR, and Harbor.

Q: How does crane handle authentication? A: crane reads credentials from the standard Docker config file (~/.docker/config.json) or accepts credentials via crane auth login.

Q: Is the go-containerregistry library usable independently? A: Yes. The Go library is designed for embedding in other tools and is used internally by ko, kaniko, and other container ecosystem projects.

Sources

• https://github.com/google/go-containerregistry
• https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md