9.3.1.5 Compose Cache Options

Compose cache options control how Docker's build cache is used (or deliberately bypassed) when building a service's image through Compose, influencing both build speed and whether a build genuinely reflects the very latest state of its dependencies and base images.

Building With the Default Cache Behavior

Without any special options, Compose's build process uses Docker's standard layer caching, reusing previously built layers whenever the relevant instructions and inputs haven't changed.

docker compose build api

Unchanged layers from a previous build are reused, making this typically much faster than rebuilding every layer from scratch.

Forcing a Build Without Using the Cache

The --no-cache flag bypasses cached layers entirely, useful when a clean, fully fresh build is specifically needed.

docker compose build --no-cache api

This is considerably slower than a cached build, but ensures every instruction in the Dockerfile is genuinely re-executed rather than relying on a potentially stale cached result.

Pulling the Latest Base Images Before Building

The --pull flag ensures the build uses the most current version of any base images referenced, rather than relying on a potentially outdated, locally cached version.

docker compose build --pull api

This is particularly important for base images tagged with a mutable tag like latest, where the locally cached version might not reflect recent upstream updates.

Specifying Cache Sources for More Advanced Caching Scenarios

For more sophisticated build pipelines, particularly in CI environments, explicit cache source and destination configuration can improve cache reuse across separate build invocations or even across different machines.

services:
  api:
    build:
      context: .
      cache_from:
        - myapi:cache

Why Compose Cache Options Matter

Understanding and appropriately using these cache-related options helps balance build speed against the need for a genuinely fresh, accurate build, particularly important when diagnosing a build issue that might otherwise be masked by an overly persistent cached layer.