command: docker buildx create
short: Create a new builder instance
long: |-
    Create makes a new builder instance pointing to a Docker context or endpoint,
    where context is the name of a context from `docker context ls` and endpoint is
    the address for Docker socket (eg. `DOCKER_HOST` value).

    By default, the current Docker configuration is used for determining the
    context/endpoint value.

    Builder instances are isolated environments where builds can be invoked. All
    Docker contexts also get the default builder instance.
usage: docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]
pname: docker buildx
plink: docker_buildx.yaml
options:
    - option: append
      value_type: bool
      default_value: "false"
      description: Append a node to builder instead of changing it
      details_url: '#append'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: bootstrap
      value_type: bool
      default_value: "false"
      description: Boot builder after creation
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: builder
      value_type: string
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: buildkitd-config
      value_type: string
      description: BuildKit daemon config file
      details_url: '#buildkitd-config'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: buildkitd-flags
      value_type: string
      description: BuildKit daemon flags
      details_url: '#buildkitd-flags'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: config
      value_type: string
      description: BuildKit daemon config file
      deprecated: false
      hidden: true
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: driver
      value_type: string
      description: |
        Driver to use (available: `cloud`, `docker-container`, `kubernetes`, `remote`)
      details_url: '#driver'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: driver-opt
      value_type: stringArray
      default_value: '[]'
      description: Options for the driver
      details_url: '#driver-opt'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: leave
      value_type: bool
      default_value: "false"
      description: Remove a node from builder instead of changing it
      details_url: '#leave'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: name
      value_type: string
      description: Builder instance name
      details_url: '#name'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: node
      value_type: string
      description: Create/modify node with given name
      details_url: '#node'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: platform
      value_type: stringArray
      default_value: '[]'
      description: Fixed platforms for current node
      details_url: '#platform'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: timeout
      value_type: duration
      default_value: 20s
      description: Override the default timeout for loading builder status
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
    - option: use
      value_type: bool
      default_value: "false"
      description: Set the current builder instance
      details_url: '#use'
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
inherited_options:
    - option: debug
      shorthand: D
      value_type: bool
      default_value: "false"
      description: Enable debug logging
      deprecated: false
      hidden: false
      experimental: false
      experimentalcli: false
      kubernetes: false
      swarm: false
examples: |-
    ### Append a new node to an existing builder (--append) {#append}

    The `--append` flag changes the action of the command to append a new node to an
    existing builder specified by `--name`. Buildx will choose an appropriate node
    for a build based on the platforms it supports.

    ```console
    $ 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}

    ```text
    --buildkitd-config FILE
    ```

    Specifies the configuration file for the BuildKit daemon to use. The
    configuration can be overridden by [`--buildkitd-flags`](#buildkitd-flags).
    See an [example BuildKit daemon configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).

    If you don't specify a configuration file, Buildx looks for one by default in:

    * `$BUILDX_CONFIG/buildkitd.default.toml`
    * `$DOCKER_CONFIG/buildx/buildkitd.default.toml`
    * `~/.docker/buildx/buildkitd.default.toml`

    Note that if you create a `docker-container` builder and have specified
    certificates for registries in the `buildkitd.toml` configuration, the files
    will be copied into the container under `/etc/buildkit/certs` and configuration
    will be updated to reflect that.

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

    ```text
    --buildkitd-flags FLAGS
    ```

    Adds flags when starting the BuildKit daemon. They take precedence over the
    configuration file specified by [`--buildkitd-config`](#buildkitd-config). See
    `buildkitd --help` for the available flags.

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

    #### BuildKit daemon network mode

    You can specify the network mode for the BuildKit daemon with either the
    configuration file specified by [`--buildkitd-config`](#buildkitd-config) using the
    `worker.oci.networkMode` option or `--oci-worker-net` flag here. The default
    value is `auto` and can be one of `bridge`, `cni`, `host`:

    ```text
    --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.

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

    ```text
    --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)
    * `cloud`
    * `docker-container`
    * `kubernetes`
    * `remote`

    For more information about build drivers, see [here](/build/builders/drivers/).

    #### `docker` driver

    Uses the builder that is built into the Docker daemon. With this driver,
    the [`--load`](/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.

    #### `cloud` driver

    Uses Docker Build Cloud builders. For Docker Build Cloud access and setup, see
    [Docker Build Cloud setup](/build-cloud/setup/). For
    build examples, see [Building with Docker Build Cloud](/build-cloud/usage/).

    Connect Buildx to an existing cloud builder with `--driver cloud` and the
    builder name in the form `<account>/<builder>` or
    `cloud://<account>/<builder>`. You must be signed in with `docker login` and
    have access to the builder.

    ```console
    $ docker buildx create --driver cloud --name cloud-builder --use org/builder
    $ docker buildx create --driver cloud --name cloud-builder --use cloud://org/builder
    ```

    When you don't specify an output, an untagged result remains in the cloud build
    cache. If you use `--tag`, Buildx automatically loads the image when the build
    targets a single platform and runs on one cloud node. For details about loading
    behavior, Docker contexts, and other output configurations, see
    [Load results from Docker Build Cloud](/build/exporters/).

    When `buildx create` resolves a Build Cloud builder group, each service instance
    becomes a Buildx node. `--append` requires the resolved instance names to be
    unique in the Buildx builder. Resolved cloud nodes are a create-time snapshot;
    recreate the Buildx builder to refresh topology after Build Cloud membership or
    placement changes.

    #### `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.

    Unlike `docker` driver, built images will not automatically appear in
    `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used
    to achieve that.

    #### `kubernetes` driver

    Uses Kubernetes pods. With this driver, you can spin up pods with defined
    BuildKit container image to build your images.

    Unlike `docker` driver, built images will not automatically appear in
    `docker images` and [`build --load`](/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.

    Unlike `docker` driver, built images will not automatically appear in
    `docker images` and [`build --load`](/reference/cli/docker/buildx/build/#load) needs to be used
    to achieve that.

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

    ```text
    --driver-opt OPTIONS
    ```

    Passes additional driver-specific options.
    For information about available driver options, refer to the detailed
    documentation for the specific driver:

    * [`docker` driver](/build/builders/drivers/docker/)
    * [`docker-container` driver](/build/builders/drivers/docker-container/)
    * [`kubernetes` driver](/build/builders/drivers/kubernetes/)
    * [`remote` driver](/build/builders/drivers/remote/)

    With `BUILDX_DEFAULT_POLICY=1`, the `docker-container` driver verifies signed
    `moby/buildkit` builder image tags before creating the builder. To explicitly
    bypass this verification, set `allow-untrusted-image=true`. For example:

    ```console
    $ BUILDX_DEFAULT_POLICY=1 docker buildx create --driver docker-container \
        --driver-opt allow-untrusted-image=true
    ```

    Only use this option for an image that you trust. It disables builder image
    verification for the new builder node.

    ### 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 node that is removed
    is set with `--node`.

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

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

    ```text
    --name NAME
    ```

    The `--name` flag specifies the name of the builder to be created or modified.
    If none is specified, one will be automatically generated.

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

    ```text
    --node NODE
    ```

    The `--node` flag specifies the name of the node to be created or modified. If
    you don't specify a name, the node name defaults to the name of the builder it
    belongs to, with an index number suffix.

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

    ```text
    --platform PLATFORMS
    ```

    The `--platform` flag sets the platforms supported by the node. 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 can be used when multiple nodes support
    building for the same platform.

    ```console
    $ 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 ...)`.
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false