Dockerfile File Format

Introduction

A Dockerfile is a text file of instructions for building a container image. It belongs to Docker, and other container tools read the same format. Each instruction either changes the image’s files, usually by adding a layer, or sets something about how the image runs.

The file has no extension: it is normally named Dockerfile. Other names are common when a project has several, such as Dockerfile.dev or app.dockerfile, and Podman also looks for Containerfile. The file viewer on this site knows these by their whole name.

Structure

A Dockerfile is plain text, read line by line. A line holds an instruction and its arguments. Instructions are not case-sensitive, but are written in capitals by convention. A backslash at the end of a line continues it on the next. A line starting with # is a comment, and a # anywhere else is ordinary text.

# syntax=docker/dockerfile:1
FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN go build -o /app \
    ./cmd/server

FROM alpine:3.20
COPY --from=build /app /usr/local/bin/app
ENV PORT=8080
EXPOSE $PORT
ENTRYPOINT ["/usr/local/bin/app"]

A file starts with FROM, which names the base image, though ARG may come before it and parser directives come first of all. Each further FROM starts a new stage, which can copy files out of an earlier one.

Parser directives are special comments at the very top of the file, such as # syntax=, which picks the version of the Dockerfile front end, and # escape=, which changes the line-continuation character. They must come before any other comment or instruction.

Links