SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdocker-buildx

docker-buildx

Deployment & operations

View repository

Updated 10-15 17:45

About this skill

Docker Buildx — Build Engine and Multi-Platform

Expert guidance for docker build, buildx, multi-platform builds, and build optimization.

When to Use

ALWAYS use this skill when the user mentions:

  • "docker build", "buildx", "build image"
  • "multi-platform", "multi-arch", "multi-platform build"
  • "linux/arm64", "linux/amd64"
  • "BuildKit", "Build Cloud"
  • "build acceleration", "build cache", "build cache"
  • "Docker build is slow", "how to speed up docker build"
  • Need to build images for multiple CPU architectures

Core Commands

# Basic build
docker build -t myapp:v1 .

# Build with BuildKit (default in modern Docker)
DOCKER_BUILDKIT=1 docker build -t myapp:v1 .

# Build from specific Dockerfile
docker build -f Dockerfile.prod -t myapp:v1 .

# No cache rebuild
docker build --no-cache -t myapp:v1 .

Buildx — Multi-Platform Builder

Setup

# Create a builder instance
docker buildx create --name multiarch --use

# Inspect available platforms
docker buildx inspect --bootstrap

Build for Multiple Platforms

# Build and push directly (single command)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:v1.0.0 \
  --push .

# Build and load to local Docker (single platform only)
docker buildx build \
  --platform linux/arm64 \
  -t myapp:arm64 \
  --load .

# Build and export as tar
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:v1.0.0 \
  --output type=tar,dest=myapp.tar .

Platform Aliases

Alias Architectures
linux/amd64 Intel/AMD 64-bit
linux/arm64 ARM 64-bit (Apple Silicon, AWS Graviton)
linux/arm/v7 ARM 32-bit (Raspberry Pi 3)
linux/arm/v6 ARM 32-bit (Raspberry Pi Zero)

BuildKit Features

Secret Mount

# Dockerfile
RUN --mount=type=secret,id=npmrc \
  cp /run/secrets/npmrc .npmrc && \
  npm ci && \
  rm .npmrc

docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

Cache Mount (Persist Across Builds)

# Python: persist pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
  pip install -r requirements.txt

# Node.js: persist npm cache
RUN --mount=type=cache,target=/root/.npm \
  npm ci

# Go: persist module cache
RUN --mount=type=cache,target=/root/.cache/go-build \
  go build -o server .

SSH Forwarding

# Clone private repo during build
RUN --mount=type=ssh \
  git clone git@github.com:org/private-repo.git

docker buildx build --ssh default -t myapp .

Inline Cache (Export Cache into Image)

# Export cache metadata into the image itself
docker buildx build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:latest \
  --push .

# Later builds can use this image as cache source
docker build --cache-from myapp:latest -t myapp:v2 .

Layer Caching — Pull Before Build

# Pull previous image for layer cache
docker pull myapp:latest || true
docker build \
  --cache-from myapp:latest \
  -t myapp:${TAG} .

GitHub Actions — Multi-Platform

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: user/app:latest
    cache-from: type=gha          # GitHub Actions cache
    cache-to: type=gha,mode=max

Workflow — Recommended Build Process

Step 1: Create Builder: docker buildx create --name multiarch --driver docker-container --use Step 2: Choose Approach: Single-platform (--load) or multi-platform (--push)? Cross-compilation or QEMU? Step 3: Configure Dockerfile: Use --platform=$BUILDPLATFORM + ARG TARGETOS TARGETARCH Step 4: Run Build: docker buildx build --platform linux/amd64,linux/arm64 -t app --push . Step 5: Verify: docker buildx imagetools inspect app confirm multi-architecture manifest

Gotchas — Common Pitfalls

  • --load with multi-platform: --load only works for a SINGLE platform. → Recovery: Use --push or --output type=oci,dest=image.tar for multi-platform; or build single platform with --load.
  • QEMU emulation is slow: Building ARM on AMD is 5-10x slower. → Recovery: Use native ARM runners in CI (ubuntu-24.04-arm on GitHub Actions); or Docker Build Cloud for native multi-arch builders.
  • BuildKit by default: Modern Docker uses BuildKit by default. → Recovery: DOCKER_BUILDKIT=1 is a no-op on Docker 23+; use docker buildx build for explicit BuildKit control.
  • --cache-from without pulling first: Docker won't pull the cache image automatically. → Recovery: docker pull myapp:latest || true before docker build --cache-from myapp:latest.

Boundary — Capability Boundaries (Applicable and Non-Applicable Scenarios)

Category Scenario Description
✅ Can do Multi-platform build (linux/amd64,arm64) buildx + QEMU/cross-compilation/native node
✅ Can do BuildKit advanced features secret mount, cache mount, SSH forwarding, inline cache
✅ Can do Docker Build Cloud integration Cloud build + team shared cache
⚠️ Conditional Multi-platform + --load Only single-platform supported; multi-platform requires --push
⚠️ Conditional ARM local without QEMU Requires docker run --privileged --rm tonistiigi/binfmt --install all
❌ Out of scope Dockerfile authoring Use docker-dockerfile
❌ Out of scope Basic docker build/tag/push Use docker-build
❌ Out of scope Container orchestration (Compose/Swarm) Use docker-compose/docker-production

When NOT to Use This Skill

❌ Skip ✅ Use Instead
Writing Dockerfile content docker-dockerfile
Compose-based builds docker-compose
Docker basics docker-basics
Running containers docker-run

Security & Stability

  • Never expose secrets in build logs. Use --secret for BuildKit or CI secrets masking.
  • Multi-platform images must be pushed to a registry — --load only works for single platform.
  • Cache images in CI should be pulled with || true — first build won't have a cache.

📚 Official Documentation Reference

Documentation Address
Docker Build https://docs.docker.com/build/
Buildx reference https://docs.docker.com/reference/cli/docker/buildx/
BuildKit https://docs.docker.com/build/buildkit/
Docker Build Cloud https://docs.docker.com/build-cloud/
Multi-platform build https://docs.docker.com/build/building/multi-platform/
Build cache https://docs.docker.com/build/cache/

🧭 Docker Skills Journey

📍 You are here: docker-buildx — Build engine

← Previous: docker-dockerfile — Write Dockerfiles → Next: docker-run — Run containers / docker-cicd — CI/CD