How to load a Docker image from a tarball

Loading a Docker image tarball is a practical way to move an image between hosts when registry access is unavailable, restricted, or intentionally skipped during backup and restore work. The archive can be copied between systems and restored directly into the local Docker image store without pulling from a registry.

The main command is docker image load, which reads an archive created by docker image save and restores the repository tags stored in that archive. Current Docker releases can read the archive from a file with --input or from standard input, and a multi-platform archive can be filtered with --platform when only one variant should be loaded.

Loading the archive only makes the image available locally. It does not start a container, replace a running workload, or remove older tags automatically, and a large tarball can take noticeable time and disk space while Docker unpacks the layers.

1. Confirm that the tarball is present at the path that will be passed to Docker.

   $ ls -lh ~/images/local-demo-app.tar
   -rw-r--r-- 1 user user 4.2M Apr 16 09:20 /home/user/images/local-demo-app.tar

   docker image load can read plain tar archives and compressed archives such as .tar.gz, .tar.bz2, .tar.xz, or .tar.zst.

2. Load the archive into the local Docker image store.

   $ docker image load --input ~/images/local-demo-app.tar
   Loaded image: local/demo-app:1.0

   The output lists every repository tag restored from the archive. When the tarball contains more than one platform variant, add --platform=linux/amd64 or the required platform string to load only that variant.

   Related: How to save a Docker image to a tarball

3. Inspect the restored image tag so the local name is confirmed before it is used elsewhere.

   $ docker image inspect local/demo-app:1.0 --format 'Image ID={{.Id}} Tags={{join .RepoTags ", "}}'
   Image ID=sha256:485931c968e2e71f5ccaea2a5d4a1071b9f88848c0c712a60f26035053bb4e5c Tags=local/demo-app:1.0

   The image ID may differ from this example, but the expected repository and tag should match the archive that was loaded.

4. Run a one-off container from the restored image when a quick execution check is needed.

   $ docker container run --rm local/demo-app:1.0
   Simplified Guide Docker load demo

   Use the real image command or entrypoint output as the success check on production images.

   docker image load does not replace a running container. Recreate or update the container separately if a workload needs to switch to the restored image.