9.3.2 Service Image Config

Service image config covers the various ways the image field can be used within a Compose service — referencing an existing image outright, or naming the result of a local build — together with related considerations like tagging and registry sourcing.

Image Used Without a Build

For a service representing an off-the-shelf dependency, image alone specifies exactly which existing image to pull and run.

services:
  db:
    image: postgres:16

Image Combined With Build

For a service representing custom application code, image names the result of the accompanying build configuration, giving that built image a specific, referenceable tag.

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

Why Explicit Tagging Matters for Either Case

Whether referencing an existing image or naming a locally built one, specifying an explicit, meaningful tag (rather than relying on an implicit or mutable latest) makes the actual version in use clear and consistent.

services:
  db:
    image: postgres:16.2
  api:
    build: .
    image: myapi:2.3.0

Referencing an Image From a Private Registry

An image hosted in a private registry is referenced by including that registry's address as part of the image name.

services:
  api:
    image: registry.example.com/myteam/myapi:2.3.0

docker login registry.example.com
docker compose pull api

Authentication with the private registry may be required before Compose can successfully pull an image referenced this way.

Why Service Image Config Matters

A clear understanding of how image behaves both with and without an accompanying build field, along with sound tagging and registry referencing practices, is foundational to ensuring each service in a Compose application runs exactly the intended version of its corresponding image.