docker buildx create and use Command Reference

By Kaveh Alemi·Latchkey

Create and select a BuildKit builder instance.

docker buildx create provisions a new builder. The default builder uses the limited docker driver; multi-arch builds and external cache backends require the docker-container driver, which create sets up. docker buildx use selects which builder subsequent build commands target.

Common flags

• --name - name the builder instance
• --driver - builder driver, e.g. docker-container (needed for multi-arch and gha cache)
• --use - immediately switch to the new builder after creating it
• --bootstrap - start the builder right away instead of lazily on first build
• --platform - declare the platforms this builder supports

Example

docker buildx create --name ci-builder --driver docker-container --use
docker buildx inspect --bootstrap
docker buildx use ci-builder

In CI

Most workflows use the docker/setup-buildx-action which runs create/use for you, but doing it explicitly is useful in custom scripts. The docker-container driver is mandatory for --platform multi-arch and for type=gha cache; the default docker driver silently ignores those features.

Key takeaways

• The docker-container driver is required for multi-arch and external cache; the default docker driver is not enough.
• --use makes the new builder the active one for later build commands.
• buildx inspect --bootstrap warms the builder before the first build.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation