Skip to content
use new container attach on already container go on debug
Branch: master
Clone or download
Latest commit ea9ecb9 Apr 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.chglog fix: file mode Mar 19, 2019
internal feat: support -v mount filesystem Apr 21, 2019
pkg fix: code style fmt Apr 3, 2019
scripts feat: travis add deploy Apr 9, 2019
version feat: command add more Mar 20, 2019
.gitignore feat: add cmd pkg Mar 13, 2019
.reviewdog.yml test: add reviewdog ci Apr 1, 2019
.travis.yml fix: ci config Apr 9, 2019
LICENSE docs: add license Apr 3, 2019 docs: update readme Apr 21, 2019
demo.cast feat: update asciinema demo Mar 20, 2019
go.sum fix: update docker deb pkg latest Apr 5, 2019


Build Status Go Report Card



docker-debug is an troubleshooting running docker container, which allows you to run a new container in running docker for debugging purpose. The new container will join the pid, network, user, filesystem and ipc namespaces of the target container, so you can use arbitrary trouble-shooting tools without pre-installing them in your production container image.



Quick Start

Install the docker-debug cli

mac brew

brew tap zeromake/docker-debug
brew install docker-debug

download binary file

# MacOS
curl -Lo docker-debug

# Linux
curl -Lo docker-debug

chmod +x ./docker-debug
sudo mv docker-debug /usr/local/bin/

# Windows
curl -Lo docker-debug.exe

download the latest binary from the release page and add it to your PATH.

Try it out!

# docker-debug [OPTIONS] CONTAINER COMMAND [ARG...] [flags]

# More flags
docker-debug --help

# info
docker-debug info

Build from source

Clone this repo and:

go build -o docker-debug ./cmd/docker-debug
mv docker-debug /usr/local/bin

Default image

docker-debug uses nicolaka/netshoot as the default image to run debug container. You can override the default image with cli flag, or even better, with config file ~/.docker-debug/config.toml

version = "0.5.0"
image = "nicolaka/netshoot:latest"
mount_dir = "/mnt/container"
timeout = 10000000000
config_default = "default"

    host = "unix:///var/run/docker.sock"
    tls = false
    cert_dir = ""
    cert_password = ""


  • support windows7(Docker Toolbox)
  • support windows10
  • refactoring code
  • add testing
  • add changelog
  • add
  • add brew package
  • docker-debug version manage config file
  • cli command set mount target container filesystem
  • mount volume filesystem
  • docker connection config on cli command
  • -v cli args support
  • docker-debug signal handle smooth exit
  • cli command document on readme
  • config file document on readme
  • add http api and web shell


  1. find image docker is has, not has pull the image.
  2. find container name is has, not has return error.
  3. from customize image runs a new container in the container's namespaces (ipc, pid, network, etc, filesystem) with the STDIN stay open.
  4. create and run a exec on new container.
  5. Debug in the debug container.
  6. then waits for the debug container to exit and do the cleanup.

Reference & Thank

  1. kubectl-debug: docker-debug inspiration is from to this a kubectl debug tool.
  2. Docker核心技术与实现原理: docker-debug filesystem is from the blog.
  3. docker-engine-api-doc: docker engine api document.
You can’t perform that action at this time.