Stage 4 · Provision
Image Internals & Advanced Builds
BuildKit Cache Mounts
Speed builds with RUN --mount=type=cache, inline cache metadata, registry caches, and buildx bake.
Cache Mount Overview
BuildKit cache mounts persist data between builds without including it in image layers. This is fundamentally different from layer caching. Cache mounts survive between builds but are not part of the image. Package managers use them to avoid re-downloading dependencies.
# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
# Cache mount for npm
RUN --mount=type=cache,target=/root/.npm \
npm ci
# Cache mount with ID (isolated caches)
RUN --mount=type=cache,target=/root/.cache,id=npm-cache \
npm ciThe target is the path inside the container where the cache is mounted. The id isolates caches — different IDs do not share data. Without id, all builds share the same cache.
Package Manager Caches
# syntax=docker/dockerfile:1
# Node.js
FROM node:20-alpine
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
# Python
FROM python:3.12-slim
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
pip install -r requirements.txt
# Go
FROM golang:1.22-alpine
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
# Rust
FROM rust:1.75-slim
COPY Cargo.toml Cargo.lock ./
RUN --mount=type=cache,target=/usr/local/cargo/registry \
cargo build --release
# Apt
FROM ubuntu:22.04
RUN --mount=type=cache,target=/var/lib/apt/lists \
--mount=type=cache,target=/var/cache/apt \
apt-get update && apt-get install -y curlEach package manager has its own cache directory. Mount the correct path for each. The cache persists between builds, so the second build is much faster than the first.
Inline Cache
# Build with inline cache metadata
docker build \
--cache-to type=inline \
-t myregistry.com/myapp:1.0 .
# Pull with cache
docker buildx build \
--cache-from type=registry,ref=myregistry.com/myapp:1.0 \
-t myregistry.com/myapp:1.1 .Inline cache embeds cache metadata in the image manifest. Other machines pulling the image can use it as a cache source. This is the simplest way to share build cache across machines.
Registry Caches
# Export cache to registry
docker buildx build \
--cache-to type=registry,ref=myregistry.com/myapp:cache \
-t myregistry.com/myapp:1.0 .
# Import cache from registry
docker buildx build \
--cache-from type=registry,ref=myregistry.com/myapp:cache \
-t myregistry.com/myapp:1.1 .Registry caches store build cache as blobs in the registry. This is more flexible than inline cache — you can store cache for multiple builds and select which cache to use.
buildx bake
group "default" {
targets = ["api", "worker", "frontend"]
}
target "api" {
context = "./api"
cache-from = ["type=registry,ref=myregistry.com/api:cache"]
cache-to = ["type=registry,ref=myregistry.com/api:cache,mode=max"]
tags = ["myregistry.com/api:1.0"]
}
target "worker" {
context = "./worker"
cache-from = ["type=registry,ref=myregistry.com/worker:cache"]
cache-to = ["type=registry,ref=myregistry.com/worker:cache,mode=max"]
tags = ["myregistry.com/worker:1.0"]
}
target "frontend" {
context = "./frontend"
cache-from = ["type=registry,ref=myregistry.com/frontend:cache"]
cache-to = ["type=registry,ref=myregistry.com/frontend:cache,mode=max"]
tags = ["myregistry.com/frontend:1.0"]
}buildx bake builds multiple targets in parallel using a declarative configuration. Each target can have its own cache settings. Build all targets with docker buildx bake.
Best Practices
- Use cache mounts for all package manager caches
- Use separate cache IDs for different build stages
- Combine cache mounts with inline or registry cache for CI/CD
- Use buildx bake for multi-service projects
- Set mode=max on registry caches to export all layers
- Monitor cache hit rates with --progress=plain
- Clean up stale caches periodically with buildx prune
By default, registry caches only export the final layer's cache. Use mode=max to export all intermediate layers. This makes cache hits more likely on subsequent builds.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.