9.3.2.2 Compose Local Image Tag

A Compose local image tag is the name and version identifier assigned to an image built locally from a service's own build configuration, set through the accompanying image field, distinguishing this locally constructed image from any image instead pulled from a remote registry.

Assigning a Local Tag to a Built Image

Specifying image alongside build names the resulting locally built image with a specific tag.

services:
  api:
    build: .
    image: myapi:local

After building, this image exists locally, tagged as myapi:local, distinct from any same-named image that might exist in a remote registry.

Why a Clear Local Tagging Convention Helps Avoid Confusion

Adopting a clear naming convention for locally built images — a :local or :dev suffix, for instance — helps distinguish them at a glance from images intended to be pulled from a registry, reducing the chance of confusing the two.

services:
  api:
    build: .
    image: myapi:dev

docker images | grep myapi

myapi   dev   a1b2c3d4e5f6   2 minutes ago   180MB

Referencing the Local Tag From Elsewhere

A locally built and tagged image can be referenced directly by other tooling or scripts that need to use the exact same image Compose just built.

docker run --rm myapi:dev npm test

Why Locally Tagged Images Aren't Automatically Pushed Anywhere

Building and tagging an image locally through Compose has no effect on any remote registry — an explicit docker push is required separately if that image actually needs to be shared or deployed elsewhere.

docker compose build api
docker push myapi:dev

Why Compose Local Image Tags Matter

Deliberately and clearly tagging locally built images helps avoid confusion between local development builds and images sourced from a registry, supporting a more predictable development workflow as a project's images and their various versions accumulate over time.