9.3.1.2 Compose Dockerfile Path

The Compose Dockerfile path, specified through the dockerfile field within a service's build configuration, identifies exactly which Dockerfile (by name and location, relative to the build context) Compose should use, supporting projects that maintain more than one Dockerfile for different purposes.

Specifying a Non-Default Dockerfile Name

Without this field, Compose looks for a file simply named Dockerfile within the build context — dockerfile overrides this to use a differently named file instead.

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile.prod

Why Multiple Dockerfiles Are a Common Pattern

A project often maintains separate Dockerfiles for different purposes — a development-oriented one with debugging tools included, a lean, optimized production one — selecting between them through this field as appropriate.

Dockerfile.dev
Dockerfile.prod

services:
  api-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
  api-prod:
    build:
      context: .
      dockerfile: Dockerfile.prod

Specifying a Dockerfile in a Different Directory

The dockerfile path is interpreted relative to the build context, allowing it to reference a Dockerfile that resides somewhere other than the context's own root.

services:
  api:
    build:
      context: .
      dockerfile: docker/api/Dockerfile

Verifying the Correct Dockerfile Is Actually Being Used

Reviewing the build output confirms which specific Dockerfile's instructions were actually executed, useful when a project has several Dockerfiles and there's any doubt about which one a given build picked up.

docker compose build api

Why the Dockerfile Path Field Matters

This field provides the flexibility needed for projects maintaining multiple, purpose-specific Dockerfiles, ensuring each service's build process uses exactly the Dockerfile appropriate to its specific role, rather than being limited to a single, default-named file.