ARG and ENV instructions in Docker - Commands & Configuration

Introduction

When building Docker images, you often need to set values that your app or the build process uses. ARG and ENV let you set these values, but they work differently. ARG sets values only during build time, while ENV sets values that stay in the image and are available when running containers.

When you want to pass a secret or variable only during the image build, like a version number or API key.

When you want to set environment variables that your app inside the container will use at runtime.

When you want to have default values that can be overridden when building or running the container.

When you want to keep your Dockerfile flexible and reusable for different environments or versions.

When you want to reduce hardcoding values inside your Dockerfile for easier maintenance.

Config File - Dockerfile

Dockerfile

FROM alpine:3.18

ARG APP_VERSION=1.0.0
ENV APP_ENV=production

RUN echo "Building app version $APP_VERSION"

CMD ["sh", "-c", "echo Running app in $APP_ENV environment"]

FROM alpine:3.18 sets the base image.

ARG APP_VERSION=1.0.0 defines a build-time variable with a default value.

ENV APP_ENV=production sets an environment variable available in the running container.

RUN echo ... uses the ARG variable during build to show the version.

CMD ... uses the ENV variable when the container runs to show the environment.

Commands

Builds the Docker image using the Dockerfile in the current folder. It uses the default ARG value APP_VERSION=1.0.0.

Terminal

docker build -t my-app:1.0 .

Expected Output

Sending build context to Docker daemon  2.048kB

Step 1/5 : FROM alpine:3.18

 ---> 3f53bb00af94

Step 2/5 : ARG APP_VERSION=1.0.0

 ---> Using cache

 ---> 123456789abc

Step 3/5 : ENV APP_ENV=production

 ---> Using cache

 ---> 23456789abcd

Step 4/5 : RUN echo "Building app version $APP_VERSION"

 ---> Running in abcdef123456

Building app version 1.0.0

Removing intermediate container abcdef123456

 ---> 3456789abcde

Step 5/5 : CMD ["sh", "-c", "echo Running app in $APP_ENV environment"]

 ---> Running in 789abcde1234

Removing intermediate container 789abcde1234

 ---> 456789abcdef

Successfully built 456789abcdef

Successfully tagged my-app:1.0

→

-t - Names and tags the image for easy reference

Runs the container from the built image. It prints the environment variable APP_ENV set by ENV.

Terminal

docker run --rm my-app:1.0

Expected Output

Running app in production environment

→

--rm - Automatically removes the container after it exits

Builds the image again but overrides the ARG APP_VERSION to 2.0.0 during build time.

Terminal

docker build --build-arg APP_VERSION=2.0.0 -t my-app:2.0 .

Expected Output

Sending build context to Docker daemon  2.048kB

Step 1/5 : FROM alpine:3.18

 ---> 3f53bb00af94

Step 2/5 : ARG APP_VERSION=1.0.0

 ---> Using cache

 ---> 123456789abc

Step 3/5 : ENV APP_ENV=production

 ---> Using cache

 ---> 23456789abcd

Step 4/5 : RUN echo "Building app version $APP_VERSION"

 ---> Running in abcdef123457

Building app version 2.0.0

Removing intermediate container abcdef123457

 ---> 56789abcdef0

Step 5/5 : CMD ["sh", "-c", "echo Running app in $APP_ENV environment"]

 ---> Running in 89abcdef0123

Removing intermediate container 89abcdef0123

 ---> 6789abcdef01

Successfully built 6789abcdef01

Successfully tagged my-app:2.0

→

--build-arg - Overrides ARG variables during build

Runs the container but overrides the ENV variable APP_ENV to 'development' at runtime.

Terminal

docker run --rm -e APP_ENV=development my-app:2.0

Expected Output

Running app in development environment

→

-e - Sets or overrides environment variables for the running container

→

--rm - Removes the container after it stops

Key Concept

ARG sets build-time variables only available during image build, while ENV sets environment variables available when running containers.

Common Mistakes

Trying to use ARG variables inside the running container.

ARG variables do not persist in the final image and are not available at runtime.

Use ENV to set variables that the container needs when running.

Not overriding ARG with --build-arg during build and expecting a different value.

Without --build-arg, the default ARG value in the Dockerfile is used.

Use --build-arg to pass different values when building the image.

Setting environment variables only with ENV but trying to change them at build time.

ENV variables are baked into the image and cannot be changed during build with --build-arg.

Use ARG for build-time variables and ENV for runtime variables.

Summary

Use ARG to define variables that only exist during the Docker image build process.

Use ENV to set environment variables that containers will use when they run.

Override ARG values during build with --build-arg and override ENV values at runtime with -e.