tar with docker save/load: Image Tarballs (CI Errors)

docker save emits an image as a tar stream you can gzip, cache, and docker load later.

Caching Docker images between jobs is a tar problem: docker save produces a tar, you compress it, store it, and reload it. The format details are where pipelines go wrong.

What it does

docker save writes one or more images, including their layers and manifest, to a tar stream on stdout (or to -o file). docker load reads that tar back. Because the output is a plain tar, you can compress it with gzip or zstd for storage and decompress before loading.

Common usage

Terminal

docker save myimage:tag | gzip > image.tar.gz     # save + compress
gunzip -c image.tar.gz | docker load              # decompress + load
docker save -o image.tar myimage:tag              # save to a file
docker save myimage:tag | zstd > image.tar.zst    # zstd for speed

Options

Form	What it does
docker save img \| gzip	Stream the image tar through gzip
docker save -o file img	Write the image tar to a file
docker load -i file	Load an image from a tar file
... \| docker load	Load an image arriving on stdin
docker image inspect	Verify the image landed after load

In CI

To share a built image across jobs without a registry, save and gzip it as a cache artifact: docker save app:ci | gzip > image.tgz in the build job, gunzip -c image.tgz | docker load in the next. Use the image digest as part of the cache key so a rebuild invalidates the cache.

Common errors in CI

gzip: stdin: not in gzip format on load means you fed a plain tar to gunzip, or saved without compressing; load the raw tar with docker load -i image.tar. open /var/lib/docker/tmp/...: no space left on device during load is a full-disk error; prune images or expand the runner volume. invalid tar header usually means the artifact was corrupted or truncated in transit.