Introduction

You cannot pass a build argument back into the Dockerfile that originally created an already-built parent image. Build arguments exist only while the current image is being built. If you want a child build to influence base-image selection or to reuse a value from the parent, you have to design that explicitly with ARG, ENV, or image tags.

Understand What a "Parent Dockerfile" Really Is

Once a base image has been built, Docker no longer sees the original Dockerfile as a live parent object. The child Dockerfile only sees the resulting image referenced by FROM. That means a command like docker build --build-arg FOO=bar . affects the current build, not the historical Dockerfile that produced my-base:latest.

So the answer depends on what you are really trying to do:

• choose which base image to use
• reuse a value during the current child build
• persist configuration from the base image into the child image

Those are different cases, and Docker handles them differently.

Use ARG to Parameterize the Current Build

If you want to choose the base image dynamically, declare an ARG before FROM and use it in the image reference.

1ARG NODE_VERSION=20
2FROM node:${NODE_VERSION}-alpine
3
4ARG APP_ENV=production
5RUN echo "Building for ${APP_ENV}"

Build it like this:

docker build --build-arg NODE_VERSION=22 --build-arg APP_ENV=staging -t demo .

The NODE_VERSION argument works before FROM because Docker explicitly allows that pattern. The APP_ENV argument is available only after it is declared in the stage where it is used.

Persist Values Explicitly with ENV

If a value needs to survive into descendant images or into the running container, ARG alone is not enough because build arguments are not persisted automatically. The common pattern is to convert a build argument into an environment variable.

1FROM alpine:3.20
2
3ARG APP_HOME=/opt/app
4ENV APP_HOME=${APP_HOME}
5
6RUN mkdir -p "${APP_HOME}"

A child image built from this base can then read APP_HOME because it was baked into the image metadata as an environment variable.

FROM my-base:1.0
RUN echo "Inherited APP_HOME=${APP_HOME}"

That is not "passing an argument to the parent Dockerfile." It is persisting a value in the built parent image so descendants can consume it.

Redeclare ARG in Each Stage That Needs It

This is another place developers get tripped up. In multi-stage builds, an ARG must be declared in each stage where it is referenced.

1ARG ALPINE_VERSION=3.20
2
3FROM alpine:${ALPINE_VERSION} AS build
4ARG APP_ENV=production
5RUN echo "Build stage: ${APP_ENV}"
6
7FROM alpine:${ALPINE_VERSION}
8ARG APP_ENV=production
9RUN echo "Final stage: ${APP_ENV}"

The value can be passed once from the command line, but the ARG instruction still has to appear in every stage that wants to use it.

Common Pitfalls

The biggest mistake is assuming a child Docker build can reach back into the Dockerfile that produced the base image and set its ARG values after the fact. That is not how Docker's build model works.

Another common issue is expecting ARG values to exist at runtime. They do not, unless you explicitly copy them into ENV or another persistent layer.

People also often forget to redeclare ARG after FROM or in a later stage, which makes the value appear to "disappear" even though Docker is following the normal scoping rules.

Summary

• Build arguments affect the current Docker build, not an already-built parent Dockerfile.
• Use ARG before FROM when you want to parameterize base-image selection.
• Use ENV if a value must persist into child images or running containers.
• Redeclare ARG in every stage that needs it.
• Think in terms of image metadata and build scope, not parent-Dockerfile inheritance.