Turn a Tarball into a Docker Image with docker import

You have a root filesystem tarball and no Dockerfile in sight, and docker import is the tool that turns that tarball straight into a tagged image. This guide uses Docker 29.8.1 from the installed docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble. Allow about fifteen minutes if the tarball already exists, or longer if you need to assemble and inspect it first.

• You need: a working Docker daemon, the Docker CLI, a readable archive, and enough space for the imported layer.
• Privilege note: commands that only inspect files or images are ordinary user commands. Use elevated privileges only when your source files require them, and never use sudo to make a Docker permission problem disappear without checking which daemon and user you are actually addressing.

1. Check the installed command

docker import is an alias for docker image import. Its input is one file, URL or dash, followed by an optional REPOSITORY[:TAG] name:

$ docker import --help
Usage:  docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]

Options:
  -c, --change list       Apply Dockerfile instruction to the created image
  -m, --message string    Set commit message for imported image
      --platform string   Set platform if server is multi-platform capable

The command does not build Dockerfile instructions. It creates a filesystem layer from the input and can apply a limited set of image metadata changes. Check the daemon as well as the client before starting an import:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker info > /dev/null && echo 'Docker daemon is reachable'
Docker daemon is reachable

2. Inspect the archive before Docker reads it

An archive is input data, not a trust boundary. List its entries without extracting them, and look for unexpected top-level paths before importing it:

$ tar -tzf /path/to/rootfs.tgz | sed -n '1,20p'
./
./etc/
./etc/os-release
./bin/
./bin/sh

The exact listing depends on the archive. Docker untars an archive relative to the image root, so a file stored as etc/os-release becomes /etc/os-release in the resulting filesystem. Do not assume a file named rootfs.tgz has the layout you want. If the archive is a single file rather than an archive, Docker's documentation requires the full path that the file should have on the host, so use a real archive for a normal root filesystem import.

For an uncompressed tar file, replace -tzf with -tf. For another compression format, use the matching tar option your local tar supports. Keep the original archive until the image has passed its checks.

3. Import and tag the filesystem

Give the image a repository and tag so later commands do not depend on an untagged image ID:

$ docker import \
    --message 'Imported checked root filesystem' \
    /path/to/rootfs.tgz \
    example/rootfs:local
sha256:IMAGE_ID_PRINTED_HERE

The digest is generated by Docker and differs on every import. A successful import prints it on standard output. The --message value becomes the image history comment: it is metadata, not a shell command. Keep repository and tag values to names you actually intend to retain.

Verify that the tag resolves to the new image:

$ docker image inspect --format '{{.RepoTags}} {{.Id}}' example/rootfs:local
[example/rootfs:local] sha256:IMAGE_ID_PRINTED_HERE

The ID in your output will differ. If the import ran without a repository and tag, Docker creates an untagged image: find it by the digest from the import output, then add a tag with docker image tag, or remove it deliberately after inspection.

4. Check the filesystem and history

Inspect files inside the image by creating a short-lived container. This is an ordinary Docker operation, but it may need the same daemon access as the import:

$ docker run --rm --entrypoint /bin/sh example/rootfs:local \
    -c 'test -f /etc/os-release && printf "%s\n" "root filesystem check passed"'
root filesystem check passed

This check assumes the imported filesystem contains /bin/sh and /etc/os-release. Substitute a path meaningful for your archive. The --rm option removes the stopped test container; it does not remove the image.

Check the imported comment in the history output:

$ docker image history example/rootfs:local
IMAGE        CREATED        CREATED BY   SIZE     COMMENT
IMAGE_ID...  moments ago                 ...      Imported checked root filesystem

A successful import is not proof that an application will run. It confirms Docker accepted the archive and created an image. Entrypoints, environment variables, volumes, working directory and exposed ports are separate image configuration concerns.

5. Add metadata only when you have reviewed it

The --change option can apply supported metadata instructions while creating the image. Current Docker documentation lists CMD, ENTRYPOINT, ENV, EXPOSE, HEALTHCHECK, LABEL, ONBUILD, STOPSIGNAL, USER and VOLUME. It does not turn an import into a general Dockerfile build:

$ docker import \
    --change 'ENV APP_MODE=local' \
    --change 'WORKDIR /srv/app' \
    --change 'CMD ["/bin/sh"]' \
    /path/to/rootfs.tgz \
    example/rootfs:configured

Each --change value is passed as one quoted shell argument. Review values that set startup commands, users, mounts or health checks before importing: a mistaken ENTRYPOINT or CMD can make a later container look broken even though the filesystem is intact.

6. Handle platforms and failed imports

By default, Docker uses the daemon's native platform. If the root filesystem targets another operating system or architecture and the daemon supports multiple platforms, set it explicitly:

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

The platform label does not translate binaries. An amd64 filesystem still needs a compatible runtime or emulation to run on another architecture.

If import fails, keep the source archive and read the error before retrying. Check its type with file /path/to/rootfs.tgz, list it with the correct tar option, and confirm the Docker daemon has enough storage. If a test image was created before a later check failed, remove only that known tag:

$ docker image rm example/rootfs:local
Untagged: example/rootfs:local

Removing a tag may leave the image available through another tag or digest. Check docker image ls before removing further references. Do not prune the whole image store as a cleanup shortcut.