Import a Root Filesystem with docker image import

A vendor hands you a bare root filesystem tarball instead of a proper Docker image, and docker image import is how you turn it into one. You will give it a predictable tag and verify its contents and metadata. Allow about fifteen minutes if the tarball already exists and the Docker daemon is running.

This guide uses Docker Community Edition CLI 29.8.1, from the installed docker-ce-cli package version 5:29.8.1-1~ubuntu.24.04~noble. You need a readable root filesystem archive, the Docker CLI, and access to the Docker daemon. Most inspection commands are ordinary user commands. Import itself may need access to the Docker socket, which commonly means membership of the docker group or sudo on a host using the root-owned socket.

Warning: importing creates image data in the daemon's storage. It does not create a running container, but the tarball becomes trusted input for anything later started from the image. Keep the source archive until you have checked the result. Do not import an archive from an untrusted source into a daemon whose images or socket are used by other workloads.

1. Check the command and choose the input

Confirm the installed syntax before copying a command into a script:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker image import --help
Usage:  docker image import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]

docker image import accepts a local archive path, an HTTP or HTTPS URL, or - for standard input. The archive should contain a filesystem tree to become the image's root filesystem. It is not a Docker image archive produced by docker image save; use docker image load for that different format.

The supported archive suffixes documented for this command are .tar, .tar.gz, .tgz, .bzip, .tar.xz, and .txz. Docker also accepts an individual file path, but that file must represent the full path within the imported filesystem. If you are unsure what an archive contains, inspect it without extracting it:

$ tar -tf /path/to/rootfs.tgz | sed -n '1,20p'

2. Import the archive with a tag

Use a repository and tag that describe the image's purpose. The following command changes daemon state, so use sudo only if your Docker access requires it:

$ docker image import /path/to/rootfs.tgz local/rootfs:2026-09-23
sha256:<image-digest>

The digest is generated by Docker and will differ on your host. A repository tag makes later commands unambiguous. If you omit the destination, Docker creates the image without a repository tag, which is awkward to reference and easy to confuse with another untagged image.

Checkpoint: List the exact reference you just created:

$ docker image ls local/rootfs:2026-09-23
REPOSITORY    TAG         IMAGE ID       CREATED          SIZE
local/rootfs  2026-09-23  <image-id>    <time>           <size>

Column spacing, the image ID, age and size vary. The repository and tag should match your command.

3. Import through standard input when a pipeline is useful

A dash tells Docker to read the archive from standard input. This is useful when the archive is produced by another command, and it avoids creating a second copy on disk:

$ cat /path/to/rootfs.tgz | docker image import - local/rootfs:piped

For a directory, archive its contents rather than the directory entry if the desired root is the directory itself:

$ tar -c -C /path/to/rootfs . | docker image import - local/rootfs:directory

Ownership is a common trap. A non-root tar process may not preserve root-owned files from the source tree. When those ownerships are part of the image's contract, archive the directory with the required privilege:

$ sudo tar -c -C /path/to/rootfs . | docker image import - local/rootfs:directory

Review the source tree and the privilege boundary first. sudo gives the archiving process access to more files; it does not make the resulting image safer.

4. Apply image metadata during import

The --change option applies supported Dockerfile-style metadata instructions to the new image. It does not run arbitrary build steps. Supported instructions include CMD, ENTRYPOINT, ENV, EXPOSE, HEALTHCHECK, LABEL, ONBUILD, STOPSIGNAL, USER, VOLUME and WORKDIR.

Quote each instruction as one shell argument. You can repeat the option:

$ docker image import \
    --change 'ENV APP_ENV=production' \
    --change 'WORKDIR /srv/app' \
    --change 'CMD ["/srv/app/start"]' \
    /path/to/rootfs.tgz local/rootfs:configured

Inspect the resulting configuration instead of assuming the shell quoting did what you intended:

$ docker image inspect --format '{{json .Config}}' local/rootfs:configured

Do not put package installation, file copies or other build commands in --change. If the filesystem needs those changes, prepare the root filesystem separately or use a Dockerfile build with an explicit reviewable context.

5. Record a message and verify the platform

--message stores a human-readable comment in the imported image's history. It is useful for recording why an archive was imported:

$ docker image import \
    --message 'Imported vendor root filesystem for test review' \
    /path/to/rootfs.tgz local/rootfs:review
$ docker image history local/rootfs:review

The history output should show the message in the comment column. The exact digest, timestamps and size are host-specific.

By default the daemon's native platform is used. If the daemon supports multiple operating systems or architectures, set the platform explicitly when the root filesystem is for another one:

$ docker image import --platform=linux/amd64 \
    /path/to/rootfs.tgz local/rootfs:amd64
$ docker image inspect --format '{{.Os}}/{{.Architecture}}' local/rootfs:amd64
linux/amd64

Do not use a platform label to make incompatible binaries work. It records the intended platform; you still need an appropriate runtime and host support.

6. Diagnose failures and remove a test image

A failure to open the archive usually means the path or read permission is wrong. Check without changing Docker state:

$ test -r /path/to/rootfs.tgz && echo readable
$ tar -tf /path/to/rootfs.tgz >/dev/null && echo valid-tar

An import can succeed while producing an unusable image if the archive has the wrong top-level layout, missing executables or unsuitable ownership. Inspect the archive before import, then inspect the image configuration and test it in an isolated container before using it for a service.

If this was a disposable test image, remove its tag after checking it:

$ docker image rm local/rootfs:review

This removes the named image reference and may remove image data that is no longer referenced. Do not run it against a tag used by a running or important container. There is no undo command; recreate the image from the original archive if you remove it accidentally.

Done means