Docker Buildx: How To Build Multi-Platform Container Images

Advanced Use Cases

So far, I showed you basic Buildx commands and use cases. There's a lot more Buildx can do, with some of the features being impossible to implement with the classic builder.

Let's explore some advanced techniques to take your containerization workflow to the next level.

Multi-stage build optimization

Multi-stage builds are one of Docker's most powerful features for creating efficient images, and Buildx makes them even better.

To demonstrate, let's create an optimized Python application with multiple stages:

# Dockerfile.optimized
FROM python:3.13-slim AS base
WORKDIR /app
COPY requirements.txt .

FROM base AS builder
RUN pip install --no-cache-dir --target=/install -r requirements.txt

FROM base AS linter
COPY --from=builder /install /usr/local/lib/python3.13/site-packages
COPY app.py .
RUN pip install pylint && pylint app.py || exit 0

FROM base AS tester
COPY --from=builder /install /usr/local/lib/python3.9/site-packages
COPY app.py .
RUN pip install pytest && python -m pytest app.py -v || exit 0

FROM python:3.13-alpine AS final
WORKDIR /app
COPY --from=builder /install /usr/local/lib/python3.13/site-packages
COPY app.py .
EXPOSE 5000
CMD ["python", "app.py"]

With Buildx, you can build this more efficiently:

docker buildx build --file Dockerfile.optimized -t myapp:optimized --load .

Image 9 - Multi-stage builds

So, what makes this special? Buildx processes independent stages in parallel. While the legacy builder would execute each stage sequentially, Buildx identifies that the linter and tester stages don't depend on each other and builds them simultaneously.

One more added benefit of this build optimization is reduction in file size. You can verify the image size by running the following:

docker images myapp

You'll see something like this:

Image 10 - Docker image sizes

The alpine-based final image is much smaller.

CI/CD pipeline integration

While you're working locally, you can still set up Buildx configurations that mirror your CI/CD environment.

To start, create a .dockerignore file to keep builds clean:

.git
__pycache__
*.pyc
*.pyo
*.pyd
.Python
env
venv
*.so
.coverage
htmlcov

Then create a build script that mimics what your CI pipeline might do:

#!/bin/bash
# build.sh - Local CI/CD simulation

echo "Starting CI/CD build process..."

# Setup builder with emulation support
echo "Setting up builder..."
docker buildx create --name cibuilder --use || true
docker buildx inspect --bootstrap

# Run linting
echo "Running lint stage..."
docker buildx build --file Dockerfile.optimized --target linter .

# Run tests
echo "Running test stage..."
docker buildx build --file Dockerfile.optimized --target tester .

# Build for multiple platforms
echo "Building multi-platform image..."
docker buildx build --file Dockerfile.optimized \
  --platform linux/amd64,linux/arm64 \
  --tag myapp:$(date +%Y%m%d) \
  --tag myapp:latest \
  --load \
  --progress=plain \
  .

echo "Build process complete!"

In plain English, this script does the following:

• Creates a dedicated builder for CI/CD.
• Runs the linting stage.
• Runs the testing stage.
• Builds the final multi-platform image with versioned tags.

Now for the fun part - make the script executable and run it:

chmod +x build.sh
./build.sh

Local editing

A common pain point when working with Docker is that every time you change the source file, you need to rebuild the image and run the container. It just takes too much time.

Here is the good news: for local development with faster iterations, you can create a development version:

# Dockerfile.dev
FROM python:3.13-slim
WORKDIR /app

RUN pip install flask psutil python-dotenv

# Install development tools
RUN pip install pytest pylint watchdog

# Mount app code at runtime instead of copying
CMD ["python", "app.py"]

Run it with a volume mount for live code reloading:

docker buildx build -f Dockerfile.dev -t myapp:dev --load .
docker run -it --rm -p 5000:5000 -v $(pwd):/app myapp:dev

Now you can edit your app.py file locally, and the changes will be immediately reflected in the running container!

Up next, let's discuss performance.

Performance Considerations

Nobody likes a slow development workflow, and the power of parallelization with Docker Buildx can help.

Let's explore how to optimize your builds and take advantage of Buildx's performance features to create images faster.

Build parallelization techniques

One of Buildx's biggest advantages is its ability to build stages in parallel. The traditional Docker builder executes each step sequentially, but Buildx analyzes your Dockerfile and identifies which steps can run at the same time.

To demonstrate, I'll use two files - Dockerfile.standard and Dockerfile.parallel. Here are the contents for both:

Dockerfile.standard

FROM python:3.13-slim
WORKDIR /app

# System dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Application code
COPY app.py .

# Linting
RUN pip install pylint && pylint app.py || true

EXPOSE 5000
CMD ["python", "app.py"]

Dockerfile.parallel

FROM python:3.13-slim AS python-base
WORKDIR /app

# Independent stage for installing system dependencies
FROM python-base AS system-deps
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    g++ \
    && rm -rf /var/lib/apt/lists/*

# Independent stage for installing Python dependencies
FROM python-base AS python-deps
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Independent stage for static code analysis
FROM python-deps AS linting
COPY app.py .
RUN pip install pylint && pylint app.py || true

# Final stage that combines dependencies
FROM python-base AS final
# Copy from system deps stage
COPY --from=system-deps /usr/bin/gcc /usr/bin/gcc
# Copy from Python deps stage
COPY --from=python-deps /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
COPY app.py .
EXPOSE 5000
CMD ["python", "app.py"]

Let's measure how this parallel structure improves build times:

# Time the standard sequential build
time docker build -t myapp:standard -f Dockerfile.standard .

# Time the parallel-optimized build with Buildx
time docker buildx build --load -t myapp:parallel -f Dockerfile.parallel .

For reference, the standard build took 18.48 seconds while the parallel build took only 1.17 seconds!

For even better performance, you can try using the --cache-from and --cache-to flags to leverage local disk caching:

# First build - create cache
docker buildx build --load -t myapp:latest --cache-to type=local,dest=./buildcache .

# Subsequent builds - use cache
docker buildx build --load -t myapp:latest --cache-from type=local,src=./buildcache .

You can also limit context size with careful .dockerignore files:

# Create a comprehensive .dockerignore
cat > .dockerignore << 'EOF'
.git
.github
.dockerignore
.pytest_cache
__pycache__
*.pyc
*.pyo
*.pyd
.Python
venv
env
node_modules
.coverage
htmlcov
.DS_Store
EOF

Long story short, by structuring your Dockerfiles with parallelization in mind and leveraging Buildx's advanced caching, you'll spend less time waiting for builds and more time developing features.

Ecosystem Integration

Docker Buildx doesn't exist in isolation. It's built to integrate seamlessly with other tools in your development environment.

Let's explore how Buildx works with local developer tools and makes your container workflow more efficient.

Kubernetes build clusters

Kubernetes offers powerful capabilities for running distributed Docker Buildx operations across a cluster. When integrating Buildx with Kubernetes, you can get faster and more resilient builds that scale with your project needs.

> Are you new to Kubernetes? The Kubernetes vs Docker: Differences Every Developer Should Know post is your next stop.

Using Kubernetes for your build infrastructure offers a couple of advantages:

1. Automatic scaling: Kubernetes can scale your builder nodes up or down based on demand, allocating resources efficiently across your cluster. You can even set up autoscaling rules based on CPU utilization.
2. Resource optimization: Kubernetes scheduling makes sure your builds get the resources they need without overwhelming individual nodes. You can set resource limits and requests to ensure consistent performance.
3. High availability: By distributing BuildKit instances across multiple nodes, your build infrastructure remains available even if individual nodes fail.
4. Consistent environments: Every team member connects to the same build infrastructure, eliminating "works on my machine" problems.
5. Parallel execution: Complex builds with many stages can run in parallel across multiple nodes, significantly reducing build times. A project that might take 15 minutes to build locally could be completed in 3-4 minutes when distributed.

Consider this a more "theoretical" section, as diving deeper into Kubernetes is an advanced topic in itself.

To get started, create a file named buildkit-deployment.yaml with the following contents:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: buildkit
  namespace: buildkit
spec:
  replicas: 3
  selector:
    matchLabels:
      app: buildkit
  template:
    metadata:
      labels:
        app: buildkit
    spec:
      containers:
      - name: buildkit
        image: moby/buildkit:latest
        args:
        - --addr
        - tcp://0.0.0.0:1234
        ports:
        - containerPort: 1234
        securityContext:
          privileged: true
---
apiVersion: v1
kind: Service
metadata:
  name: buildkit
  namespace: buildkit
spec:
  type: ClusterIP
  ports:
  - port: 1234
    targetPort: 1234
  selector:
    app: buildkit

The next step is to apply this file to your Kubernetes cluster:

kubectl create namespace buildkit
kubectl apply -f buildkit-deployment.yaml

Finally, connect to this deployment from your local machine:

docker buildx create --name k8s-builder \
  --driver remote \
  --driver-opt endpoint=tcp://<cluster-ip>:1234 \
  --use

And that's it, you're good to go!

IDE plugin support

IDEs like Visual Studio Code offer excellent integration with Docker Buildx through its Docker extension. This integration makes it easier to manage your Buildx workflows directly from your development environment.

To get started with Docker Buildx in VS Code, install the "Docker" extension from the VS Code marketplace.

Once installed, you'll gain several Buildx-specific features:

• Right-click on any Dockerfile to see a context menu with a "Build Image..." option that supports Buildx.
• Access to build arguments, platform targets, and output options through the UI.
• Ability to manage and switch between different builder instances.
• Integration with the VS Code terminal for running complex Buildx commands.

Image 11 - Docker extension for VSCode

Here's an example of customizing VS Code tasks to use Buildx by creating a .vscode/tasks.json file:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Docker: Buildx Build",
      "type": "shell",
      "command": "docker buildx build --load -t ${input:imageName} .",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    },
    {
      "label": "Docker: Buildx Multi-Platform",
      "type": "shell",
      "command": "docker buildx build --platform linux/amd64,linux/arm64 -t ${input:imageName} ."
    }
  ],
  "inputs": [
    {
      "id": "imageName",
      "description": "Image name (with tag):",
      "default": "myapp:latest",
      "type": "promptString"
    }
  ]
}

With this configuration, you can quickly access common Buildx commands from the VS Code Tasks menu (Terminal > Run Task). The extension also provides helpful syntax highlighting for Dockerfiles and autocompletion for common Docker commands, all of which make your Buildx workflow more productive.

Troubleshooting and Debugging

Every development tool will sometimes (too often) need troubleshooting, and Docker Buildx is no exception. In this section, I'll walk you through a couple of common issues so you can diagnose them yourself quickly and get back on track.

Common issues and resolutions

When working with Buildx, you might encounter a couple of common challenges. Here are the most frequent issues and their solutions:

• Builder creation fails. If you see errors when creating a builder with docker buildx create, check your Docker version:

docker version

Buildx requires Docker 19.03 or newer. If you're using an older version, upgrade Docker to access Buildx features.

For "no such plugin" errors, make sure Buildx is properly installed by running:

docker buildx version

• Multi-platform build failures. When building for multiple platforms with errors like "exec format error" or "no matching manifest", check if QEMU is installed:

docker buildx inspect --bootstrap

If necessary, install platform emulators:

docker run --privileged --rm tonistiigi/binfmt --install all

• Cache-related issues. For problems with caching, try clearing your local build cache:

# Remove specific builder's cache
docker buildx prune -b mybuilder

# Remove all build cache
docker buildx prune --all

> What exactly is the Docker prune command? Learn with a ton of hands-on examples.

• BuildKit daemon connection problems. If you see "failed to solve" or connection errors, restart the builder:

docker buildx rm mybuilder
docker buildx create --name mybuilder --use
docker buildx inspect --bootstrap

• Performance-related issues. For slow builds, try the debug output to identify bottlenecks:

docker buildx build --progress=plain --no-cache .

This verbose output helps pinpoint which build stages are taking the most time, allowing you to optimize your Dockerfile accordingly.

• "Load" command failures. If you encounter "error: docker exporter does not currently support exporting manifest lists" when using --load with multi-platform builds, remember that loading multiple platforms into the Docker daemon simultaneously isn't supported. Instead:

# Build for your current platform and load it
docker buildx build --platform linux/amd64 --load -t myapp:latest .

• Debugging practices. For more complex issues, these debugging approaches will help:

# Enable BuildKit debug logs
BUILDKIT_DEBUG=1 docker buildx build .

# Inspect the builder's internal state
docker buildx inspect

# Check system requirements
docker info

# For specific stage failures, build only up to that stage
docker buildx build --target problem-stage .

# Verify your Docker context
docker context ls

By systematically working through these troubleshooting steps, you can resolve most Buildx issues and maintain an efficient container build workflow.

Summing up Docker Buildx Guide

We've covered a lot of ground in this Docker Buildx article! You've seen how this powerful tool can make your container builds faster and more flexible.

Remember the key benefits: You can build images for multiple platforms with a single command, speed up your builds with advanced caching, and keep your images secure with proper secret management. The performance improvements are real, especially when you structure your Dockerfiles to take advantage of parallel building.

I use it all the time on my M-chip Macbook, since not all images are available for ARM.

Whether you're a solo developer or part of a large team, Buildx gives you tools that fit your workflow. You can run builds locally, distribute them across containers, or even scale up to Kubernetes clusters as your needs grow.

To learn more about Docker and Docker Buildx, I recommend enrolling in the following DataCamp courses:

• Containerization and Virtualization Concepts
• Introduction to Docker
• Intermediate Docker
• Containerization and Virtualization with Docker and Kubernetes
• CI/CD for Machine Learning