ARG and ENV instructions in Docker - Deep Dive

Overview - ARG and ENV instructions

What is it?

ARG and ENV are instructions used in Dockerfiles to define variables. ARG sets build-time variables that exist only while building the image. ENV sets environment variables that persist in the running container. These variables help customize the image and container behavior without hardcoding values.

Why it matters

Without ARG and ENV, Docker images would be rigid and hard to customize. Developers would need to create many images for small changes or manually configure containers after starting them. ARG and ENV make images flexible, reusable, and easier to maintain, saving time and reducing errors.

Where it fits

Learners should know basic Dockerfile structure and image building before this. After mastering ARG and ENV, they can learn about Docker Compose, multi-stage builds, and container runtime configuration for advanced container management.

Mental Model

Core Idea

ARG defines temporary build-time variables, while ENV defines persistent runtime environment variables inside Docker containers.

Think of it like...

ARG is like a recipe note you use only while cooking, but ENV is like a label on the finished dish that tells you how to serve it.

Dockerfile
├── ARG <name>=<default>  (build-time variable, temporary)
├── ENV <name>=<value>    (runtime variable, persistent)
|
Build phase: ARG used only here
|
Run phase: ENV available inside container

Build-Up - 7 Steps

1

Foundation

Understanding ARG basics

Concept: ARG defines variables available only during image build.

In a Dockerfile, ARG lets you declare a variable with an optional default value. You can use it in later instructions during build. For example: ARG VERSION=1.0 RUN echo "Building version $VERSION" This prints the version during build but the variable is not in the final image.

Result

The build output shows 'Building version 1.0'. The variable VERSION is not available after build.

Understanding ARG helps you customize builds without affecting the final container environment.

2

Foundation

Understanding ENV basics

Concept: ENV sets environment variables that exist inside the running container.

ENV defines variables that persist in the container after it starts. For example: ENV APP_ENV=production Inside the container, any process can read APP_ENV. This helps configure app behavior at runtime.

Result

When the container runs, the environment variable APP_ENV is set to 'production'.

Knowing ENV lets you control container behavior dynamically without changing the image.

3

Intermediate

Using ARG with docker build command

🤔Before reading on: Do you think ARG variables can be overridden during docker build? Commit to your answer.

Concept: ARG variables can be overridden at build time using --build-arg option.

You can pass a different value for ARG when building: docker build --build-arg VERSION=2.0 . This overrides the default VERSION=1.0 in the Dockerfile. The build uses VERSION=2.0 instead.

Result

The build output shows 'Building version 2.0' instead of the default.

Knowing how to override ARG at build time makes your builds flexible and reusable.

4

Intermediate

ENV variables can use ARG values

🤔Before reading on: Can ENV variables be set using ARG values? Commit to your answer.

Concept: You can use ARG values to set ENV variables during build, combining build-time and runtime configs.

Example: ARG VERSION=1.0 ENV APP_VERSION=$VERSION This sets APP_VERSION inside the container to the build-time VERSION value.

Result

Inside the container, APP_VERSION is set to the value passed to VERSION during build.

Combining ARG and ENV lets you pass build-time info into the running container environment.

5

Intermediate

Scope and lifetime differences

Concept: ARG variables exist only during build; ENV variables exist in the container runtime.

ARG variables disappear after build finishes. ENV variables stay in the image and container. For example, you cannot access ARG inside a running container, but ENV is always accessible.

Result

Trying to echo an ARG variable inside a running container returns empty, but ENV variables show their values.

Understanding variable lifetimes prevents confusion about where and when variables are accessible.

6

Advanced

Security considerations with ARG and ENV

🤔Before reading on: Do you think ARG and ENV variables are secure ways to store secrets? Commit to your answer.

Concept: ARG and ENV are not secure for secrets because they can be inspected in image history or container environment.

ARG values appear in image build history and ENV variables are visible inside containers. For secrets, use Docker secrets or external vaults instead.

Result

Secrets stored in ARG or ENV can be exposed unintentionally, risking security breaches.

Knowing the security limits of ARG and ENV helps avoid accidental leaks of sensitive data.

7

Expert

Subtle behavior with multi-stage builds

🤔Before reading on: Does ARG persist across multi-stage builds automatically? Commit to your answer.

Concept: ARG variables must be re-declared in each build stage; they do not automatically carry over.

In multi-stage Dockerfiles: FROM base AS builder ARG VERSION=1.0 FROM base AS final # VERSION is not available here unless re-declared ARG VERSION ENV APP_VERSION=$VERSION You must declare ARG in each stage to use it.

Result

Without re-declaring ARG, the variable is empty in later stages, causing unexpected behavior.

Understanding ARG scope in multi-stage builds prevents subtle bugs in complex Dockerfiles.

Under the Hood

During docker build, ARG variables are substituted by the Docker engine only in the build context. They do not become part of the image layers. ENV variables are written into image metadata and become part of the container's environment when it runs. The Dockerfile parser processes ARG first, then ENV, resolving variables accordingly.

Why designed this way?

Separating build-time and runtime variables allows flexibility and security. Build-time variables customize image creation without bloating the image or exposing sensitive data at runtime. Runtime variables configure container behavior dynamically. This design balances customization and image size.

Docker Build Process
┌───────────────┐
│ Dockerfile    │
│ ┌───────────┐ │
│ │ ARG VARS  │ │  <-- Used only during build
│ └───────────┘ │
│ ┌───────────┐ │
│ │ ENV VARS  │ │  <-- Stored in image metadata
│ └───────────┘ │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Docker Image  │
│ ENV variables │  <-- Available at container runtime
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can ARG variables be accessed inside a running container? Commit yes or no.

Common Belief: ARG variables are available inside the running container just like ENV variables.

Reality: ARG variables exist only during build and are not present in the running container environment.

Why it matters: Assuming ARG is available at runtime leads to bugs where expected variables are missing inside containers.

Quick: Are ENV variables secure places to store passwords? Commit yes or no.

Common Belief: ENV variables are safe to store secrets like passwords or API keys.

Reality: ENV variables can be viewed by anyone with container access or by inspecting the image, so they are not secure for secrets.

Why it matters: Storing secrets in ENV risks accidental exposure and security breaches.

Quick: Do ARG variables automatically carry over between multi-stage build stages? Commit yes or no.

Common Belief: ARG variables declared in one stage are automatically available in all subsequent stages.

Reality: ARG variables must be declared in each stage separately; they do not persist across stages automatically.

Why it matters: Not re-declaring ARG in each stage causes empty or missing variables, leading to build failures or wrong configurations.

Quick: Does setting ENV overwrite ARG values during build? Commit yes or no.

Common Belief: ENV variables override ARG variables if they have the same name.

Reality: ARG and ENV are separate; ENV can use ARG values but does not overwrite ARG. ARG is only build-time, ENV is runtime.

Why it matters: Confusing ARG and ENV leads to unexpected variable values and container behavior.

Expert Zone

1

ARG variables can be used to reduce image size by conditionally including build steps, but misuse can cause cache invalidation.

2

ENV variables set in Dockerfile can be overridden at container runtime with docker run -e, allowing flexible container configuration.

3

Using ARG in combination with multi-stage builds requires careful re-declaration to avoid subtle bugs in complex images.

When NOT to use

Do not use ARG or ENV to store sensitive secrets; use Docker secrets or external vaults instead. Avoid ARG for runtime configuration since it is not available after build. For dynamic runtime configs, prefer ENV or external config files.

Production Patterns

In production, ARG is often used to pass build versions or flags, while ENV configures app modes (dev, prod). Multi-stage builds use ARG to control build dependencies. ENV variables are overridden at runtime for environment-specific settings without rebuilding images.

Connections

Environment Variables in Operating Systems

ARG and ENV in Docker mirror OS environment variables but differ in scope and lifetime.

Understanding OS environment variables helps grasp how ENV configures container processes similarly.

Build-Time vs Runtime Configuration

ARG represents build-time config, ENV represents runtime config, illustrating a common software deployment pattern.

Knowing this separation clarifies why some settings must be fixed at build and others remain flexible at runtime.

Software Compilation Flags

ARG is like compile-time flags in programming languages that affect how software is built but not how it runs.

Recognizing this analogy helps understand why ARG variables do not persist after build.

Common Pitfalls

#1 Trying to access ARG variables inside a running container.

Wrong approach:

docker run myimage sh -c 'echo $VERSION' # expecting ARG VERSION here

Correct approach:

Use ENV to set variables for runtime:
ENV VERSION=1.0
Then run:
docker run myimage sh -c 'echo $VERSION'

Root cause:

Misunderstanding that ARG is only for build-time and not included in container environment.

#2 Not re-declaring ARG in each stage of a multi-stage build.

Wrong approach:

FROM base AS builder
ARG VERSION=1.0
FROM base AS final
# no ARG VERSION here
ENV APP_VERSION=$VERSION

Correct approach:

FROM base AS builder
ARG VERSION=1.0
FROM base AS final
ARG VERSION
ENV APP_VERSION=$VERSION

Root cause:

Assuming ARG variables persist across stages without explicit declaration.

#3 Storing sensitive secrets in ENV variables.

Wrong approach:

ENV DB_PASSWORD=supersecret

Correct approach:

Use Docker secrets or external vaults to manage sensitive data securely.

Root cause:

Believing ENV variables are private and secure inside containers.

Key Takeaways

ARG variables are only available during image build and cannot be accessed inside running containers.

ENV variables persist in the image and container, configuring runtime behavior dynamically.

ARG can be overridden at build time with --build-arg, making builds flexible and reusable.

In multi-stage builds, ARG must be declared in each stage to be accessible.

Neither ARG nor ENV should be used to store secrets; use dedicated secret management tools instead.