9.3.2.5 Compose Build Image Pairing

Compose build image pairing refers to the common pattern of specifying both build and image together within a single service definition, where Compose constructs the image from local source but also assigns it a specific, meaningful name and tag for reference elsewhere.

The Basic Pairing Pattern

Both fields work together, with build describing how to construct the image and image naming the result.

services:
  api:
    build: .
    image: myapi:2.3.0

After building, this image exists locally as myapi:2.3.0, available to be referenced, pushed to a registry, or used by other tooling that needs that exact image.

Why This Pairing Is More Useful Than Build Alone

Without an explicit image field, a built service's image still exists, but under an automatically generated name based on the project and service name — pairing with an explicit image field instead gives it a deliberate, meaningful, and stable name.

docker images

myapp_api    latest
myapi        2.3.0

The second, explicitly named and tagged image is more clearly identifiable and more conveniently referenced by anything outside the immediate Compose context.

Using This Pairing to Push a Built Image to a Registry

A built and explicitly tagged image can be pushed to a registry, making it available for deployment elsewhere, distinct from how a purely image-only service (with no build) would simply pull an already-published image.

docker compose build api
docker push myapi:2.3.0

Updating the Tag for a New Version

Incrementing the tag as part of a new release keeps each built version distinctly identifiable.

services:
  api:
    build: .
    image: myapi:2.4.0

Why Compose Build Image Pairing Matters

Pairing build with an explicit image field is a valuable practice for any service whose built image might need to be referenced, pushed, or deployed beyond the immediate context of running docker compose up, giving that locally constructed image the same deliberate naming a purely registry-sourced image would have.