crane pull and push: Images as Tarballs
crane pull writes a remote image to a local tarball and crane push uploads a tarball to a registry, moving images without a Docker daemon.
Sometimes you need the image as a file (to scan it, cache it, or move it across an air gap). crane pull and push do that without docker save/load.
What it does
crane pull downloads an image reference and writes it as a tarball (docker or OCI layout). crane push reads such a tarball and uploads it to a destination reference. Together they replace docker save / docker load in daemonless environments.
Common usage
# pull to a tarball
crane pull ghcr.io/acme/app:1.4.0 app.tar
# push a tarball to a new reference
crane push app.tar ghcr.io/acme/app:promoted
# pull as an OCI layout directory
crane pull --format=oci ghcr.io/acme/app:1.4.0 ./oci-layoutOptions
| Flag | What it does |
|---|---|
| pull REF PATH | Save reference REF to tarball/dir PATH |
| push PATH REF | Upload tarball/dir PATH to reference REF |
| --format tarball|oci | Output layout for pull (default docker tarball) |
| --cache_path <dir> | Layer cache directory to reuse across pulls |
| --insecure | Allow HTTP / skip TLS verification |
In CI
crane pull produces a tarball you can hand to a scanner or archive as a build artifact without a daemon; crane push re-uploads it to another registry. For air-gapped promotion, pull on the internet side and push on the internal side.
Common errors in CI
"MANIFEST_UNKNOWN" on pull means the source does not exist. "UNAUTHORIZED: authentication required" on push means the destination needs a login. "unexpected status code 400" pushing a tarball to a registry that rejects the schema means re-pull with --format=oci (or push with skopeo). A truncated tarball error usually means the artifact was not fully downloaded between jobs.