Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 111 ยท Dockerfiles

FROM and RUN

Master the Dockerfile FROM and RUN instructions: shell form vs exec form, chaining commands, apt-get best practices, ARG before FROM, SHELL and pipefail.

FROM and RUN are the two instructions you will write most often. FROM decides what your image starts with, and RUN does the work of turning that starting point into something useful: installing packages, creating users, compiling code. They look simple, and they hide a handful of details that separate a tidy Dockerfile from one that is slow, huge or silently broken.

This lesson goes through both in depth. You will see the difference between shell form and exec form with real output, learn how to chain commands without bloating the image, follow the apt-get pattern that professionals use, and pass build arguments into FROM. You will also meet a classic trap: a pipeline that fails but lets the build continue.

FROM

FROM starts a new build stage from a base image. The simplest form is FROM image:tag, and you saw it in Writing a Dockerfile. Three more forms are worth knowing:

DOCKERFILE
FROM alpine:3.22                       # a tag
FROM alpine:3.22@sha256:2e0b81d6...    # tag plus digest: pinned, but still readable
FROM --platform=linux/amd64 alpine:3.22  # force a CPU platform
FROM alpine:3.22 AS builder            # give the stage a name (for multi-stage builds)

FROM scratch starts from an empty image, which is the base for tiny, single-binary images. If your Dockerfile has several FROM lines, each starts a new stage, and only the last one becomes the final image. That is the basis of Multi-Stage Builds. The --platform flag is covered in Multi-Platform Images, and choosing among debian, alpine and others in Choosing a Base Image.

ARG before FROM

ARG is the only instruction allowed before FROM. It lets you parameterise the base image:

DOCKERFILE
ARG ALPINE_VERSION=3.22
FROM alpine:${ALPINE_VERSION}

ARG GREETING
RUN echo "ALPINE_VERSION is [${ALPINE_VERSION}]; GREETING is [${GREETING}]"
RUN . /etc/os-release && echo "base: $PRETTY_NAME"

Build it normally and look at the result:

CONSOLE
$ docker build --progress=plain --no-cache -t argdemo .
...
#5 0.566 ALPINE_VERSION is []; GREETING is []
#6 0.518 base: Alpine Linux v3.22

Notice that ALPINE_VERSION is empty inside the stage, even though it selected the right base image. An ARG declared before FROM belongs to the "global" scope, which only FROM lines can read. To use it in a stage, declare it again inside the stage without a value (ARG ALPINE_VERSION), and Docker takes the global default. Now override it from the command line:

CONSOLE
$ docker build --progress=plain --no-cache \
    --build-arg ALPINE_VERSION=3.21 --build-arg GREETING=hello -t argdemo .
...
#5 0.652 ALPINE_VERSION is []; GREETING is [hello]
#6 0.565 base: Alpine Linux v3.21

--build-arg ALPINE_VERSION=3.21 switched the base to Alpine 3.21 (the base: line shows it), and GREETING, declared inside the stage, reached the RUN. ENV and ARG explains scopes in detail and why build arguments must never hold secrets.

RUN: two forms

RUN executes a command during the build and saves the changes as a new layer. It comes in two forms that behave differently.

Shell form

DOCKERFILE
RUN echo "shell form: user=$(whoami) home=$HOME"

The command is a plain string. Docker runs it through a shell (/bin/sh -c "..." on Linux), so you get variable expansion, pipes, &&, redirections and globbing, just as at a terminal.

Exec form

DOCKERFILE
RUN ["echo", "exec form: no shell so $HOME is NOT expanded"]

The command is a JSON array: the program, then each argument as a separate string (double quotes required). Docker starts the program directly, with no shell in between. That means no variable expansion, no pipes, no &&. It is exact and predictable, and it is the right choice for CMD and ENTRYPOINT (see CMD and ENTRYPOINT), but for RUN you mostly want shell form.

You can build a shell yourself in exec form when you want to be explicit:

DOCKERFILE
FROM alpine:3.22
RUN echo "shell form: user=$(whoami) home=$HOME"
RUN ["echo", "exec form: no shell so $HOME is NOT expanded"]
RUN ["/bin/sh", "-c", "echo exec form with sh -c: home=$HOME"]

And the build output proves the difference:

CONSOLE
$ docker build --progress=plain --no-cache -t forms .
...
#5 [2/4] RUN echo "shell form: user=$(whoami) home=$HOME"
#5 0.296 shell form: user=root home=/root
#6 [3/4] RUN ["echo", "exec form: no shell so $HOME is NOT expanded"]
#6 0.414 exec form: no shell so $HOME is NOT expanded
#7 [4/4] RUN ["/bin/sh", "-c", "echo exec form with sh -c: home=$HOME"]
#7 0.334 exec form with sh -c: home=/root

The first line expanded $(whoami) and $HOME. The second printed $HOME literally. The third, which asks for a shell explicitly, expanded it again.

Which shell? On Linux images the default is ["/bin/sh", "-c"]. On Alpine that is BusyBox ash, and on Debian it is dash, so Bash-only features such as [[ ... ]], arrays and set -o pipefail may not work unless you install and select Bash (see SHELL below).

One RUN, one layer

Every RUN makes a layer, and layers only ever add. A file deleted by a later RUN is hidden but still stored in the earlier layer. That is why chaining commands matters.

Consider installing a package on Debian the careless way, in three steps:

DOCKERFILE
FROM debian:bookworm-slim
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

The rm at the end cleans up, but the package lists that apt-get update downloaded (about 20 MB) are already frozen in the layer from step one. docker history shows it:

CONSOLE
$ docker history badapt --format 'table {{.CreatedBy}}\t{{.Size}}'
CREATED BY                                      SIZE
RUN /bin/sh -c rm -rf /var/lib/apt/lists/* #โ€ฆ   20.5kB
RUN /bin/sh -c apt-get install -y curl # buiโ€ฆ   16MB
RUN /bin/sh -c apt-get update # buildkit        19.8MB
# debian.sh --arch 'amd64' out/ 'bookworm' 'โ€ฆ   85.3MB

The cleanup layer is 20 kB; the 19.8 MB of lists is still there. The fix is to do install and cleanup in a single RUN, chained with &&, so the lists are deleted before the layer is saved:

DOCKERFILE
FROM debian:bookworm-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*

Compared on one machine, the three-step image was about 171 MB, and the chained one about 134 MB (the base image alone is 116 MB), a 37 MB difference for installing one program. The size of the chained version with and without --no-install-recommends differed only by about 1 MB for curl, but for packages with many "recommended" dependencies the flag can save tens of megabytes.

The backslash at the end of a line continues the instruction onto the next line. The convention of starting each continued line with && makes it easy to read and to reorder.

The apt-get rules

For Debian and Ubuntu bases, follow this pattern every time:

  1. apt-get update and apt-get install in the same RUN. If update is its own RUN, Docker may cache that layer for months and a later install runs against a stale package list, then fails with "package not found" or installs an old version.
  2. -y so the command never waits for a keypress (builds are not interactive).
  3. --no-install-recommends to skip optional extras.
  4. Clean up in the same layer: rm -rf /var/lib/apt/lists/*.
  5. Pin versions only when you need reproducibility (curl=7.88.1-10+deb12u8); otherwise rely on the base image tag to fix the release.
  6. Use apt-get, not apt. apt is meant for people and warns that its interface is not stable in scripts.
  7. Sort multi-package lists alphabetically. Duplicates and merge conflicts become obvious.

Alpine has its own equivalent, where --no-cache replaces the update-and-clean dance:

DOCKERFILE
RUN apk add --no-cache curl ca-certificates

The result of the Debian version works: the image can run curl, and the package lists really are gone:

CONSOLE
$ docker run --rm goodapt curl --version | head -1
curl 7.88.1 (x86_64-pc-linux-gnu) libcurl/7.88.1 OpenSSL/3.0.22 ...
$ docker run --rm goodapt ls /var/lib/apt/lists | wc -l
0

When a pipeline hides a failure

A shell pipeline reports the exit status of its last command. That has a nasty consequence in Dockerfiles. Here false always fails, but cat at the end succeeds:

DOCKERFILE
FROM alpine:3.22
RUN false | cat && echo "pipeline hid the failure"
CONSOLE
$ docker build --progress=plain --no-cache -t pipe .
...
#5 0.510 pipeline hid the failure
#5 DONE 0.6s

The build passed, although the first command failed. If that first command were curl https://example.com/install.sh | sh, a network error would give you an image without the software and no complaint. Bash can make a pipeline fail if any stage fails, with set -o pipefail. In a Dockerfile you enable it for every following RUN with the SHELL instruction:

DOCKERFILE
FROM debian:bookworm-slim
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN false | cat && echo "not reached"
CONSOLE
ERROR: process "/bin/bash -o pipefail -c false | cat && echo \"not reached\"" did not complete successfully: exit code: 1

Now the failure stops the build. SHELL changes the shell used by shell-form RUN, CMD and ENTRYPOINT from that line on. Alpine does not include Bash, so on Alpine either apk add bash first or avoid pipelines in RUN. A related tip: add set -eu at the top of long scripts so that errors and unset variables stop the build.

Heredocs for longer scripts

When a RUN grows past three or four lines, backslashes and && get noisy. BuildKit supports heredocs, which let you write a small script in place (they worked in our test with no extra setup on Docker 29):

DOCKERFILE
FROM alpine:3.22
RUN <<EOT
set -eu
echo "step one"
echo "step two"
mkdir -p /opt/demo
EOT
CONSOLE
#6 0.631 step one
#6 0.631 step two

The whole block is one instruction, so it creates one layer. If a command in it fails, set -e stops the script and the build. Heredocs are covered further in BuildKit and buildx.

What to put in a RUN, and what not

  • Do: install packages, create users and directories, compile code, change file permissions, download and verify a tool.
  • Do not: start long-running programs (a RUN that never exits blocks the build), or try to keep a process alive for later instructions. Each RUN starts from the previous layer's files, not its processes.
  • Do not: put secrets in RUN commands or arguments; they stay in the image history. Use BuildKit secret mounts.
  • Do not: RUN cd dir and expect the next instruction to be in dir. Use WORKDIR.
  • Do not: use RUN apt-get upgrade. It makes builds non-reproducible; choose a newer base image tag instead.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between RUN echo $HOME and RUN ["echo", "$HOME"]?

    Shell form runs through /bin/sh -c, which expands variables. Exec form starts the program directly, so $HOME is passed literally.
  2. 2. Why should apt-get update and apt-get install be in the same RUN?

    Docker caches each RUN. A separate update layer may be reused for months, and the following install then works from old package lists.
  3. 3. You run RUN apt-get update in one layer and RUN rm -rf /var/lib/apt/lists/* in a later one. What happens to the image size?

    Layers only add. A deletion in a later layer hides the files but the earlier layer still stores them. Install and clean up in one RUN.
  4. 4. An ARG is declared before FROM. Where can its value be read?

    Arguments before FROM are global and only visible to FROM. Re-declare ARG NAME inside the stage to use the value there.
  5. 5. RUN curl -fsSL https://example.com/tool | tar -xz is used with the default shell. The download fails. What happens to the build?

    Without set -o pipefail (via SHELL ["/bin/bash", "-o", "pipefail", "-c"]), only the last command's status counts. A pipe such as false | cat passes silently without it.

Summary

  • FROM starts a stage from a base image (tag, digest, scratch, or a named earlier stage); only ARG may come before it, and such an argument is visible only to FROM lines.
  • Shell-form RUN goes through /bin/sh -c (variables, pipes and && work); exec form starts the program directly with no expansion.
  • Each RUN is a layer, and layers only grow. Install and clean up in the same RUN.
  • On Debian/Ubuntu use apt-get update && apt-get install -y --no-install-recommends ... && rm -rf /var/lib/apt/lists/* in one instruction; on Alpine use apk add --no-cache.
  • Pipelines hide earlier failures unless pipefail is set, which you can enable with SHELL ["/bin/bash", "-o", "pipefail", "-c"].
  • Use heredocs for multi-line scripts, and never put secrets in RUN.

Next: COPY and ADD