FROM Instruction Reference

Description

The FROM instruction initializes a new build stage and sets the base image for subsequent instructions. As such, a valid Dockerfile must start with a FROM instruction.

The image can be any valid image – it's especially easy to start with an image from a public repository like Docker Hub. For example:

FROM ubuntu:20.04
FROM python:3.9-slim
FROM node:18-alpine

The image value can be specified in several formats:

• image:tag - Specifies a particular version of the image using a tag (e.g., ubuntu:20.04)
• image@digest - Specifies an exact version of the image using a content hash (e.g., ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2)
• image - Without a tag, defaults to the latest tag, which is generally not recommended for production use

The AS name syntax assigns a name to the build stage, which can be referenced in subsequent FROM and COPY instructions. This is extremely useful in multi-stage builds for creating small production images.

The --platform flag allows you to specify the platform of the image if the build is multi-platform enabled. This is useful for cross-platform builds and for ensuring consistent builds across different architectures.

Examples

FROM ubuntu:20.04

FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

FROM --platform=linux/arm64 node:18

ARG VERSION=20.04
FROM ubuntu:${VERSION}

FROM ubuntu:20.04 AS base
RUN apt-get update && apt-get install -y python3

FROM base AS dev
RUN apt-get install -y python3-dev

FROM base AS prod
COPY --from=dev /app/build /app

Building from scratch

scratch is a reserved, empty image. It contains no filesystem at all — no shell, no libc, no CA certificates, not even /tmp. FROM scratch produces an image whose only contents are whatever you copy into it, which is why it is the standard final stage for a statically linked binary:

FROM golang:1.22-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server

FROM scratch
COPY --from=build /out/server /server
ENTRYPOINT ["/server"]

Three things routinely go wrong on scratch, and all three are the absence of files rather than a Docker problem:

• TLS fails with x509: certificate signed by unknown authority. There is no CA bundle. Copy one in: COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/.
• The binary will not start. A dynamically linked binary has nothing to link against. Build with CGO_ENABLED=0 for Go, or --target x86_64-unknown-linux-musl for Rust.
• You cannot debug it. There is no shell, so docker exec -it … sh fails. If you need a shell, use a distroless :debug variant or alpine:3.20 instead — see choosing a base image.

scratch cannot be pulled or tagged; it only exists as a value for FROM. If you need almost nothing but still want a user database and CA certificates, gcr.io/distroless/static is the usual middle ground.

Error: "no build stage in current context" / "stage requires a FROM instruction"

These errors mean the builder found an instruction before the first FROM, so there is no stage for it to belong to. BuildKit reports no build stage in current context; the legacy builder said Please provide a source image with `from` prior to commit; other tools phrase it as "stage requires a FROM instruction". Only ARG, comments and parser directives such as # syntax= are permitted above the first FROM:

# syntax=docker/dockerfile:1
# ARG before FROM is allowed, but it is only usable in FROM lines
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
# Redeclare it to use the value inside the stage
ARG NODE_VERSION

Common causes:

• An ENV, LABEL, RUN or WORKDIR above the first FROM. Move it below. If you wanted a value available to FROM, use ARG instead of ENV.
• A trailing backslash on the line before FROM. ARG BASE=alpine \ joins the next line into the ARG, so the FROM disappears.
• The wrong file. docker build -f points at a fragment, a Compose file, or a Dockerfile that starts with a shared snippet meant to be concatenated.
• A misspelled FROM usually gives unknown instruction: FORM instead, but check for it while you are there.

Comments and blank lines between stages are fine. Instructions between one stage's last line and the next FROM belong to the preceding stage, which is valid but easy to misread.

Can FROM point to another Dockerfile?

No. FROM takes an image reference, the name of an earlier stage in the same Dockerfile, or a named build context. There is no FROM ./base/Dockerfile or include syntax. The options are:

# 1. Build the other Dockerfile first, then reference its tag
docker build -t myorg/base:1.0 -f base/Dockerfile base/
#    ...and in the app Dockerfile:  FROM myorg/base:1.0

# 2. Supply the base as a named build context (no Dockerfile change needed
#    beyond FROM base). Works with an image, a directory, a Git URL or an OCI layout.
docker buildx build --build-context base=docker-image://myorg/base:1.0 -t myapp .

# 3. Merge both into one multi-stage Dockerfile and use the stage name
FROM debian:12-slim AS base
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates

FROM base AS app
COPY . /app

With Docker Bake you can also feed one Dockerfile's target into another without pushing it: set contexts = { base = "target:base" } on the dependent target, and Bake builds base first.

--platform, $BUILDPLATFORM and $TARGETPLATFORM

BuildKit sets these build args automatically in the global scope, so they can be used in FROM without declaring them:

• BUILDPLATFORM — the platform of the machine running the build (e.g. linux/amd64).
• TARGETPLATFORM — the platform being built, from docker build --platform (defaults to BUILDPLATFORM). Also split into TARGETOS, TARGETARCH, TARGETVARIANT.

A FROM without --platform pulls the TARGETPLATFORM variant. For a compiler stage, pin it to the build machine so it runs natively instead of under QEMU emulation, and cross-compile for the target:

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.23-alpine AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app .

# Final stage: no --platform, so it uses the target platform
FROM alpine:3.20
COPY --from=build /out/app /usr/local/bin/app
ENTRYPOINT ["app"]

docker buildx build --platform linux/amd64,linux/arm64 -t myorg/app:1.0 --push .

Inside a stage, TARGETOS/TARGETARCH must be redeclared with ARG before use, like any global arg (see ARG scope). More in multi-arch builds with buildx.

Notes and Limitations

• A Dockerfile must have at least one FROM instruction.
• ARG is the only instruction that can precede the first FROM; comments and parser directives may also appear above it.
• Multiple FROM instructions in a single Dockerfile are used for multi-stage builds or to create multiple images.
• Each FROM instruction clears any state created by previous instructions.
• The AS syntax was introduced in Docker 17.05.
• The automatic platform args (BUILDPLATFORM, TARGETPLATFORM, TARGETARCH, ...) are only set by BuildKit, the default builder since Docker Engine 23.0.
• When building for multiple platforms, the FROM instruction will use the target platform by default, unless --platform is specified.