FROM Instruction Reference

Set the base image for subsequent instructions in the Dockerfile

Syntax

FROM [--platform=] [AS ]

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

The FROM instruction is the most fundamental instruction in a Dockerfile. It specifies the base image from which you are building, establishing the foundation for your container image.

A Dockerfile must start with a FROM instruction, though it can be preceded by ARG instructions that are used in the FROM line. A single Dockerfile can contain multiple FROM instructions to create multiple images or use one build stage as a dependency for another.

Options

--platform=<platform>

Specifies the platform of the image if the build is multi-platform enabled. For example, linux/amd64, linux/arm64, or windows/amd64.

FROM --platform=linux/arm64 node:18-alpine
AS <name>

Names the build stage for use in subsequent FROM instructions with the --from flag in COPY instructions.

FROM node:18 AS build

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

Basic Usage

Using a specific version of an image as the base:

FROM ubuntu:20.04

This sets Ubuntu 20.04 as the base image for the build.

Using a Digest

Using a digest to pin the exact version of the base image:

FROM ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

This ensures you always use exactly the same base image, regardless of tag changes.

Multi-stage Build

Using multiple FROM instructions for a multi-stage build:

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

This builds the application in one stage and then copies only the build artifacts to a smaller production image.

Using Platform Flag

Specifying the platform for the base image:

FROM --platform=linux/arm64 node:18

This specifies that the node:18 image should be for the arm64 architecture.

Using ARG Before FROM

Using an ARG instruction before FROM to parameterize the base image:

ARG VERSION=20.04
FROM ubuntu:${VERSION}

This allows you to change the base image version at build time using --build-arg.

Multiple FROM Instructions

Using multiple FROM instructions to create multiple images in one Dockerfile:

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

This creates a base image and then two variants (dev and prod) that build upon it.

Best Practices

  • Always specify a tag or digest: Avoid using the latest tag, as it can lead to unexpected changes in your base image over time.
  • Use specific tags: Prefer version-specific tags (e.g., node:18.12) over more general tags (e.g., node:18) for better reproducibility.
  • Consider using digests for production: For maximum reliability, use image digests to ensure you always get exactly the same image.
  • Use lightweight base images: Consider Alpine-based or "slim" variants of images to reduce the final image size.
  • Leverage multi-stage builds: Use multiple FROM instructions to create smaller, more secure production images.
  • Consider distroless images: For production, consider using "distroless" images that contain only your application and its runtime dependencies, not a full OS.
  • Be aware of platform differences: Use the --platform flag when building for different architectures.

Notes and Limitations

  • A Dockerfile must have at least one FROM instruction.
  • The ARG instruction is the only instruction that can precede FROM in a Dockerfile.
  • 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 --platform flag requires BuildKit and was introduced in Docker 19.03.
  • When building for multiple platforms, the FROM instruction will use the target platform by default, unless --platform is specified.

Related Instructions

RUN

Executes commands in a new layer on top of the current image.

COPY

Copies files from the build context to the image, with options to copy from other build stages.

ARG

Defines variables that can be passed at build time, including in FROM instructions.

WORKDIR

Sets the working directory for subsequent instructions in the Dockerfile.
Reference Index
RUN Instruction

On This Page

Try Our Optimizer

Analyze your Dockerfile for optimization opportunities.

Dockerfile Optimizer

Related Tutorials