tug: Multi-platform Docker rescue ship


tug streamlines Docker pipelines.

Spend less time managing buildx images. Enjoy more time developing your core application.


$ cd example

$ tug -t mcandre/tug-demo -exclude-arch mips64

$ tug -ls mcandre/tug-demo
Platform:  linux/386
Platform:  linux/amd64
Platform:  linux/amd64/v2

$ tug -t mcandre/tug-demo -load linux/amd64

$ docker run --rm mcandre/tug-demo cat /banner
Hello World!


Multi-platform images help developers serve users across more environments. For example, a developer working with Docker on a classic workstation (linux/amd64), with users consuming the image on a modern M1 Mac or Raspberry Pi (arm64). Multi-platform images are the glue that binds these necessary software components together in a working fashion.






$ go install github.com/mcandre/tug/cmd/[email protected]



For more information on developing tug itself, see DEVELOPMENT.md.




tug -get-platforms lists available platforms. Generally of the form linux/*.

tug -ls <name> lists any buildx cache entries present for the given image name, of the form name[:tag].

tug -t <name> builds multi-platform images into the buildx cache, of the form name[:tag].

  • -debug enables additional logging. In case of some buildx error.
  • -exclude-os <list> / -exclude-arch <list> skip the specified operating systems and/or architectures. For example, any platform variants unsupported by your FROM base image.
  • -load <platform> copies an image to the local Docker registry as a side effect of the build. By default, Docker does not copy any buildx images to the local Docker registry as witnessed by docker image, docker run, etc. Select an appropriate linux/<architecture> platform based on your host machine. Typically -load linux/amd64 for traditional hosts, or -load linux/arm64 for newer arm64 hosts.
  • -push uploads buildx cached images to the remote Docker registry, as a side effect of the image build process. This works around gaps in the buildx subsystem for conventional build, push workflows.
  • . or <directory> are optional trailing arguments for the Docker build directory. We default to the current working directory.

tug -clean empties the buildx image cache and removes the tug builder.

See tug -help for more detail.


Running tug itself within a Docker context, such as for CI/CD, would naturally require Docker-in-Docker privileges. See the relevant documentation for your particular cluster environment, such as Kubernetes.


Docker Hub provides an exceptional variety of base images, everything from Debian to Ubuntu to RHEL to glibc to musl to uClibC. If your base image lacks support for a particular platform, try searching for alternative base images. Or, build a new base image from scratch and publish it back to Docker Hub! The more we refine our base images, the easier it is to extend and use them.


  • factorio ports Go applications.
  • gox, an older Go cross-compiler wrapper.
  • LLVM bitcode offers an abstract assembler format for C/C++ code.
  • snek ports native C/C++ applications.
  • tonixxx ports applications of any programming language.
  • WASM provides a portable interface for C/C++ code.
  • xgo supports Go projects with native cgo dependencies.


View Github