regctl image copy: Copy Images Between Registries
regctl image copy transfers an image from one registry reference to another over the registry API, keeping all architectures by default.
regctl (from regclient) is a daemonless registry client. image copy mirrors images the way skopeo copy and crane copy do, with fine control over referrers and digest tags.
What it does
regctl image copy reads the source manifest and blobs and writes them to the destination reference. It copies the full manifest list by default and can also carry along digest-tagged referrers (signatures, SBOMs) with --digest-tags.
Common usage
# copy an image between registries
regctl image copy docker.io/library/nginx:1.25 ghcr.io/acme/nginx:1.25
# carry signatures/SBOM digest tags along
regctl image copy --digest-tags \
ghcr.io/acme/app:1.4.0 registry.example.com/app:1.4.0
# log in first
regctl registry login ghcr.io -u "$GH_USER" -p "$GH_TOKEN"Options
| Flag | What it does |
|---|---|
| SRC DST | Source and destination references (positional) |
| --digest-tags | Also copy the sha256-... digest tags (signatures, SBOMs) |
| --referrers | Copy OCI referrers (attestations) attached to the image |
| --platform os/arch | Copy only one platform from an index |
| --force-recursive | Recopy all blobs even if the destination has them |
In CI
regctl runs as a static binary or small container, so it mirrors images in restricted runners with no daemon. Use --digest-tags (or --referrers) when the source image has cosign signatures or SBOMs you need to move together with the image.
Common errors in CI
"failed to ... 401 Unauthorized" means run regctl registry login. "manifest not found" means the source reference is wrong. "http: server gave HTTP response to HTTPS client" against a plain-HTTP registry needs regctl registry set --tls disabled <host>. If signatures do not appear on the destination, add --digest-tags or --referrers.