# Docker Bake (https://depot.dev/docs/container-builds/how-to-guides/docker-bake)

Building multiple Docker images that share common dependencies? Need to build all your services at once? `depot bake` lets you build multiple images in parallel from a single file, dramatically speeding up your builds while taking advantage of shared work between images.

## Why use bake?

Traditional approaches to building multiple images often involve sequential builds using tools like `make` or shell scripts. This means waiting for each image to complete before starting the next one, and rebuilding shared dependencies multiple times.

With `depot bake`, you can:

* Build all images in parallel on dedicated BuildKit builders
* Automatically deduplicate shared work across images
* Define all your builds in a single HCL, JSON, or Docker Compose file
* Get native Intel and Arm builds without emulation
* Leverage persistent caching across all your builds

## How to use depot bake

### Basic usage

By default, `depot bake` looks for these files in your project root:

* `compose.yaml`, `compose.yml`, `docker-compose.yml`, `docker-compose.yaml`
* `docker-bake.json`, `docker-bake.override.json`
* `docker-bake.hcl`, `docker-bake.override.hcl`

Run bake with no arguments to build the default group or all services:

```shell
depot bake
```

### Specifying a bake file

Use the `-f` flag to specify a custom bake file:

```shell
depot bake -f my-bake-file.hcl
```

### Building specific targets

Build only specific targets instead of all:

```shell
depot bake app db
```

## HCL bake file format

HCL is the recommended format for bake files as it provides the most features and flexibility.

### Basic example

```hcl
group "default" {
  targets = ["app", "db", "cron"]
}

target "app" {
  dockerfile = "Dockerfile.app"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/app:latest"]
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/db:latest"]
}

target "cron" {
  dockerfile = "Dockerfile.cron"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/cron:latest"]
}
```

You can think of each `target` as a Docker build command, where you specify the Dockerfile, platforms, and tags for the image. These targets can be grouped together in a `group` to build them all at once.

Our optimized instances of BuildKit will build these images in parallel, automatically deduplicating work across targets.

### Using variables

Make your bake files more flexible with variables:

```hcl
variable "TAG" {
  default = "latest"
}

variable "REGISTRY" {
  default = "myrepo"
}

target "app" {
  dockerfile = "Dockerfile.app"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["${REGISTRY}/app:${TAG}"]
}
```

Override variables from the command line:

```shell
TAG=v1.0.0 REGISTRY=mycompany depot bake
```

### Sharing base images

Use `contexts` to specify dependencies between targets in a bake file. A common use of this is to highlight that targets share a base image, so you can deduplicate work by only building that base image once:

```hcl
target "base" {
  dockerfile = "Dockerfile.base"
  platforms = ["linux/amd64", "linux/arm64"]
}

target "app" {
  contexts = {
    base = "target:base"
  }
  dockerfile = "Dockerfile.app"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/app:latest"]
}

target "worker" {
  contexts = {
    base = "target:base"
  }
  dockerfile = "Dockerfile.worker"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/worker:latest"]
}
```

In your Dockerfiles, reference the base context:

```dockerfile
# Dockerfile.app
FROM base
# ... rest of your app Dockerfile
```

### Matrix builds

You can use the matrix key to parameterize a single target to build images for different inputs. This can be helpful if you have a lot of similarities between targets in your bake file.

```hcl
target "service" {
  name = "service-${item}"
  matrix = {
    item = ["frontend", "backend", "api"]
  }
  dockerfile = "Dockerfile.${item}"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/${item}:latest"]
}
```

**Note: The name property is required when using the matrix property to create the unique image build for each value in the matrix.**

## Docker Compose bake format

You can use your existing Docker Compose files as a bake file. There are limitations compared to HCL, like not supporting `inherits` or variable blocks. But it's a great way to build all of your services in parallel without needing to rewrite your existing Compose files.

```yaml
services:
  app:
    build:
      dockerfile: Dockerfile.app
      platforms:
        - linux/amd64
        - linux/arm64
    image: myrepo/app:latest

  db:
    build:
      dockerfile: Dockerfile.db
      platforms:
        - linux/amd64
        - linux/arm64
    image: myrepo/db:latest

  worker:
    build:
      dockerfile: Dockerfile.worker
      platforms:
        - linux/amd64
        - linux/arm64
    image: myrepo/worker:latest
```

Build all services defined in the Docker Compose file with:

```shell
depot bake -f docker-compose.yml
```

## Advanced features

### Using multiple Depot projects in a bake file

In some cases you may want to shard your container builds out across different Depot projects so you can have the full BuildKit host dedicated to the build. For compose, you can specify different Depot projects per service.

```yaml
services:
  frontend:
    build:
      dockerfile: ./Dockerfile.frontend
      x-depot:
        project-id: project-id-1
  backend:
    build:
      dockerfile: ./Dockerfile.backend
      x-depot:
        project-id: project-id-2
```

You can also specify the project ID in HCL for each `target`:

```hcl
target "app" {
  dockerfile = "Dockerfile.app"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/app:latest"]
  project_id = "project-id-1"
}

target "db" {
  dockerfile = "Dockerfile.db"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/db:latest"]
  project_id = "project-id-2"
}

target "worker" {
  dockerfile = "Dockerfile.worker"
  platforms = ["linux/amd64", "linux/arm64"]
  tags = ["myrepo/worker:latest"]
  project_id = "project-id-3"
}
```

**Note:** When you use the `depot/bake-action` in a GitHub Actions workflow, the `x-depot.project-id` in your Docker Compose file or `project_id` in your HCL bake file take precedence over the `project` input in the action configuration.

### Understanding bake and autoscaling

A `depot bake` command is submitted as a single build request to BuildKit, regardless of how many targets are defined in the bake file. This has important implications for [build autoscaling](/docs/container-builds/how-to-guides/autoscaling):

* For autoscaling purposes, one `depot bake` command counts as one build, not multiple builds
* For example, if your project has Autoscaling enabled with a value of `2` builds per instance, two concurrent `depot bake` commands will run on the same builder, but a third concurrent `depot bake` command will trigger the provisioning of a new builder
* The number of targets inside a bake file has no impact on the autoscaling count

**Splitting bake builds across projects**: You can specify different project IDs (as shown in the section above) to split a single bake into multiple builds (one per project). However, the number of targets inside the bake for each project has no impact on autoscaling. Each `depot bake` command for each project still counts as a single build.

### Loading images locally

Load specific targets to your local Docker daemon by including the target name after the load flag:

```shell
depot bake --load app
```

This only loads the specified target, not all targets in the bake file.

### Using the Depot Registry with bake

You can save built images to the [Depot Registry](/docs/registry/overview) for later use:

```shell
depot bake --save --metadata-file=build.json
```

If you want to specify a specific tag for the images being stored in the registry, you can do so by using the `--save-tag` flag:

```shell
depot bake --save --save-tag myrepo/app:v1.0.0
```

You can pull specific targets out of the Depot Registry later using the [`depot pull`](/docs/cli/reference/container-builds#depot-pull) command:

```shell
depot pull --project <project-id> --target app,db <build-id>
```

Or push to your registry after tests pass:

```shell
depot push --project <project-id> --target app \
  --tag myregistry/app:v1.0.0 <build-id>
```

### Passing build arguments (i.e. `--build-arg`) to a target

You can pass build arguments to your targets in the bake file using the `args` block. This is useful for passing environment variables or other configuration options to your Docker builds.

```hcl
target "app" {
  args = {
    NODE_VERSION = "18"
    ENV = "production"
  }
}
```

## GitHub Actions integration

You can use the [`depot/bake-action`](https://github.com/depot/bake-action) in your GitHub Actions workflows to leverage `depot bake` for building your bake files with our [Docker build service](/products/container-builds):

```yaml
name: Build images
on: push

jobs:
  bake:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: depot/setup-action@v1
      - uses: depot/bake-action@v1
        with:
          file: docker-bake.hcl
          push: true
```

## Tips and best practices

1. **Use groups** to organize related targets and build them together
2. **Leverage inheritance** with `inherits` to reduce duplication
3. **Use contexts** for shared base images to maximize deduplication
4. **Set platforms explicitly** to ensure consistent multi-platform builds
5. **Use variables** for configuration that changes between environments
6. **Use multiple Depot projects** to shard builds across different BuildKit hosts for resource intensive builds
7. **Save to ephemeral registry** in CI to build once and push after tests

## Next steps

* Learn more about [BuildKit parallelization](/blog/buildkit-in-depth)
* Explore the [full bake syntax reference](/blog/buildx-bake-deep-dive)
* Check out how to get faster container builds with [`depot/bake-action`](/docs/container-builds/integrations/github-actions)

## For AI Agents

The full site index is at [llms.txt](https://depot.dev/llms.txt). Append `.md` to any documentation, blog, changelog, or customer URL to fetch its markdown source directly.