convert docker images to rootfs
Go to file
Motiejus Jakštys 6400df9612 Makefile: make VSNHASH, LDFLAGS overridable 2024-05-12 07:33:29 +03:00
rootfs upgrade to go 1.20 2023-05-19 15:05:21 +03:00
t add integration tests 2024-05-10 15:59:04 +03:00
.gitignore add integration tests 2024-05-10 15:59:04 +03:00
LICENSE re-license to apache2 2023-02-09 10:23:35 +02:00
Makefile Makefile: make VSNHASH, LDFLAGS overridable 2024-05-12 07:33:29 +03:00 update README w.r.t. integration tests 2024-05-10 16:00:49 +03:00
go.mod upgrade to go 1.20 2023-05-19 15:05:21 +03:00
main.go main.go: fix Sprintf -> Fprintf 2024-05-10 14:50:29 +03:00
main_test.go replace io/ioutil with os 2023-01-03 16:00:34 +02:00
release shell scripts: shfmt 2024-05-10 16:10:29 +03:00


Converts a Docker image (a bunch of layers) to a flattened "rootfs" tarball.

Project Status

The project was announced to be deprecated in the beginning of 2024, but the maintainer has an interest in Docker ecosystem again, thus will maintain it somewhat starting at mid-2024.

The author has some significant changes in mind, but the timeline is unknown.


Docker images became a popular way to distribute applications with their dependencies; however, Docker is not the best runtime environment. At least not for everyone. May boring technology run our software.

Undocker bridges the gap between application images (in docker image format) and application isolation ("container") runtimes: once the docker image is extracted, it can be run with old-fashioned tools: lxc, systemd-nspawn, systemd, FreeBSD Jails, and many others.


Build it like this for the "current" platform:

$ make undocker

make -B will print the extra flags (-X <...>) for cross-compiling with other archs. It's all go build <...> in the back, and depends only on Go's compiler and stdlib.

Usage: convert docker image to rootfs

Download busybox docker image from docker hub and convert it to a rootfs:

$ skopeo copy docker:// docker-archive:busybox.tar
$ undocker busybox.tar - | tar -xv | sponge | head -10; echo '<...>'

Refer here for other ways to download Docker images. There are many.

On author's laptop converting a 1.1GB Docker image with 77 layers takes around 3 seconds and uses ~65MB of residential memory.

Usage example: systemd

systemd-run \
  --wait --pty --collect --service-type=exec \
  -p RootDirectory=$PWD \
  -p ProtectProc=invisible \
  -p PrivateUsers=true \
  -p DynamicUser=yes \
  -- busybox httpd -vfp 8080

Systemd protections like PrivateUsers, DynamicUser, ProtectProc and others are available, just like to any systemd unit.

Similar Projects


The following contributions may be accepted:

  • Patchsets, with accompanying tests.
  • Regression reports.

If you found a container that undocker cannot extract, or extracts incorrectly and you need this that work with undocker, submit a patchset. If there is a reasonably small container that can reproduce the issue, we may add it to integration tests. See make test-integration on how that works.

Reports of regression reports must provide examples of "works before" and "does not work after". Issues without an accompanying patch will most likely be rejected.


Feel free to ping me directly.