Difference between 'image' and 'build' within docker compose

Please help me understand the difference between 'image' and 'build' within docker compose


  • image means docker compose will run a container based on that image
  • build means docker compose will first build an image based on the Dockerfile found in the path associated with build (and then run a container based on that image).

PR 2458 was eventually merged to allow both (and use image as the image name when building, if it exists).

therobyouknow mentions in the comments:

dockerfile: as a sub-statement beneath build: can be used to specify the filename/path of the Dockerfile.

version: '3'
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1

build: expects dockerfile path as an argument, it will build an image first and then use the image to create a container.

image: expects existing image name as argument , it will launch container using this image.

Example:docker-compose.yaml

version: '3'
services:
  service1:
    build: .
    ports:
      - "5000:5000"
  service2:
    image: "redis:alpine"

service1 will build an image first based on Dockerfile of current path and run container based on this image.

service2 will download "redis:alpine" image from docker hub and run container on downloaded image.