9.2.1.1 Service Image Field

The image field within a Compose service specifies which existing, pre-built container image that service should run, used either on its own for off-the-shelf dependencies or in combination with build to name an image produced from local source.

Using Image on Its Own

For a service that simply runs an existing image without any custom build step, image alone specifies exactly which image to pull and run.

services:
  db:
    image: postgres:16
  cache:
    image: redis:7

Compose pulls these images from the configured registry (Docker Hub, by default) if they aren't already present locally.

Specifying a Particular Tag

Including a specific tag, rather than relying on latest, ensures the exact intended version of an image is used consistently.

services:
  db:
    image: postgres:16.2

Pinning to this specific version avoids the unpredictability of latest silently resolving to a different version at some point in the future.

Using Image Alongside Build

When a service also has a build field, image instead names the resulting image that build produces, giving it a specific, referenceable name and tag.

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

This builds the image from the local Dockerfile and tags the result as myapi:2.3.0, making it referenceable by that name elsewhere.

Pulling the Latest Version of a Referenced Image

For services using an existing image, explicitly pulling the latest version matching a given tag ensures Compose uses the most current image, rather than whatever version happens to already be cached locally.

docker compose pull

Why the Image Field Matters

The image field is fundamental to telling Compose exactly what should actually run for a given service, whether referencing an existing, off-the-shelf image or naming the result of a local build, making correct and deliberate use of this field essential to a working Compose configuration.