Export Docker Images Safely with docker save

That tar file docker save just wrote is worthless as a backup if nobody checks it is actually readable before the source image gets deleted. This builds a portable tar archive from one or more local images, checks that the archive is genuinely readable, and optionally compresses it. It is useful for moving an image to another Docker host or keeping an offline copy. Allow about ten minutes, plus however long writing the image layers takes; the archive itself can be large.

1. Check the installed command and image reference

This guide uses the Docker CLI 29.8.1 from the docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble. The installed manual describes docker save as an alias for docker image save; both forms take the same options.

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ docker image ls --format '{{.Repository}}:{{.Tag}}'
example/app:1.4
alpine:latest

Pick an exact image reference from the list. A name with no tag may resolve to :latest, but writing the tag out explicitly makes a backup much easier to identify and repeat later. This command only reads the local image store, so it normally needs no elevated privileges at all.

2. Write one image to a new tar file

Use -o or --output when the destination should be a file. This writes the image and its parent layers to a new file in the current directory:

$ docker save --output example-app-1.4.tar example/app:1.4
$ ls -lh example-app-1.4.tar
-rw------- 1 alice alice 245M Sep 23 07:30 example-app-1.4.tar

The size and timestamp are examples, not fixed output. A successful command normally prints no progress message at all, because the archive is simply written to the named file. Docker image archives hold the layers and repository metadata that docker load needs; they are not a filesystem snapshot of a running container.

3. Verify the archive without loading it

Use the system tar command to inspect the archive. This does not touch Docker's image store and does not start a container:

$ tar -tf example-app-1.4.tar | sed -n '1,12p'
 manifest.json
 repositories
 ...
$ test -s example-app-1.4.tar && echo 'archive is non-empty'
archive is non-empty

The exact layer directory names and listing length depend on the image. What matters is that the file exists, is non-empty, and reads as a valid tar archive. If tar -tf reports an error, keep the original image and rerun the export to a different temporary name. Do not delete the source image to reclaim space until the archive has passed your checks.

4. Save several tags or images together

Pass more than one image reference after the options. This is useful when a deployment expects related tags, or a whole set of images, to travel together:

$ docker save --output release-images.tar \
    example/app:1.4 example/worker:1.4 alpine:latest
$ tar -tf release-images.tar | sed -n '1,8p'
 manifest.json
 repositories
 ...

Docker includes each requested reference and the layers it actually needs. If two images share a layer, the archive can represent that shared data without you having to export it twice by hand. Pass tags deliberately, since exporting example/app:1.4 does not pull in every other tag in that repository.

5. Choose a platform when the image store has variants

In Docker 29.8.1, the installed command accepts --platform, formatted as os/arch or os/arch/variant, for example linux/amd64 or linux/arm64/v8. Without it, Docker saves every platform variant present in the daemon's image store. Selecting one can make an archive noticeably smaller and avoids carrying platforms the receiving host will never use:

$ docker save --platform=linux/amd64 \
    --output example-app-amd64.tar example/app:1.4
$ tar -tf example-app-amd64.tar | sed -n '1,8p'
 manifest.json
 repositories
 ...

The platform must already exist in the local image store. If it does not, Docker returns an error such as no suitable export target found for platform, and that failure does not create the variant for you. Check which platforms your local image actually contains with the image-management commands available in your Docker version, or export without the selector when every stored variant is required.

The platform option is an API 1.48+ feature in current Docker documentation. Older clients or daemons may reject it, so check both client and server versions before wiring it into a portable script.

6. Compress the stream when storage or transfer matters

With no output option, docker save streams the tar archive straight to standard output, which makes piping it through gzip straightforward:

$ docker save example/app:1.4 | gzip > example-app-1.4.tar.gz
$ gzip -t example-app-1.4.tar.gz && echo 'gzip stream is valid'
gzip stream is valid
$ gzip -dc example-app-1.4.tar.gz | tar -tf - | sed -n '1,8p'
 manifest.json
 repositories
 ...

Use gzip -t to check the compressed stream, then pipe decompression into tar -tf - to check the tar content underneath it. A compressed archive is still an image archive, not a Docker registry export. To restore one later, an operator uses docker load, but loading changes the destination image store, so plan that step separately.

7. Replace an old archive only after verification

For a recurring backup, write to a temporary name in the same directory, verify it, then replace the old archive. The mv step changes the backup set itself, so stop and check the paths before running it:

$ docker save --output example-app-1.4.tar.new example/app:1.4
$ tar -tf example-app-1.4.tar.new > /dev/null
$ mv -- example-app-1.4.tar.new example-app-1.4.tar
$ ls -lh example-app-1.4.tar
-rw------- 1 alice alice 245M Sep 23 07:34 example-app-1.4.tar