github.com/pdmccormick/importable-docker-buildx@v0.0.0-20240426161518-e47091289030/README.md (about) 1 # buildx 2 3 [![GitHub release](https://img.shields.io/github/release/docker/buildx.svg?style=flat-square)](https://github.com/docker/buildx/releases/latest) 4 [![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?style=flat-square&logo=go&logoColor=white)](https://pkg.go.dev/github.com/docker/buildx) 5 [![Build Status](https://img.shields.io/github/actions/workflow/status/docker/buildx/build.yml?branch=master&label=build&logo=github&style=flat-square)](https://github.com/docker/buildx/actions?query=workflow%3Abuild) 6 [![Go Report Card](https://goreportcard.com/badge/github.com/docker/buildx?style=flat-square)](https://goreportcard.com/report/github.com/docker/buildx) 7 [![codecov](https://img.shields.io/codecov/c/github/docker/buildx?logo=codecov&style=flat-square)](https://codecov.io/gh/docker/buildx) 8 9 `buildx` is a Docker CLI plugin for extended build capabilities with 10 [BuildKit](https://github.com/moby/buildkit). 11 12 Key features: 13 14 - Familiar UI from `docker build` 15 - Full BuildKit capabilities with container driver 16 - Multiple builder instance support 17 - Multi-node builds for cross-platform images 18 - Compose build support 19 - High-level build constructs (`bake`) 20 - In-container driver support (both Docker and Kubernetes) 21 22 # Table of Contents 23 24 - [Installing](#installing) 25 - [Windows and macOS](#windows-and-macos) 26 - [Linux packages](#linux-packages) 27 - [Manual download](#manual-download) 28 - [Dockerfile](#dockerfile) 29 - [Set buildx as the default builder](#set-buildx-as-the-default-builder) 30 - [Building](#building) 31 - [Getting started](#getting-started) 32 - [Building with buildx](#building-with-buildx) 33 - [Working with builder instances](#working-with-builder-instances) 34 - [Building multi-platform images](#building-multi-platform-images) 35 - [Reference](docs/reference/buildx.md) 36 - [`buildx bake`](docs/reference/buildx_bake.md) 37 - [`buildx build`](docs/reference/buildx_build.md) 38 - [`buildx create`](docs/reference/buildx_create.md) 39 - [`buildx du`](docs/reference/buildx_du.md) 40 - [`buildx imagetools`](docs/reference/buildx_imagetools.md) 41 - [`buildx imagetools create`](docs/reference/buildx_imagetools_create.md) 42 - [`buildx imagetools inspect`](docs/reference/buildx_imagetools_inspect.md) 43 - [`buildx inspect`](docs/reference/buildx_inspect.md) 44 - [`buildx ls`](docs/reference/buildx_ls.md) 45 - [`buildx prune`](docs/reference/buildx_prune.md) 46 - [`buildx rm`](docs/reference/buildx_rm.md) 47 - [`buildx stop`](docs/reference/buildx_stop.md) 48 - [`buildx use`](docs/reference/buildx_use.md) 49 - [`buildx version`](docs/reference/buildx_version.md) 50 - [Contributing](#contributing) 51 52 For more information on how to use Buildx, see 53 [Docker Build docs](https://docs.docker.com/build/). 54 55 # Installing 56 57 Using `buildx` with Docker requires Docker engine 19.03 or newer. 58 59 > **Warning** 60 > 61 > Using an incompatible version of Docker may result in unexpected behavior, 62 > and will likely cause issues, especially when using Buildx builders with more 63 > recent versions of BuildKit. 64 65 ## Windows and macOS 66 67 Docker Buildx is included in [Docker Desktop](https://docs.docker.com/desktop/) 68 for Windows and macOS. 69 70 ## Linux packages 71 72 Docker Engine package repositories contain Docker Buildx packages when installed according to the 73 [Docker Engine install documentation](https://docs.docker.com/engine/install/). Install the 74 `docker-buildx-plugin` package to install the Buildx plugin. 75 76 ## Manual download 77 78 > **Important** 79 > 80 > This section is for unattended installation of the buildx component. These 81 > instructions are mostly suitable for testing purposes. We do not recommend 82 > installing buildx using manual download in production environments as they 83 > will not be updated automatically with security updates. 84 > 85 > On Windows and macOS, we recommend that you install [Docker Desktop](https://docs.docker.com/desktop/) 86 > instead. For Linux, we recommend that you follow the [instructions specific for your distribution](#linux-packages). 87 88 You can also download the latest binary from the [GitHub releases page](https://github.com/docker/buildx/releases/latest). 89 90 Rename the relevant binary and copy it to the destination matching your OS: 91 92 | OS | Binary name | Destination folder | 93 | -------- | -------------------- | -----------------------------------------| 94 | Linux | `docker-buildx` | `$HOME/.docker/cli-plugins` | 95 | macOS | `docker-buildx` | `$HOME/.docker/cli-plugins` | 96 | Windows | `docker-buildx.exe` | `%USERPROFILE%\.docker\cli-plugins` | 97 98 Or copy it into one of these folders for installing it system-wide. 99 100 On Unix environments: 101 102 * `/usr/local/lib/docker/cli-plugins` OR `/usr/local/libexec/docker/cli-plugins` 103 * `/usr/lib/docker/cli-plugins` OR `/usr/libexec/docker/cli-plugins` 104 105 On Windows: 106 107 * `C:\ProgramData\Docker\cli-plugins` 108 * `C:\Program Files\Docker\cli-plugins` 109 110 > **Note** 111 > 112 > On Unix environments, it may also be necessary to make it executable with `chmod +x`: 113 > ```shell 114 > $ chmod +x ~/.docker/cli-plugins/docker-buildx 115 > ``` 116 117 ## Dockerfile 118 119 Here is how to install and use Buildx inside a Dockerfile through the 120 [`docker/buildx-bin`](https://hub.docker.com/r/docker/buildx-bin) image: 121 122 ```dockerfile 123 # syntax=docker/dockerfile:1 124 FROM docker 125 COPY --from=docker/buildx-bin /buildx /usr/libexec/docker/cli-plugins/docker-buildx 126 RUN docker buildx version 127 ``` 128 129 # Set buildx as the default builder 130 131 Running the command [`docker buildx install`](docs/reference/buildx_install.md) 132 sets up docker builder command as an alias to `docker buildx build`. This 133 results in the ability to have `docker build` use the current buildx builder. 134 135 To remove this alias, run [`docker buildx uninstall`](docs/reference/buildx_uninstall.md). 136 137 # Building 138 139 ```console 140 # Buildx 0.6+ 141 $ docker buildx bake "https://github.com/docker/buildx.git" 142 $ mkdir -p ~/.docker/cli-plugins 143 $ mv ./bin/build/buildx ~/.docker/cli-plugins/docker-buildx 144 145 # Docker 19.03+ 146 $ DOCKER_BUILDKIT=1 docker build --platform=local -o . "https://github.com/docker/buildx.git" 147 $ mkdir -p ~/.docker/cli-plugins 148 $ mv buildx ~/.docker/cli-plugins/docker-buildx 149 150 # Local 151 $ git clone https://github.com/docker/buildx.git && cd buildx 152 $ make install 153 ``` 154 155 # Getting started 156 157 ## Building with buildx 158 159 Buildx is a Docker CLI plugin that extends the `docker build` command with the 160 full support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit) 161 builder toolkit. It provides the same user experience as `docker build` with 162 many new features like creating scoped builder instances and building against 163 multiple nodes concurrently. 164 165 After installation, buildx can be accessed through the `docker buildx` command 166 with Docker 19.03. `docker buildx build` is the command for starting a new 167 build. With Docker versions older than 19.03 buildx binary can be called 168 directly to access the `docker buildx` subcommands. 169 170 ```console 171 $ docker buildx build . 172 [+] Building 8.4s (23/32) 173 => ... 174 ``` 175 176 Buildx will always build using the BuildKit engine and does not require 177 `DOCKER_BUILDKIT=1` environment variable for starting builds. 178 179 The `docker buildx build` command supports features available for `docker build`, 180 including features such as outputs configuration, inline build caching, and 181 specifying target platform. In addition, Buildx also supports new features that 182 are not yet available for regular `docker build` like building manifest lists, 183 distributed caching, and exporting build results to OCI image tarballs. 184 185 Buildx is flexible and can be run in different configurations that are exposed 186 through various "drivers". Each driver defines how and where a build should 187 run, and have different feature sets. 188 189 We currently support the following drivers: 190 - The `docker` driver ([guide](https://docs.docker.com/build/drivers/docker/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) 191 - The `docker-container` driver ([guide](https://docs.docker.com/build/drivers/docker-container/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) 192 - The `kubernetes` driver ([guide](https://docs.docker.com/build/drivers/kubernetes/), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) 193 - The `remote` driver ([guide](https://docs.docker.com/build/drivers/remote/)) 194 195 For more information on drivers, see the [drivers guide](https://docs.docker.com/build/drivers/). 196 197 ## Working with builder instances 198 199 By default, buildx will initially use the `docker` driver if it is supported, 200 providing a very similar user experience to the native `docker build`. Note that 201 you must use a local shared daemon to build your applications. 202 203 Buildx allows you to create new instances of isolated builders. This can be 204 used for getting a scoped environment for your CI builds that does not change 205 the state of the shared daemon or for isolating the builds for different 206 projects. You can create a new instance for a set of remote nodes, forming a 207 build farm, and quickly switch between them. 208 209 You can create new instances using the [`docker buildx create`](docs/reference/buildx_create.md) 210 command. This creates a new builder instance with a single node based on your 211 current configuration. 212 213 To use a remote node you can specify the `DOCKER_HOST` or the remote context name 214 while creating the new builder. After creating a new instance, you can manage its 215 lifecycle using the [`docker buildx inspect`](docs/reference/buildx_inspect.md), 216 [`docker buildx stop`](docs/reference/buildx_stop.md), and 217 [`docker buildx rm`](docs/reference/buildx_rm.md) commands. To list all 218 available builders, use [`buildx ls`](docs/reference/buildx_ls.md). After 219 creating a new builder you can also append new nodes to it. 220 221 To switch between different builders, use [`docker buildx use <name>`](docs/reference/buildx_use.md). 222 After running this command, the build commands will automatically use this 223 builder. 224 225 Docker also features a [`docker context`](https://docs.docker.com/engine/reference/commandline/context/) 226 command that can be used for giving names for remote Docker API endpoints. 227 Buildx integrates with `docker context` so that all of your contexts 228 automatically get a default builder instance. While creating a new builder 229 instance or when adding a node to it you can also set the context name as the 230 target. 231 232 ## Building multi-platform images 233 234 BuildKit is designed to work well for building for multiple platforms and not 235 only for the architecture and operating system that the user invoking the build 236 happens to run. 237 238 When you invoke a build, you can set the `--platform` flag to specify the target 239 platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or 240 `darwin/amd64`). 241 242 When the current builder instance is backed by the `docker-container` or 243 `kubernetes` driver, you can specify multiple platforms together. In this case, 244 it builds a manifest list which contains images for all specified architectures. 245 When you use this image in [`docker run`](https://docs.docker.com/engine/reference/commandline/run/) 246 or [`docker service`](https://docs.docker.com/engine/reference/commandline/service/), 247 Docker picks the correct image based on the node's platform. 248 249 You can build multi-platform images using three different strategies that are 250 supported by Buildx and Dockerfiles: 251 252 1. Using the QEMU emulation support in the kernel 253 2. Building on multiple native nodes using the same builder instance 254 3. Using a stage in Dockerfile to cross-compile to different architectures 255 256 QEMU is the easiest way to get started if your node already supports it (for 257 example. if you are using Docker Desktop). It requires no changes to your 258 Dockerfile and BuildKit automatically detects the secondary architectures that 259 are available. When BuildKit needs to run a binary for a different architecture, 260 it automatically loads it through a binary registered in the `binfmt_misc` 261 handler. 262 263 For QEMU binaries registered with `binfmt_misc` on the host OS to work 264 transparently inside containers they must be registered with the `fix_binary` 265 flag. This requires a kernel >= 4.8 and binfmt-support >= 2.1.7. You can check 266 for proper registration by checking if `F` is among the flags in 267 `/proc/sys/fs/binfmt_misc/qemu-*`. While Docker Desktop comes preconfigured 268 with `binfmt_misc` support for additional platforms, for other installations 269 it likely needs to be installed using [`tonistiigi/binfmt`](https://github.com/tonistiigi/binfmt) 270 image. 271 272 ```console 273 $ docker run --privileged --rm tonistiigi/binfmt --install all 274 ``` 275 276 Using multiple native nodes provide better support for more complicated cases 277 that are not handled by QEMU and generally have better performance. You can 278 add additional nodes to the builder instance using the `--append` flag. 279 280 Assuming contexts `node-amd64` and `node-arm64` exist in `docker context ls`; 281 282 ```console 283 $ docker buildx create --use --name mybuild node-amd64 284 mybuild 285 $ docker buildx create --append --name mybuild node-arm64 286 $ docker buildx build --platform linux/amd64,linux/arm64 . 287 ``` 288 289 Finally, depending on your project, the language that you use may have good 290 support for cross-compilation. In that case, multi-stage builds in Dockerfiles 291 can be effectively used to build binaries for the platform specified with 292 `--platform` using the native architecture of the build node. A list of build 293 arguments like `BUILDPLATFORM` and `TARGETPLATFORM` is available automatically 294 inside your Dockerfile and can be leveraged by the processes running as part 295 of your build. 296 297 ```dockerfile 298 # syntax=docker/dockerfile:1 299 FROM --platform=$BUILDPLATFORM golang:alpine AS build 300 ARG TARGETPLATFORM 301 ARG BUILDPLATFORM 302 RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log 303 FROM alpine 304 COPY --from=build /log /log 305 ``` 306 307 You can also use [`tonistiigi/xx`](https://github.com/tonistiigi/xx) Dockerfile 308 cross-compilation helpers for more advanced use-cases. 309 310 ## High-level build options 311 312 See [High-level builds with Bake](https://docs.docker.com/build/bake/) for more details. 313 314 # Contributing 315 316 Want to contribute to Buildx? Awesome! You can find information about 317 contributing to this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)