Day 29intermediateMar 1, 2026

ARG vs ENV in Dockerfiles — The Key Difference

Mixing up ARG and ENV means your config either disappears at runtime or leaks into your image.

dockerdockerfileconfiguration

What

ARG defines variables available only during the docker build process. ENV sets environment variables that persist into the running container. ARG values are not available as environment variables at runtime, while ENV values become part of the container's environment. Note: ARG values can still be seen in image metadata via docker history — neither ARG nor ENV should be used for real secrets. Use BuildKit secrets (--mount=type=secret) instead.

Why It Matters

Using the wrong instruction leads to subtle bugs. An ARG-based config vanishes at runtime, causing mysterious crashes. An ENV used for build-only secrets gets baked into the image and exposed to anyone who inspects it. Understanding the lifecycle of each prevents both categories of problems.

Example

# ARG: build-time only (not in running container)
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-slim

# ENV: persists into running container
ENV NODE_ENV=production
ENV PORT=3000

# Combining ARG and ENV
ARG APP_VERSION
ENV APP_VERSION=${APP_VERSION}

# Build with custom args
# docker build --build-arg APP_VERSION=1.2.3 --build-arg NODE_VERSION=18 .

# Verify at runtime
# docker run myapp env | grep APP_VERSION
# Output: APP_VERSION=1.2.3

dockerfile

Common Mistake

Using ARG for values needed at runtime, like database URLs or feature flags. The ARG value disappears once the build finishes, so the running container never sees it.

Quick Fix

If a value is needed when the container runs, use ENV. If it's only needed during the build (like choosing a base image version), use ARG. To pass a build-time value into runtime, combine them: ARG MY_VAR then ENV MY_VAR=${MY_VAR}.