Turn a Root Filesystem Tarball into a Docker Image

You will finish with a tagged Docker image made from a root filesystem tarball, plus checks that confirm its contents and metadata. 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.

You need a working Docker daemon, the Docker CLI, a readable archive, and enough space for the imported layer. The commands that only inspect files or images are ordinary user commands. Use elevated privileges only when your source files require them, and do not use sudo to make a Docker permission problem disappear without checking which daemon and user you are 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 that a file named rootfs.tgz has the layout you want. If the archive is a single file rather than an archive, the Docker documentation requires the full path that the file should have on the host; 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 supported by your local tar. 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 will differ 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 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 be different. If the import was run 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 that is 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

Do not treat a successful import as proof that an application will run. It confirms that 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 appear 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 when 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 that 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.