DOCKER-BUILDX-CREATE(1)

💖 docker-buildx-create — the manual, but make it slay 💖

okay bestie, welcome to DOCKER-BUILDX-CREATE(1), the page that teaches you how to spawn a whole new builder instance like it's nothing. no cap, this one's a banger. 🦋

---

✨ NAME ✨

docker-buildx-create — create a new builder instance. that's it, that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]

---

🎀 DESCRIPTION 🎀

so Create does exactly what it says on the tin: it makes a new builder instance that points at a Docker context or endpoint. and when we say context, we mean the name of a context — the kind you'd see in docker context ls. and when we say endpoint, we mean the address of a Docker socket, like, the DOCKER_HOST value. iykyk. 🫶

by default? the current Docker configuration is what gets used to figure out the context/endpoint value. so if you don't say anything, it just... knows. iconic.

now the important part: builder instances are isolated environments where builds can be invoked. little build bubbles. 🫧 and heads up — all Docker contexts also get the default builder instance. everyone gets one, it's a party. 🎉

---

✨ OPTIONS ✨

• --append[=false] — append a node to a builder instead of changing it. adding, not editing. 🍓
• --bootstrap[=false] — boot the builder right after creation. wake it up immediately, no waiting around.
• --buildkitd-config="" — BuildKit daemon config file.
• --buildkitd-flags="" — BuildKit daemon flags.
• --driver="" — driver to use. the available ones are: "docker-container", "kubernetes", "remote".
• --driver-opt=[] — options for the driver.
• -h, --help[=false] — help for create.
• --leave[=false] — remove a node from builder instead of changing it. bye bye node. 👋
• --name="" — builder instance name.
• --node="" — create/modify node with given name.
• --platform=[] — fixed platforms for current node.
• --use[=false] — set the current builder instance.

---

🦋 EXAMPLE 🦋

💫 Append a new node to an existing builder (--append) {#append}

the --append flag changes the action of the command so it appends a new node to an existing builder — the one you point at with --name. then Buildx will choose an appropriate node for a build based on the platforms it supports. matching energy, basically. ✨

$ docker buildx create mycontext1
eager_beaver

$ docker buildx create --name eager_beaver --append mycontext2
eager_beaver

💫 Specify a configuration file for the BuildKit daemon (--buildkitd-config) {#buildkitd-config}

--buildkitd-config FILE

this one specifies the configuration file for the BuildKit daemon to use. and psst — the configuration can be overridden by ⟨#buildkitd-flags⟩. 👀 there's an example BuildKit daemon configuration file over here ⟨https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md⟩ if you wanna peek.

if you don't specify a configuration file, Buildx goes looking for one by default in:

• $BUILDX_CONFIG/buildkitd.default.toml
• $DOCKER_CONFIG/buildx/buildkitd.default.toml
• ~/.docker/buildx/buildkitd.default.toml

also real talk: if you create a docker-container builder and you've specified certificates for registries in the buildkitd.toml configuration, those files will be copied into the container under /etc/buildkit/certs and the configuration will be updated to reflect that. the whole thing. 💖

💫 Specify options for the BuildKit daemon (--buildkitd-flags) {#buildkitd-flags}

--buildkitd-flags FLAGS

this adds flags when starting the BuildKit daemon. they take precedence over the configuration file specified by ⟨#buildkitd-config⟩ — so flags win, periodt. for the available flags, go check buildkitd --help.

--buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'

💫 BuildKit daemon network mode

you can specify the network mode for the BuildKit daemon either with the configuration file specified by ⟨#buildkitd-config⟩ using the worker.oci.networkMode option, or with the --oci-worker-net flag right here. the default value is auto, and it can be one of bridge, cni, host:

--buildkitd-flags '--oci-worker-net bridge'

Note 👑 Network mode "bridge" is supported since BuildKit v0.13 and will become the default in next v0.14. so like, get ready.

💫 Set the builder driver to use (--driver) {#driver}

--driver DRIVER

sets the builder driver to be used. a driver is a configuration of a BuildKit backend. Buildx supports the following drivers:

• docker (default)
• docker-container
• kubernetes
• remote

for more info about build drivers, see here ⟨/build/drivers/⟩. 🌈

🌟 docker driver

uses the builder that's built into the Docker daemon. with this driver, the ⟨/reference/cli/docker/buildx/build/#load⟩ flag is implied by default on buildx build. however — building multi-platform images or exporting cache is not currently supported. so no, not that. 😭

🌟 docker-container driver

uses a BuildKit container that will be spawned via Docker. with this driver, both building multi-platform images and exporting cache are supported. slay.

unlike the docker driver, built images will not automatically appear in docker images, and ⟨/reference/cli/docker/buildx/build/#load⟩ needs to be used to achieve that. just so you know. 💅

🌟 kubernetes driver

uses Kubernetes pods. with this driver, you can spin up pods with a defined BuildKit container image to build your images. very main character.

unlike the docker driver, built images will not automatically appear in docker images, and ⟨/reference/cli/docker/buildx/build/#load⟩ needs to be used to achieve that.

🌟 remote driver

uses a remote instance of BuildKit daemon over an arbitrary connection. with this driver, you manually create and manage instances of buildkit yourself, and configure buildx to point at it. it's giving DIY. 🛠️

unlike the docker driver, built images will not automatically appear in docker images, and ⟨/reference/cli/docker/buildx/build/#load⟩ needs to be used to achieve that.

💫 Set additional driver-specific options (--driver-opt) {#driver-opt}

--driver-opt OPTIONS

passes additional driver-specific options. for info about which driver options are actually available, go read the detailed documentation for the specific driver:

• ⟨/build/drivers/docker/⟩
• ⟨/build/drivers/docker-container/⟩
• ⟨/build/drivers/kubernetes/⟩
• ⟨/build/drivers/remote/⟩

💫 Remove a node from a builder (--leave) {#leave}

the --leave flag changes the action of the command to remove a node from a builder. the builder needs to be specified with --name, and the node that gets removed is set with --node. 🍃

$ docker buildx create --name mybuilder --node mybuilder0 --leave

💫 Specify the name of the builder (--name) {#name}

--name NAME

the --name flag specifies the name of the builder to be created or modified. if you don't specify one, one will be automatically generated for you. surprise! 🎁

💫 Specify the name of the node (--node) {#node}

--node NODE

the --node flag specifies the name of the node to be created or modified. if you don't give it a name, the node name defaults to the name of the builder it belongs to, with an index number suffix. cute little numbered babies. 🧚

💫 Set the platforms supported by the node (--platform) {#platform}

--platform PLATFORMS

the --platform flag sets the platforms the node supports. it expects a comma-separated list of platforms of the form OS/architecture/variant. the node will also automatically detect the platforms it supports — but manual values take priority over the detected ones, and they can be used when multiple nodes support building for the same platform. your call, your rules. 👑

$ docker buildx create --platform linux/amd64
$ docker buildx create --platform linux/arm64,linux/arm/v7

💫 Automatically switch to the newly created builder (--use) {#use}

the --use flag automatically switches the current builder to the newly created one. equivalent to running docker buildx use $(docker buildx create ...). ```

---

🔥 SEE ALSO 🔥

docker-buildx(1)

---

and that's the whole page, bestie 💜 huge thanks to the folks behind this one — this doc comes from Apr 2025, DOCKER-BUILDX-CREATE(1). go forth and create something gorgeous. 🌸✨🫶