# crane pull and push: Images as Tarballs

> crane pull saves a remote image to a tarball and crane push uploads a tarball to a registry, both without a daemon. Reference for --format, cache, and CI errors.

Source: https://latchkey.dev/learn/command-reference/crane-pull-push  
Updated: 2026-06-30

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

```Terminal
# 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-layout
```

## Options

| 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.

## FAQ

### crane pull and push: Images as Tarballs?

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.

### 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).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt