9.3.2.4 Compose Pull Behavior

Compose pull behavior governs when and how Compose retrieves a service's image from a registry, whether automatically as part of up, or explicitly through a dedicated pull command, and how this interacts with locally cached images and locally built services.

Automatic Pulling as Part of Starting Services

Running up automatically pulls any referenced image not already present locally before starting the corresponding service.

docker compose up -d

For an image already cached locally, this automatic pull check is typically fast, but it does still occur unless explicitly skipped.

Explicitly Pulling Without Starting Anything

The dedicated pull command retrieves the latest version of every referenced image without starting any services, useful for refreshing images ahead of time.

docker compose pull

Controlling Pull Behavior With the Pull Policy

The pull_policy field on a service gives more explicit control over exactly when that service's image should be pulled.

services:
  db:
    image: postgres:16
    pull_policy: always

Setting this to always ensures the latest version matching the specified tag is pulled every time, rather than relying on a potentially outdated, locally cached version.

Why Built Services Don't Pull the Same Way

A service with a build configuration, rather than only an image reference, doesn't pull anything for that service — it builds its image instead, with pull having no equivalent effect on services constructed locally rather than sourced from a registry.

services:
  api:
    build: .

docker compose pull api

This command has no meaningful effect on the api service specifically, since it has no remote image to pull in the first place.

Why Compose Pull Behavior Matters

Understanding exactly when and how Compose pulls images — automatically, explicitly, or governed by an explicit pull policy — helps avoid both unnecessarily stale cached images and unexpected, unnecessary network activity when an image doesn't actually need to be re-pulled.