9.3.2.1 Prebuilt Image Reference

A prebuilt image reference specifies an existing, already-built image — sourced from a public or private registry — that a Compose service should simply run, without Compose constructing that image from any local source code at all.

The Simplest Form of Image Reference

A service depending entirely on an existing image needs only the image field, with no build configuration at all.

services:
  cache:
    image: redis:7
  search:
    image: elasticsearch:8.11.0

Why This Differs Meaningfully From a Build-Based Service

A prebuilt image reference depends entirely on that exact image already existing somewhere accessible — Docker Hub, a private registry — with Compose's role limited to pulling and running it, in contrast to a service whose image Compose actually constructs from a local Dockerfile.

docker compose pull cache
docker compose up -d cache

Pinning a Prebuilt Image to a Specific Digest for Maximum Reproducibility

Beyond just a tag, an image can be referenced by its exact content digest, guaranteeing the precise image content used, immune even to a tag being reassigned to point at different content later.

services:
  cache:
    image: redis@sha256:a1b2c3d4e5f6...

This provides the strongest possible guarantee that the exact same image content is used every time, regardless of any subsequent changes to what a given tag happens to point at.

Checking for Available Updates to a Referenced Image

Periodically checking whether a newer version of a referenced prebuilt image is available helps keep dependencies reasonably current.

docker compose pull

Why Prebuilt Image References Matter

Most Compose applications rely on at least some prebuilt image references for common dependencies like databases and caches, making a clear understanding of how to reference, pin, and update these images an important part of working effectively with Compose.