BuildAdvanced

Docker Bake Cheatsheet

Define complex multi-target build pipelines with HCL or JSON bake files and build matrices.

What it is

Docker Bake is a high-level build orchestration tool that lets you define multiple build targets, their contexts, tags, platforms, and cache settings in a single HCL, JSON, or Compose file — and build them in parallel.

Installation

Bake is part of docker buildx. Run docker buildx bake --help to verify.

Quick start

docker buildx bake

Build all default targets from docker-bake.hcl.

docker buildx bake api

Build a specific target.

docker buildx bake --print

Preview the resolved bake config without building.

HCL reference

Block / Field	Example	Description
`group`	`group "default" { targets=["api","web"] }`	A collection of targets to build together.
`target`	`target "api" { ... }`	Defines a single build target.
`context`	`context = "./api"`	Build context path.
`tags`	`tags = ["me/api:dev"]`	Image tags to apply.
`platforms`	`platforms = ["linux/amd64","linux/arm64"]`	Target platforms for multi-arch builds.
`args`	`args = { NODE_VERSION = "20" }`	Build arguments.
`matrix`	`matrix = { VERSION = ["3.9","3.11"] }`	Build across a matrix of values.

Real-world examples

Multi-service bake file

group "default" { targets = ["api", "web"] }

target "api" {
  context  = "./api"
  tags     = ["me/api:dev"]
  platforms = ["linux/amd64", "linux/arm64"]
}

target "web" {
  context = "./web"
  tags    = ["me/web:dev"]
  args    = { NEXT_PUBLIC_API = "http://api:3000" }
}

Matrix build for multiple Python versions

target "python" {
  matrix   = { VERSION = ["3.10", "3.11", "3.12"] }
  name     = "python-${VERSION}"
  tags     = ["me/python:${VERSION}"]
  args     = { PYTHON_VERSION = VERSION }
}

Best practices

Use groups to organize targets and enable selective builds per environment.
Wire up cache-from/cache-to for all targets in CI to speed up builds.
Use --print to debug bake files before running actual builds.

Related cheatsheets

Last reviewed: 2026-06-15