Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 111 ยท Images

Save, Load, Export, Import

Move Docker images without a registry: docker save and load for images, export and import for container filesystems, and why docker commit is usually a trap.

Registries are the normal way to move images between machines, but sometimes there is no registry: an air-gapped server, a customer who needs a file on a USB stick, a backup you want to keep next to your code. Docker has four commands for turning images and containers into plain files and back again: docker save and docker load, and docker export and docker import. They look like two pairs of the same thing. They are not, and mixing them up is a classic way to lose an image's configuration.

In this lesson you will use all four, open the files they produce, and see exactly what each one keeps and what it throws away. You will also meet docker commit, which turns a container into an image in one step and is almost always the wrong tool.

The two pairs at a glance

TEXT
            docker save                       docker export
  IMAGE  ---------------->  tar of IMAGE   CONTAINER ---------------> tar of one FILESYSTEM
  (layers, tags, config)    (layers, tags,  (running or stopped)      (flattened, no history,
                             config kept)                              no config, no volumes)
            docker load                       docker import
  tar of IMAGE ---------->  IMAGE         tar of FILESYSTEM -------> new IMAGE (one layer,
                                                                        you add config yourself)
Command Works on Keeps layers and history Keeps CMD, ENV, tags Includes volumes
docker save / load images yes yes not applicable
docker export / import containers no, one flat layer no no

If your goal is "move this image to another machine", use save and load. export and import exist for the rarer job of capturing the files of a container, for example to inspect them or to build a base image from a root filesystem.

docker save and docker load

docker save writes one or more images, with all their layers, tags and configuration, into a tar archive. We will use a tiny image:

CONSOLE
$ docker tag busybox:1.37 tool:1.0
$ docker save -o tool.tar tool:1.0
$ ls -l tool.tar
-rw-r--r-- 1 you you 2235392 ... tool.tar

The archive is about 2 MB. Without -o, docker save writes the archive to standard output, so you can pipe it (more on that below). The archive uses the OCI image layout, and you can look inside it with plain tar:

CONSOLE
$ tar -tf tool.tar
blobs/
blobs/sha256/
blobs/sha256/30ecbe1509090b38...
blobs/sha256/68fe9bff2ad4ad46...
blobs/sha256/bdf57e528e45e443...
index.json
manifest.json
oci-layout

(The blobs/sha256 list is longer in reality, with one file per layer, config and manifest. We shortened it.) Two small JSON files tell the story. manifest.json links the name to the image's configuration blob and its layer files:

CONSOLE
$ tar -xOf tool.tar manifest.json
[{"Config":"blobs/sha256/30ecbe1509090b38...","RepoTags":["tool:1.0"],"Layers":["blobs/sha256/68fe9bff2ad4ad46..."]}]

RepoTags is why load can restore the tag. The Layers list is the image's filesystem, one entry per layer. Everything is content-addressed, so the file names are the SHA-256 hashes of their content.

To restore the image on another machine, copy the file over and run docker load:

CONSOLE
$ docker rmi tool:1.0
Untagged: tool:1.0
$ docker load -i tool.tar
Loaded image: tool:1.0

The image comes back with its original name and tag, because the tag was stored in the archive. Nothing was downloaded: this works with the network cable unplugged.

Compression and pipes

A saved archive is not compressed as a whole, so compress it yourself when size matters:

CONSOLE
$ docker save tool:1.0 | gzip > tool.tar.gz
$ docker rmi tool:1.0
$ gunzip -c tool.tar.gz | docker load
Loaded image: tool:1.0
$ docker load < tool.tar.gz
Loaded image: tool:1.0

docker load also reads a gzip-compressed archive directly, as the last command above shows. In this particular example tool.tar.gz was almost the same size as tool.tar (about 2.2 MB), because the layers inside are already gzip-compressed. Expect real savings only when your layers are not already compressed.

A pipe can also move an image directly to another host without a temporary file, for example over SSH:

Terminal
# read-only example: needs a second machine with Docker and SSH access
docker save tool:1.0 | ssh user@server docker load

You can save several images into one archive with docker save -o stack.tar web:1.0 db:1.0. Layers they share are stored once, so one archive is smaller than two separate ones.

Save by image name, not by ID, when you want the names back: the archive records the names you passed on the command line. If a name is missing after docker load, tag the image again with docker tag.

docker export and docker import

docker export works on a container, not an image. It writes the container's current filesystem as one flat tar archive, with every layer merged. The container can be running or stopped. First create something to export:

CONSOLE
$ docker run -d --name box tool:1.0 sleep 600
$ docker exec box sh -c 'echo "hello from the writable layer" > /root/note.txt'
$ docker export -o box.tar box
$ tar -tf box.tar | head -4
.dockerenv
bin/
bin/[
bin/[[
$ tar -tf box.tar | grep -E 'root/note|dockerenv'
.dockerenv
root/note.txt

The archive contains the whole root filesystem, including .dockerenv (a marker file Docker places in every container) and the file we just created. Notice what is not in it: there are no separate layers, no image history and no metadata such as CMD or ENV.

docker import turns such an archive back into an image:

CONSOLE
$ docker import box.tar imported:1.0
sha256:5e79ee7bece5...
$ docker image inspect imported:1.0 --format 'cmd={{.Config.Cmd}} env={{.Config.Env}}'
cmd=[] env=[]
$ docker image inspect tool:1.0 --format 'cmd={{.Config.Cmd}} env={{.Config.Env}}'
cmd=[sh] env=[PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin]

The original image had a default command (sh) and a PATH. The imported one has neither. Running it without a command fails, and docker history shows a single layer with no build steps:

CONSOLE
$ docker run --rm imported:1.0
docker: Error response from daemon: no command specified

Run 'docker run --help' for more information
$ docker run --rm imported:1.0 cat /root/note.txt
hello from the writable layer
$ docker history imported:1.0
IMAGE          CREATED         CREATED BY   SIZE      COMMENT
5e79ee7bece5   6 seconds ago                4.58MB    Imported from -

The files are all there, including the note we wrote inside the container, but the configuration is gone. You can put some of it back at import time with -c (the same instructions you would write in a Dockerfile, such as CMD, ENV, ENTRYPOINT, EXPOSE, WORKDIR, USER):

CONSOLE
$ docker import -c 'CMD ["sh"]' -c 'ENV APP=demo' box.tar imported:2.0
$ docker image inspect imported:2.0 --format 'cmd={{.Config.Cmd}} env={{.Config.Env}}'
cmd=[sh] env=[APP=demo]

import can also read from a URL or from standard input (-), which is how some people build a base image from a root filesystem tarball (debootstrap output, for example). In day-to-day work, though, you will need import rarely.

What export leaves out: volumes

docker export only sees the container's own filesystem. Data stored on a mounted volume lives outside it. We started a container with a named volume at /data, wrote a file into the volume and one into the container's own filesystem, and exported:

CONSOLE
$ docker export box | tar -t | grep -E 'data|plain'
data/
root/plain.txt

The data/ directory exists as an empty mount point, but db.txt (which was written to the volume) is missing. If you care about database files, you need a volume backup, not an export. See Backup and Restore.

docker commit: why it is usually a trap

docker commit takes a container and saves its changes as a new image layer on top of the image it came from:

CONSOLE
$ docker commit -m "add note" -a "you" box committed:1.0
sha256:b3b32b88b4f0...
$ docker history committed:1.0
IMAGE          CREATED        CREATED BY                          SIZE      COMMENT
b3b32b88b4f0   1 second ago   sleep 600                           12.3kB    add note
bdf57e528e45   2 years ago    BusyBox 1.37.0 (glibc), Debian 13   4.55MB    
$ docker run --rm committed:1.0 cat /root/note.txt
hello from the writable layer

It works, and for a quick experiment (or to capture a tricky debugging state) that is fine. But look at the CREATED BY column: the new layer is labelled with sleep 600, the command the container happened to run, not with the steps that produced the change. Nobody, including you in three months, can tell what is in that layer or how to rebuild it.

The problems with commit-built images are the reasons Dockerfiles exist:

  • Not reproducible. There is no recipe, only a snapshot of whatever state the container was in.
  • Hidden junk. Package caches, shell history and temporary files get captured along with your change.
  • Nobody can review it. A Dockerfile can be code-reviewed and versioned; a binary snapshot cannot.
  • Volumes are not captured. As with export, only the container's own filesystem is committed, which we confirmed: a committed image started from a container with a volume had an empty /data.

You can see what would be committed with docker diff, which lists added (A), changed (C) and deleted (D) paths:

CONSOLE
$ docker diff box
C /root
A /root/note.txt

If you find a useful change this way, the right move is to turn it into a RUN line in a Dockerfile (see Writing a Dockerfile) and rebuild.

Which one should I use?

  • Move an image to another machine, offline: docker save and docker load.
  • Keep a backup copy of an image next to your project: docker save, compressed.
  • Get the files out of a container as a single archive: docker export (or docker cp for a single path; see Logs and exec).
  • Make an image from a root filesystem tarball: docker import, adding config with -c.
  • Capture a debugging state quickly: docker commit, then throw the image away.
  • Create an image you will ship: none of these; write a Dockerfile.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You need to copy an image, with its tag and default command, to a server that has no internet. Which pair of commands do you use?

    save and load work on images and keep layers, tags and configuration. export and import flatten a container's filesystem and lose the configuration.
  2. 2. After docker import box.tar imported:1.0, running docker run --rm imported:1.0 fails with no command specified. Why?

    docker export stores files only. The default command and environment belong to the image configuration, which is not part of the archive. Add it with docker import -c 'CMD ["sh"]' or pass a command to docker run.
  3. 3. What does docker export leave out?

    Only the container's own filesystem is exported. A volume's contents live outside it, so only an empty mount point directory appears in the archive.
  4. 4. Which is the best reason to avoid docker commit for images you ship?

    A committed layer is just a snapshot labelled with the container's command. A Dockerfile records every step, so it can be reviewed, versioned and rebuilt.
  5. 5. How can you restore the tag when loading an image saved with docker save?

    The archive's manifest records RepoTags. If you save by image ID instead of by name, no tag is recorded and you have to tag the image yourself.

Summary

  • docker save writes an image (layers, tags, configuration) to a tar archive; docker load reads it back, even when it is gzip-compressed. Pipe through gzip or ssh as needed.
  • docker export writes one container's merged filesystem as a flat tar; docker import turns that into a new single-layer image without CMD, ENV or history, unless you add them with -c.
  • Neither export nor commit includes volume data.
  • docker commit records a snapshot labelled with the container's command, so the result is hard to reproduce or review. Prefer a Dockerfile.
  • Save by name to keep tags; save several images in one archive to share layers.

Next: Writing a Dockerfile