Skopeo — Registry-Agnostic Container Image Toolkit

Introduction

Skopeo is a command-line tool for performing various operations on container images and registries without requiring a Docker daemon. It speaks OCI and Docker registry APIs directly, making it ideal for CI, air-gapped mirroring, and scripting. It's a Red Hat / containers org project (paired with Podman, Buildah, and CRI-O) with over 10,000 GitHub stars.

What Skopeo Does

• inspect any image, any registry, returning a full JSON manifest and config.
• copy images between registries (and OCI layouts, OCI archives, tar, dir transports) with no daemon.
• list-tags enumerates tags on a repo using the registry v2 API.
• sync mirrors entire repositories or whole registries, great for air-gapped mirrors.
• delete removes an image by digest or tag, when your registry allows it.

Architecture Overview

Skopeo is a Go binary built on the containers/image library — the same library backing Podman, Buildah, and CRI-O. It supports a pluggable transport system: docker://, oci://, oci-archive://, docker-archive://, containers-storage://, dir://. This lets it convert between them in-place, e.g. pull an image from a registry straight into a local OCI layout or a Podman storage graph. It handles auth via ~/.docker/config.json, Podman's auth file, or explicit --src-creds / --dest-creds.

Self-Hosting & Configuration

• Install via package manager (apt install skopeo, dnf install skopeo, brew install skopeo) or download static builds.
• No config required — defaults to Docker auth files. Override with --authfile for CI.
• Use skopeo sync --src yaml --dest docker with a YAML catalog for air-gapped mirroring workflows.
• Sign on copy with --sign-by + a GPG key, or use sigstore cosign for keyless signing.
• Run in CI containers from quay.io/skopeo/stable to avoid Docker-in-Docker gymnastics.

Key Features

• No daemon, no root required — runs anywhere including CI containers and scratch-sized images.
• True registry-to-registry copies: bytes stream directly without touching local disk.
• Signs and verifies with GPG or sigstore during copy.
• Multi-arch images are preserved with the full manifest list by default.
• First-class OCI support: archives, layouts, and image indexes all round-trip.

Comparison with Similar Tools

• docker pull/push — requires a daemon and pulls to local storage first; Skopeo is daemon-less and streams.
• crane (Google) — very similar feature set in Go; strong ecosystem but fewer transports.
• regctl — another daemon-less registry tool; nice UX, smaller feature set.
• ORAS — OCI artifact-focused; better for non-image artifacts like Helm charts and SBOMs.
• docker buildx imagetools — subset of skopeo features shipped with Docker; less portable.

FAQ

Q: Can Skopeo run on macOS? A: Yes — install via Homebrew; it speaks OCI registry APIs over HTTPS, no Linux-only deps.

Q: Does it support private registries with custom CAs? A: Yes — point --cert-dir at your CA bundle or use --tls-verify=false for insecure dev.

Q: How do I do air-gapped mirrors? A: Use skopeo sync --src docker --dest dir on the online side, rsync to the offline side, then skopeo sync --src dir --dest docker into the internal registry.

Q: Can it handle manifest lists (multi-arch)? A: Yes — pass --all to preserve every platform variant.

Sources

• https://github.com/containers/skopeo
• https://github.com/containers/skopeo/tree/main/docs