If you’re a fan of Docker and Visual Studio Code, which I am a fan of both, there’s some cool news that makes debugging Docker builds a whole lot easier. Docker and Microsoft have recently trying to improve the developer experience, working with Docker. The latest update now lets you debug Docker builds directly in VS Code.
In the past, if your Docker build failed or something didn’t act like you thought it would in your Dockerfile, your only real options were to add a bunch of RUN echo or RUN ls commands. You would then need to rebuild repeatedly, and hope you eventually found the issue. Now, Docker’s BuildKit debugger can actually open up an interactive debugging session right inside VS Code, letting you step through each instruction in your Dockerfile like real code.
You start by adding the new --debug flag to your Docker build command, like this:
Then VS Code will recognize the BuildKit debug session. It will then allow you to connect to it. Once you connect, you can see the build stages, inspect environment variables, and even poke around the container’s filesystem at each step. It’s a much more visual way to troubleshoot. This will allow you to much more easily see what's happening inside your image during the build process.
Below showing adding a breakpoint to your code and you can see that it has stopped where the breakpoint was added.
File explorer with the new docker build kit tool.
Inspecting variables with the new buildkit.
This new integration is really great for developers who work with multi-stage builds. You can pause inside any stage, check dependencies, and verify installed binaries. You can then make sure your COPY or RUN instructions are doing what you think they are before moving on.
To make it work, you’ll need to have the latest Docker extension for VS Code and make sure you’re using BuildKit. You need this since the debugger relies on BuildKit’s capabilities. Once you’ve got that, you can either attach to a running build or launch one straight from VS Code using the “Docker: Build with Debug” command from the Command Palette.
If you are like me, this feels like a big step forward if you have ever spent too long trying to fix broken Docker builds, which I have definitely sunk many hours into this in the home lab and production environments. Instead of guessing what went wrong, you can now literally step through your build and inspect the state of things in real time.
I’ve tried it out on a small self-hosted app I have built, and it works really well. You can drop into the environment mid-build and even run commands manually to test things out. I think the work between Docker and Microsoft and their collaboration are really tightening the loop between development and building containers.
If you want to dig deeper, the full write-up from Docker has step-by-step details and screenshots showing how it all works: Debug Docker Builds with Visual Studio Code
Definitely worth checking out if you’re building images regularly or tired of “debugging by rebuild.” This should save a ton of time for anyone who’s serious about Docker development.