What ARG actually is

ARG is a Dockerfile instruction that defines a variable a person or a build system can pass in at the moment an image is being built, using a flag like --build-arg. Think of it as a form field on the front door of the build process. Before Docker starts stacking layers, it asks, “Do you want to fill in any of these blanks?” Once the build finishes and the image is sealed up, that form is thrown away. The value never automatically becomes part of the finished image, and it is never available to a container running from that image unless you deliberately copy it somewhere else.

What ENV actually is

ENV is a Dockerfile instruction that sets an environment variable that becomes a permanent, visible property of the image itself. Every container started from that image inherits it automatically, the same way every employee who joins a company inherits the badge policy written into the employee handbook — nobody has to re-explain it each time someone starts a new shift. An ENV value is baked into the image metadata, so tools like docker inspect can read it, and any process running inside the container can read it too, without anyone doing anything special.

Why Docker needs both at all

A container image serves two very different audiences. During the build, the audience is the build engine itself and whoever triggered the build — a developer typing a command, or a CI pipeline substituting a version number. After the build, the audience is the running application and whoever operates it in production. ARG speaks to the first audience. ENV speaks to the second. Keeping them separate means a Dockerfile can accept build-time choices (which base image version to use, which internal package registry to pull from) without those choices leaking into the final, shipped artifact as if they were application settings.

A Docker build is not one single operation; it is a small pipeline made of distinct components, and ARG and ENV attach to different parts of that pipeline.

Notice the pattern: ARG lives entirely on the left side of this pipeline, in the builder’s working memory. ENV crosses all the way to the right side, into the image manifest and, from there, into every container. That single architectural fact — which component a value is allowed to reach — is the root cause of almost every behavioral difference discussed in this guide.

How ARG resolves

When the builder hits an ARG line, it checks three sources in order: a value passed on the command line, a default written directly after the variable name in the Dockerfile, or — if neither exists — an empty value. Whatever it resolves to becomes available only for instructions that come after that line, and only within that build stage. Crucially, this resolved value is treated as build-time data: the builder can substitute it into later instructions (for example, choosing which base image tag to pull), but it does not, by itself, write anything into the environment that a future container will inherit.

How ENV resolves

When the builder hits an ENV line, it does two things at once: it makes the variable available to every subsequent instruction in that stage, just like ARG would, and it permanently records that key-value pair into the image’s configuration object. That second part is the one ARG never does. From this point forward, the variable is not a build-time convenience — it is a committed property of the image, the same way a paint color becomes a permanent property of a car once it leaves the factory line.

The bridge between them

Because ARG values vanish after the build and ENV values persist, teams that want a build-time choice to also be visible at runtime combine the two deliberately: declare an ARG, then assign it to an ENV variable on the very next line. That single hand-off is the most common pattern in production Dockerfiles, and it is worth internalizing early because most of the “advanced” patterns later in this guide are variations on it.

Imagine a team building a Node.js application image and wanting to control which Node.js version gets installed, while also wanting the application itself to know which environment — staging or production — it is running in. The first value is a build-time decision. The second value is a runtime fact the application needs. Tracing both through the pipeline shows exactly where ARG and ENV diverge.

flowchart TD
    A["Developer runs: docker build --build-arg NODE_VERSION=18"] --> B["Builder reads ARG NODE_VERSION instruction"]
    B --> C["ARG value 18 used to pick base image tag"]
    C --> D["Image layers assembled"]
    D --> E["ENV APP_ENV=production instruction runs"]
    E --> F["APP_ENV written into image config"]
    F --> G["docker build finishes: final image created"]
    G --> H["NODE_VERSION value is gone - never stored in image"]
    G --> I["APP_ENV=production stored permanently in image config"]
    I --> J["docker run starts a container"]
    J --> K["Container inherits APP_ENV=production automatically"]
    H -.->|"not available"| J
    

Two things stand out in this flow. First, the build-time ARG did real, meaningful work — it changed which base image got used — before it vanished. It was not wasted; it simply finished its job at build time and had nothing left to do at runtime. Second, the ENV value made exactly one hop, from a Dockerfile instruction into the image config, and from there it is copied automatically into every container without any extra instruction needed. Once you can trace this diagram from memory, most Dockerfile debugging involving these two instructions becomes straightforward: ask “is this value supposed to still exist after the build finished?” and the answer tells you which instruction you needed.

The trade-off in one sentence: ARG trades permanence for flexibility at build time, and ENV trades flexibility for guaranteed availability at runtime. Choosing correctly usually just means asking whether the value should still exist tomorrow, in every copy of the image, on every machine it gets pulled to.

A surprisingly common mistake is passing a database password, an API key, or a signing certificate into an image using either --build-arg or a plain ENV line, under the assumption that it stays private because it “isn’t in the source code.” Neither assumption holds up. An ENV value is, by design, stored in plain text in the image configuration — anyone who can run docker pull and docker inspect on that image can read it in seconds, no special tools required. An ARG value is somewhat better hidden by default, since it does not automatically land in the final image, but it is frequently still recoverable: it can appear in the build cache, in intermediate layer history depending on how the build was structured, and in CI logs if the build command itself is echoed. Companies including Docker’s own security team and major cloud providers have published guidance specifically warning against using either instruction to pass credentials.

The safe pattern for actual secrets is to avoid both plain ARG and plain ENV for anything sensitive, and instead use a dedicated build-time secrets mechanism (such as BuildKit’s mount-based secrets feature) that never gets written into any layer at all, or to inject the secret only at container-start time through the orchestrator’s own secret-management system (Kubernetes Secrets, a cloud provider’s secret manager, or a runtime -e flag that is not baked into the image). The rule of thumb worth remembering: if a value must never be readable by anyone who obtains the image, it does not belong in an ARG or an ENV line at all.