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.

Practice

1. What is the main difference between ARG and ENV instructions in a Dockerfile?

easy

A. ARG defines build-time variables, ENV defines runtime environment variables.

B. ARG defines runtime environment variables, ENV defines build-time variables.

C. ARG and ENV are exactly the same and interchangeable.

D. ARG is used to set default ports, ENV sets user permissions.

Solution

1. Step 1: Understand ARG usage

   ARG defines variables that are only available during the image build process. They cannot be accessed after the image is built.

2. Step 2: Understand ENV usage

   ENV sets environment variables that persist in the built image and are available at runtime inside containers.

3. Final Answer:

   ARG defines build-time variables, ENV defines runtime environment variables. -> Option A

4. Quick Check:

   ARG = build-time, ENV = runtime [OK]

Hint: Remember: ARG is build-time, ENV is runtime [OK]

Common Mistakes:

• Confusing ARG as runtime variable
• Thinking ENV variables are only for build-time
• Assuming ARG persists in the final image
• Mixing up the purpose of ARG and ENV

2. Which of the following is the correct syntax to declare a build argument named VERSION with a default value 1.0 in a Dockerfile?

easy

A. ARG VERSION : 1.0

B. ENV VERSION=1.0

C. ARG VERSION=1.0

D. ENV VERSION : 1.0

Solution

1. Step 1: Recall ARG syntax

   The correct syntax to declare a build argument with a default value is ARG name=value. So ARG VERSION=1.0 is valid.

2. Step 2: Check other options

   ENV is for environment variables, not build arguments. The colon syntax is invalid in Dockerfile.

3. Final Answer:

   ARG VERSION=1.0 -> Option C

4. Quick Check:

   ARG syntax uses equals sign (=) [OK]

Hint: ARG uses '=' to assign default values [OK]

Common Mistakes:

• Using ENV instead of ARG for build arguments
• Using colon (:) instead of equals (=)
• Omitting the default value syntax
• Confusing ARG and ENV syntax

3. Given the Dockerfile snippet:

ARG APP_VERSION=2.0
ENV APP_VERSION=$APP_VERSION
RUN echo $APP_VERSION

What will be the output of the RUN echo $APP_VERSION command during build if no build argument is passed?

medium

A. Error: variable not found

B. $APP_VERSION

C. empty line

D. 2.0

Solution

1. Step 1: Understand ARG default value

   ARG APP_VERSION=2.0 sets a default build argument value of "2.0" if none is passed.

2. Step 2: ENV uses ARG value

   ENV APP_VERSION=$APP_VERSION sets an environment variable using the ARG value, so it becomes "2.0".

3. Step 3: RUN command output

   RUN echo $APP_VERSION prints the environment variable value "2.0" during build.

4. Final Answer:

   2.0 -> Option D

5. Quick Check:

   ARG default used in ENV, echoed as 2.0 [OK]

Hint: ARG default flows into ENV if no override [OK]

Common Mistakes:

• Expecting empty output if no build arg passed
• Thinking $APP_VERSION is literal string
• Assuming error if variable not passed
• Confusing build-time and runtime variable scopes

4. Identify the error in this Dockerfile snippet:

ARG PORT
ENV PORT=8080
EXPOSE $PORT

medium

A. You cannot use variables in the EXPOSE instruction.

B. The ENV variable PORT overrides ARG but EXPOSE uses $PORT which is not expanded.

C. The ARG variable PORT is not given a default value.

D. The ENV instruction must come before ARG.

Solution

1. Step 1: Check variable usage in EXPOSE

   The EXPOSE instruction does not support variable expansion. Using $PORT will not work.

2. Step 2: Validate other statements

   Not giving a default to ARG PORT is allowed. ENV can override ARG. The order of ARG and ENV is not restricted.

3. Final Answer:

   You cannot use variables in the EXPOSE instruction. -> Option A

4. Quick Check:

   EXPOSE does not expand variables [OK]

Hint: EXPOSE needs literal port numbers, no variables allowed [OK]

Common Mistakes:

• Assuming EXPOSE supports variable expansion
• Thinking ARG must have default value
• Believing ENV must come after ARG
• Confusing build-time and runtime variable scopes

5. You want to build a Docker image that accepts a build argument APP_ENV with default production and sets an environment variable APP_ENV inside the container accordingly. Which Dockerfile snippet correctly achieves this?

hard

A. ENV APP_ENV=production
ARG APP_ENV
ENV APP_ENV=$APP_ENV

B. ARG APP_ENV=production
ENV APP_ENV=$APP_ENV

C. ARG APP_ENV
ENV APP_ENV=production

D. ENV APP_ENV=$APP_ENV
ARG APP_ENV=production

Solution

1. Step 1: Set ARG with default value

   ARG APP_ENV=production defines the build argument with default "production" if none is passed.

2. Step 2: Set ENV using ARG value

   ENV APP_ENV=$APP_ENV sets the runtime environment variable to the ARG value, so it reflects the build argument or default.

3. Step 3: Validate other options

   ENV APP_ENV=production ARG APP_ENV ENV APP_ENV=$APP_ENV sets ENV before ARG which is invalid. ARG APP_ENV ENV APP_ENV=production does not set default for ARG. ENV APP_ENV=$APP_ENV ARG APP_ENV=production uses ENV before ARG which is incorrect.

4. Final Answer:

   ARG APP_ENV=production ENV APP_ENV=$APP_ENV -> Option B

5. Quick Check:

   ARG default then ENV from ARG [OK]

Hint: Declare ARG with default, then ENV using ARG variable [OK]

Common Mistakes:

• Setting ENV before ARG
• Not providing default value for ARG
• Overwriting ENV without ARG reference
• Confusing build-time and runtime variable order