Repolode
Submit
ktock

ktock/buildg

Interactive debugger for Dockerfile builds, offering breakpoints, step execution, and shell access inside build steps, built on BuildKit.

View on GitHub
Stars
1,503
Forks
40
Open issues
15
Last commit
3 months ago

What is it?

buildg is a debugger for Dockerfile builds. Instead of rerunning a long build and guessing where it failed, you can set breakpoints on Dockerfile lines, step through instructions one at a time, and inspect the build context and filesystem at each step.

When paused at a step, you can open an interactive shell in that step's state and run your own debugging tools. Optionally, a custom debugger image can be attached so the shell runs with tools not present in the build image. buildg also works with editors through the Debug Adapter Protocol, which lets VS Code, Emacs, and Neovim drive the debugger with visual breakpoints.

buildg is built on BuildKit, with some patches not yet merged upstream, and supports rootless execution. Native execution is currently limited to Linux; other platforms need a Linux VM. The project is marked as early-stage software. It is also available as a subcommand of nerdctl.

Key features

  • 01Set breakpoints on Dockerfile lines or on steps that fail.
  • 02Step through build instructions and continue to a chosen breakpoint.
  • 03Open an interactive shell inside a build step to inspect its state.
  • 04Attach a custom debugger image with your own tools.
  • 05Integrates with editors such as VS Code, Emacs, and Neovim via DAP.
  • 06Supports rootless execution.

Use cases

  • Finding which instruction in a large, slow Dockerfile breaks the build.
  • Inspecting files and environment at an intermediate build step.
  • Debugging Dockerfile builds from inside VS Code or Neovim.
  • Investigating build cache behavior by examining remotely cached builds.

Quick start

  1. 1

    Install Go 1.23+ and clone the repository

    git clone https://github.com/ktock/buildg
  2. 2

    Build the binary with make

    make
  3. 3

    Install the binary to your system

    sudo make install
  4. 4

    Start a debug session on a build context

    buildg debug /path/to/build/context

Things to know

  • Native execution is supported only on Linux; other platforms need a Linux VM.
  • The project is early-stage software built on BuildKit with unmerged patches.
  • Running it in rootless mode is required for IDE (DAP) integration.

Topics

#docker#dockerfile#debugger#buildkit#container#devtools#dap

FAQ

What is buildg?
Interactive debugger for Dockerfile builds, offering breakpoints, step execution, and shell access inside build steps, built on BuildKit. buildg is a debugger for Dockerfile builds. Instead of rerunning a long build and guessing where it failed, you can set breakpoints on Dockerfile lines, step through instructions one at a time, and inspect the build context and filesystem at each step.
Is buildg free to use? What license does it have?
buildg is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is buildg still maintained?
Updated within 6 months. The last commit to buildg was on Jul 30, 2026.
What can I use buildg for?
Finding which instruction in a large, slow Dockerfile breaks the build. Inspecting files and environment at an intermediate build step. Debugging Dockerfile builds from inside VS Code or Neovim. Investigating build cache behavior by examining remotely cached builds.
How do I install buildg?
Install Go 1.23+ and clone the repository: git clone https://github.com/ktock/buildg Build the binary with make: make Install the binary to your system: sudo make install Start a debug session on a build context: buildg debug /path/to/build/context
Where can I get buildg?
The source code and installation instructions are on GitHub: https://github.com/ktock/buildg

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects