Docker buildx experimental for interactive debugging

Published June 6, 2024

Do you remember the article about “not being able to run per layer docker images?”, it was actually the first article written on this blog. Luckily for me, as a former Docker Captain, I am surrounded by expert and contributors.

This time I need to thank @cpuguy because he gave me the tip I was looking for. I told you that buildkit is awesome because it is actually a library, embedded in many projects. Having a system that is easy to troubleshoot is key, so buildkit has something like a “debugger” built in. There is also a documentation page about how it is exposed in buildx and then via docker CLI.

Today I had the opportunity to try it out when moving an application from Python 3.11 to Python 3.12, even if it is a minor change Python often breaks in my experience!

 BUILDX_EXPERIMENTAL=1 docker build -t new-image -f Dockerfile --invoke /bin/bash .
[+] Building 193.4s (18/50)                                                                                                         docker:default
 => [internal] connecting to local controller                                                                                                 0.0s
 => [internal] load .dockerignore                        


59.73       AttributeError: module 'pkgutil' has no attribute 'ImpImporter'. Did you mean: 'zipimporter'?
59.73       [end of output]
59.73   note: This error originates from a subprocess, and is likely not a problem with pip.
59.73 error: subprocess-exited-with-error
59.73 × Getting requirements to build wheel did not run successfully.
59.73 │ exit code: 1
59.73 ╰─> See above for output.

First, you need to enable experimental feature for buildx via BUILDX_EXPERIMENTAL=1 environment variable. Then you have access to a new set of flags, the one I am looking at is –invoke, it accepts a command that will turn at the point where build will break in my case I am invoking /bin/bash because I know my image has it. So when it breaks, I land here:

Launching interactive container. Press Ctrl-a-c to switch to monitor console
Interactive container was restarted with process "uvkminnfak0bd13yssmnk9r9y". Press Ctrl-a-c to switch to the new container


Inside a running container from the image layer that I need to troubleshoot! Even better than what I had to do before (copy pasting the intermediate layer ID and docker run).

Now you are inside your container so you can figure out why the build process does not work as expected. You can do a lot more since buildx, and you are not simply inside your container: Press Ctrl-a-c to switch to monitor console and have a look yourself.

Are you having trouble figuring out your way to building automation, release and troubleshoot your software? Let's get actionables lessons learned straight to you via email.