concurrent, cache-efficient, and Dockerfile-agnostic builder toolkit
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
api ontrol: support calling automatic GC Sep 5, 2018
cache Merge pull request #631 from jhowardmsft/boltdb Sep 19, 2018
client Merge pull request #623 from tonistiigi/failfast Sep 17, 2018
cmd Merge pull request #631 from jhowardmsft/boltdb Sep 19, 2018
control update Go to 1.11 Sep 15, 2018
docs Revendoring to move boltdb to bbolt Sep 18, 2018
examples Merge pull request #623 from tonistiigi/failfast Sep 17, 2018
executor runcexecutor: revert forwardio Sep 12, 2018
exporter resolver: add config support for mirrors/plainhttp Sep 8, 2018
frontend Merge pull request #629 from tonistiigi/df-output-fix Sep 17, 2018
hack hack: update buildkit dockerfiles to go1.11 Sep 17, 2018
identity identity: add pkg for random id generation Jun 19, 2017
session sshprovider: allow keys from local files Sep 10, 2018
snapshot Revendoring to move boltdb to bbolt Sep 18, 2018
solver Merge pull request #631 from jhowardmsft/boltdb Sep 19, 2018
source Revendoring to move boltdb to bbolt Sep 18, 2018
util resolver: add config support for mirrors/plainhttp Sep 8, 2018
vendor Revendoring to move boltdb to bbolt Sep 18, 2018
version hack: embed git revison into binaries May 21, 2018
worker Merge pull request #631 from jhowardmsft/boltdb Sep 19, 2018
.dockerignore hack: embed git revison into binaries May 21, 2018
.gitignore hack: embed git revison into binaries May 21, 2018
.travis.yml travis: use the default version of Docker Engine (17.09) Dec 20, 2017
LICENSE Add license Jun 1, 2017
Makefile update Go to 1.11 Sep 15, 2018 update containerd (binary: v1.1.3, library: Aug 23, 2018) Aug 23, 2018
doc.go Add a go file on buildkit root folder Oct 26, 2017
gometalinter.json Add deadcode to the linter Feb 2, 2018
vendor.conf Revendoring to move boltdb to bbolt Sep 18, 2018

asciicinema example


GoDoc Build Status Go Report Card

BuildKit is a toolkit for converting source code to build artifacts in an efficient, expressive and repeatable manner.

Key features:

  • Automatic garbage collection
  • Extendable frontend formats
  • Concurrent dependency resolution
  • Efficient instruction caching
  • Build cache import/export
  • Nested build job invocations
  • Distributable workers
  • Multiple output formats
  • Pluggable architecture
  • Execution without root privileges

Read the proposal from

Introductory blog post

Used by



OpenFaaS Cloud

container build interface

Quick start


The following command installs buildkitd and buildctl to /usr/local/bin:

$ make && sudo make install

You can also use make binaries-all to prepare buildkitd.containerd_only and buildkitd.oci_only.

Starting the buildkitd daemon:

buildkitd --debug --root /var/lib/buildkit

The buildkitd daemon supports two worker backends: OCI (runc) and containerd.

By default, the OCI (runc) worker is used. You can set --oci-worker=false --containerd-worker=true to use the containerd worker.

We are open to adding more backends.

Exploring LLB

BuildKit builds are based on a binary intermediate format called LLB that is used for defining the dependency graph for processes running part of your build. tl;dr: LLB is to Dockerfile what LLVM IR is to C.

  • Marshaled as Protobuf messages
  • Concurrently executable
  • Efficiently cacheable
  • Vendor-neutral (i.e. non-Dockerfile languages can be easily implemented)

See solver/pb/ops.proto for the format definition.

Currently, following high-level languages has been implemented for LLB:

For understanding the basics of LLB, examples/buildkit* directory contains scripts that define how to build different configurations of BuildKit itself and its dependencies using the client package. Running one of these scripts generates a protobuf definition of a build graph. Note that the script itself does not execute any steps of the build.

You can use buildctl debug dump-llb to see what data is in this definition. Add --dot to generate dot layout.

go run examples/buildkit0/buildkit.go | buildctl debug dump-llb | jq .

To start building use buildctl build command. The example script accepts --with-containerd flag to choose if containerd binaries and support should be included in the end result as well.

go run examples/buildkit0/buildkit.go | buildctl build

buildctl build will show interactive progress bar by default while the build job is running. It will also show you the path to the trace file that contains all information about the timing of the individual steps and logs.

Different versions of the example scripts show different ways of describing the build definition for this project to show the capabilities of the library. New versions have been added when new features have become available.

  • ./examples/buildkit0 - uses only exec operations, defines a full stage per component.
  • ./examples/buildkit1 - cloning git repositories has been separated for extra concurrency.
  • ./examples/buildkit2 - uses git sources directly instead of running git clone, allowing better performance and much safer caching.
  • ./examples/buildkit3 - allows using local source files for separate components eg. ./buildkit3 --runc=local | buildctl build --local runc-src=some/local/path
  • ./examples/dockerfile2llb - can be used to convert a Dockerfile to LLB for debugging purposes
  • ./examples/gobuild - shows how to use nested invocation to generate LLB for Go package internal dependencies

Exploring Dockerfiles

Frontends are components that run inside BuildKit and convert any build definition to LLB. There is a special frontend called gateway (gateway.v0) that allows using any image as a frontend.

During development, Dockerfile frontend (dockerfile.v0) is also part of the BuildKit repo. In the future, this will be moved out, and Dockerfiles can be built using an external image.

Building a Dockerfile with buildctl
buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=.
buildctl build --frontend=dockerfile.v0 --local context=. --local dockerfile=. --frontend-opt target=foo --frontend-opt build-arg:foo=bar

--local exposes local source files from client to the builder. context and dockerfile are the names Dockerfile frontend looks for build context and Dockerfile location.

build-using-dockerfile utility

For people familiar with docker build command, there is an example wrapper utility in ./examples/build-using-dockerfile that allows building Dockerfiles with BuildKit using a syntax similar to docker build.

go build ./examples/build-using-dockerfile && sudo install build-using-dockerfile /usr/local/bin

build-using-dockerfile -t myimage .
build-using-dockerfile -t mybuildkit -f ./hack/dockerfiles/test.Dockerfile .

# build-using-dockerfile will automatically load the resulting image to Docker
docker inspect myimage
Building a Dockerfile using external frontend:

During development, an external version of the Dockerfile frontend is pushed to that can be used with the gateway frontend. The source for the external frontend is currently located in ./frontend/dockerfile/cmd/dockerfile-frontend but will move out of this repository in the future (#163). For automatic build from master branch of this repository tonistiigi/dockerfile:master image can be used.

buildctl build --frontend=gateway.v0 --frontend-opt=source=tonistiigi/dockerfile --local context=. --local dockerfile=.
buildctl build --frontend gateway.v0 --frontend-opt=source=tonistiigi/dockerfile --frontend-opt=context=git:// --frontend-opt


By default, the build result and intermediate cache will only remain internally in BuildKit. Exporter needs to be specified to retrieve the result.

Exporting resulting image to containerd

The containerd worker needs to be used

buildctl build ... --exporter=image --exporter-opt
ctr --namespace=buildkit images ls
Push resulting image to registry
buildctl build ... --exporter=image --exporter-opt --exporter-opt push=true

If credentials are required, buildctl will attempt to read Docker configuration file.

Exporting build result back to client

The local client will copy the files directly to the client. This is useful if BuildKit is being used for building something else than container images.

buildctl build ... --exporter=local --exporter-opt output=path/to/output-dir
Exporting built image to Docker
# exported tarball is also compatible with OCI spec
buildctl build ... --exporter=docker --exporter-opt name=myimage | docker load
Exporting OCI Image Format tarball to client
buildctl build ... --exporter=oci --exporter-opt output=path/to/output.tar
buildctl build ... --exporter=oci > output.tar


View build cache

buildctl du -v

Show enabled workers

buildctl debug workers -v

Running containerized buildkit

BuildKit can also be used by running the buildkitd daemon inside a Docker container and accessing it remotely. The client tool buildctl is also available for Mac and Windows.

To run daemon in a container:

docker run -d --privileged -p 1234:1234 tonistiigi/buildkit --addr tcp://
export BUILDKIT_HOST=tcp://
buildctl build --help

The tonistiigi/buildkit image can be built locally using the Dockerfile in ./hack/dockerfiles/test.Dockerfile.

Opentracing support

BuildKit supports opentracing for buildkitd gRPC API and buildctl commands. To capture the trace to Jaeger, set JAEGER_TRACE environment variable to the collection address.

docker run -d -p6831:6831/udp -p16686:16686 jaegertracing/all-in-one:latest
# restart buildkitd and buildctl so they know JAEGER_TRACE
# any buildctl command should be traced to

Supported runc version

During development, BuildKit is tested with the version of runc that is being used by the containerd repository. Please refer to for more information.

Running BuildKit without root privileges

Please refer to docs/


Running tests:

make test

This runs all unit and integration tests in a containerized environment. Locally, every package can be tested separately with standard Go tools, but integration tests are skipped if local user doesn't have enough permissions or worker binaries are not installed.

# test a specific package only
make test TESTPKGS=./client

# run a specific test with all worker combinations
make test TESTPKGS=./client TESTFLAGS="--run /TestCallDiskUsage -v" 

# run all integration tests with a specific worker
# supported workers: oci, oci-rootless, containerd, containerd-1.0
make test TESTPKGS=./client TESTFLAGS="--run //worker=containerd -v" 

Updating vendored dependencies:

# update vendor.conf
make vendor

Validating your updates before submission:

make validate-all