Export Docker Images Safely with docker save

You will create a portable tar archive from one or more local Docker images, check that the archive is readable, and optionally compress it. This is useful for moving an image to another Docker host or keeping an offline copy. Allow about ten minutes, plus the time needed to write the image layers. The archive 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 use 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

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

Checkpoint: record the image reference you intend to export, and confirm that it is present locally. If it is missing, obtain it through your normal image build or pull process before continuing.

2. Write one image to a new tar file

Use -o or --output when the destination should be a file. The following 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 andy andy 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 because the archive is written to the named file. Docker image archives contain the layers and repository metadata needed by docker load; they are not a filesystem snapshot of a running container.

Warning: --output can replace an existing destination. Do not point it at the only copy of a useful archive until you have checked the path and made a backup or chosen a new filename.

3. Verify the archive without loading it

Use the system tar command to inspect the archive. This does not change 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. The useful checks are that the file exists, is non-empty, and can be read as a 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 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 needs. If two images share a layer, the archive can represent that shared data without requiring you to export it twice manually. Pass tags deliberately: exporting example/app:1.4 does not mean that every other tag in the repository is included.

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 all platform variants present in the daemon's image store. Selecting one can make an archive smaller and avoids carrying platforms the receiving host does not need.

$ 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 exist in the local image store. If it does not, Docker returns an error such as no suitable export target found for platform. That failure does not create the requested variant. Check which platforms your local image contains with the image-management commands available in your Docker version, or export without the selector when all locally stored variants are required.

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

6. Compress the stream when storage or transfer matters

With no output option, docker save streams the tar archive to standard output. That makes a pipeline to 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. A compressed archive is still an image archive, not a Docker registry export. To restore one later, an operator can use docker load, but loading changes the destination Docker image store and should be planned 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, 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 andy andy 245M Sep 23 07:34 example-app-1.4.tar

If the export or tar check fails, leave the existing archive untouched and remove only the incomplete .new file after inspecting the error. If the replacement was accidental and the old file was backed up, restore it with mv -- example-app-1.4.tar.bak example-app-1.4.tar. Without a backup, there is no undo for an overwritten file, so use a new destination when in doubt.