Someone hands you an image.tar file and expects it to work, and docker image load is what makes that true. It turns that archive back into a usable image. You will import it, confirm the image and tags that appeared in the local store, and know how to remove an import you did not mean to keep. The examples use Docker CLI 29.8.1 from the docker-ce-cli package installed here. Allow a few minutes for a small archive, or longer if it contains large layers.
image.tar, and enough disk space for the unpacked layers.sudo only if your setup requires it: membership of the docker group, where configured, is already elevated access to the daemon.Start by checking the installed command and the exact file you intend to import. This step is ordinary shell work and changes no Docker state:
docker image load --help
docker version --format '{{.Client.Version}}'
ls -lh image.tarOn this machine the client reports version 29.8.1. The options that matter are --input for a file, --platform for selecting image variants, and --quiet for suppressing load output. If ls says image.tar does not exist, stop and correct the path rather than guessing which archive to load.
Checkpoint: You have named the intended archive and confirmed that the Docker client can reach the daemon. If docker version reports a connection error, fix the daemon or socket access first.
Use --input when the archive is a named file. Replace the placeholder with the path you checked in step 1:
docker image load --input ./image.tarThe command reads the tar archive and restores the images and tags stored in it. A successful load normally prints one or more lines such as:
Loaded image: example/web:2026-09
Loaded image: example/web:latestThe exact names and line count come from the archive. Do not assume it contains only one tag: the same image ID can appear under several tags, and an imported tag can point at content already present locally.
Warning: Loading is a state-changing operation. An import may consume substantial disk space and may restore tags that alter which image a later deployment command selects. Review the output before using a tag in automation.
Standard input is useful when the archive is produced by another command or stored under a different filename. Redirect it into docker image load:
docker image load < ./image.tarThis is equivalent to using --input. It also works with an archive stream from another host, provided the transfer is complete and trustworthy:
ssh user@SOURCE_HOST 'cat /path/to/image.tar' | docker image loadA successful SSH connection is not proof that the archive is the one you wanted. Confirm the source path, transfer integrity and load output. A truncated or unrelated stream will fail, or could import the wrong image if it happens to be a valid archive.
Docker's current reference also documents gzip, xz and zstd-compressed tar archives. The local manpage describes a tar archive and the installed CLI accepts the same load interface, so test an unusual compression format against a non-production archive before relying on it in a scripted transfer.
Without a filter, Docker loads every platform variant present in the archive. To import only one, pass a comma-separated platform value using os/arch or os/arch/variant:
docker image load --input ./image.tar --platform linux/amd64
docker image load --input ./image.tar --platform linux/arm64/v8Use the platform that matches the host or workload you are preparing. An archive that lacks the requested variant produces an error such as:
requested platform (linux/ppc64le) not found: image might be filtered outThat message means the filter excluded everything in the archive. Adding sudo will not fix it. Inspect how the archive was created, or load it without --platform if you deliberately need every included variant.
After the load finishes, query the local image store using the tag printed by the command, replacing the example value below:
docker image ls example/web --no-trunc
docker image inspect example/web:2026-09 --format '{{.Id}} {{json .RepoTags}}'The listing should show the repository and tags that were restored, and docker image inspect should return an image ID and its repository tags. If you loaded several variants, inspect the relevant tag rather than guessing the platform from the tag alone. For a closer check, ask Docker for the platform recorded in the image configuration:
docker image inspect example/web:2026-09 --format '{{.Os}}/{{.Architecture}}'If verification fails with a missing image error, copy the tag exactly from the load output. A tag is case-sensitive in practice here, and the archive may have restored a name different from the one you expected.
Quiet mode suppresses the receipt. The --quiet option turns off load output:
docker image load --quiet --input ./image.tarUse it only when the surrounding script records success and does its own verification. It hides useful evidence while you are diagnosing a bad path, a corrupt archive or an unexpected set of tags. Docker still returns a failure status when the load fails, so check that status before proceeding:
set -eu
docker image load --quiet --input ./image.tar
docker image inspect example/web:2026-09 >/dev/null
echo 'image loaded and verified'This checks the command result and then checks that the expected tag exists. It does not prove the archive contained the intended bytes, so keep a trusted digest or archive checksum in your deployment process where that distinction matters.
If you loaded the wrong image, stop before using it.
docker image ls example/web --no-trunc.docker image rm example/web:2026-09.docker image ls example/web --no-trunc
docker image rm example/web:2026-09Removing a tag does not necessarily remove the underlying image if another tag or container still references it. Removing an image can affect containers or later commands that depend on it, so inspect the target before confirming. Do not use broad cleanup commands as an attempt to undo one import. If you need to preserve the archive for another host, keep the archive and its checksum; deleting the local tag is not a substitute for a backup.