Docker Build Args (ARG)

1. ARG vs. ENV: Understanding the Difference

Before we dive into the syntax, it's crucial to understand the distinction between a build argument (ARG) and an environment variable (ENV). This is a common point of confusion, but the difference is straightforward and centers on the variable's lifecycle.

• ARG (Build-Time): An ARG variable exists only during the image build process (docker build). Once the image is built, the ARG variable is gone. It's used to influence how the image is built.
• ENV (Run-Time): An ENV variable is baked into the image and is available to the application when a container is running from that image. It's used to configure the application at runtime.

The following video offers a great visual explanation of this lifecycle difference.

This distinction is key: use ARG for parameters that affect the build, and ENV for parameters that your application needs when it's running.

2. Defining and Using Build Arguments

Now let's get into the practical application. You can define and use build arguments in your Dockerfile and then pass values to them from the command line or a docker-compose.yml file.

Basic Syntax

In your Dockerfile, you declare a build argument using the ARG instruction. It's good practice to provide a default value.

# Declare a build argument with a default value
ARG PYTHON_VERSION="3.11"

# Use the argument in a FROM instruction
FROM python:${PYTHON_VERSION}-slim

# ... rest of the Dockerfile

When you build the image, you can override this default value using the --build-arg flag.

# Build using the default PYTHON_VERSION (3.11)
docker build -t my-python-app .

# Build with a specific version, overriding the default
docker build --build-arg PYTHON_VERSION="3.12" -t my-python-app .

For a comprehensive guide on the syntax, scoping rules, and use cases, the following article is an excellent resource.

3. Using ARG with Docker Compose

Since you have experience with Docker Compose, you'll appreciate how seamlessly build arguments integrate. You can define them under the build key for a service in your docker-compose.yml file. This is perfect for standardizing build parameters across a development team.

# docker-compose.yml
services:
  webapp:
    build:
      context: ./app
      dockerfile: Dockerfile
      args:
        PYTHON_VERSION: "3.12"
        ENVIRONMENT: "development"
    ports:
      - "8000:8000"

Let's watch a practical demonstration of this.

4. ARG Scoping in Multi-Stage Builds

This is where the previous lesson on multi-stage builds becomes critical. An ARG has a specific scope, and it does not automatically persist across build stages.

The Rule: An ARG declared before a FROM instruction is only in scope for the FROM line itself. To use a build argument inside a stage, you must re-declare it after the FROM.

Here is a typical multi-stage example incorporating this rule:

# Global ARG, usable by any FROM instruction
ARG PYTHON_VERSION=3.12

# --- Build Stage ---
FROM python:${PYTHON_VERSION}-slim AS builder
# Re-declare the ARG to use it inside this stage
ARG PYTHON_VERSION
WORKDIR /app
RUN echo "Building with Python version ${PYTHON_VERSION}"
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

# --- Final Stage ---
FROM python:${PYTHON_VERSION}-slim
# Re-declare the ARG again for this stage
ARG PYTHON_VERSION
WORKDIR /app
RUN echo "Final image is also based on Python ${PYTHON_VERSION}"
COPY --from=builder /app /app
CMD ["python", "app.py"]

ARG APP_VERSION=1.0.0

FROM node:18-alpine AS builder
# ... build steps ...

FROM nginx:1.25-alpine
# Problem: How do you make APP_VERSION available here?
LABEL version="${APP_VERSION}"
COPY --from=builder /app/dist /usr/share/nginx/html

FROM nginx:1.25-alpine
ARG APP_VERSION # This makes the variable available
LABEL version="${APP_VERSION}"
COPY --from=builder /app/dist /usr/share/nginx/html

5. The Security Warning: Never Use ARG for Secrets

Given your interest in cybersecurity, this is the most important takeaway of the lesson. You must not pass secrets (passwords, tokens, API keys) as build arguments.

The reason is that ARG values are recorded in the image's metadata and can be easily inspected by anyone who has access to the image using the docker history command.

This short video provides a stark demonstration of the risk.

For handling secrets during the build, you should use more secure mechanisms like BuildKit's secret mounts. We will cover these advanced security topics in a later module. For now, the critical rule is: ARG is for non-sensitive, build-time configuration only.

Conclusion

You've now added another essential tool to your Dockerfile toolkit. By parameterizing your builds with ARG, you can create flexible, reusable, and CI/CD-friendly Dockerfiles.

Key Takeaways:

• ARG is for passing build-time variables, while ENV is for providing run-time variables to your container.
• You can set default ARG values in the Dockerfile and override them with the --build-arg flag or via docker-compose.yml.
• In multi-stage builds, ARGs must be re-declared in each stage after the FROM instruction to be used within that stage.
• Crucially, never use ARG for secrets, as they are exposed in the image history.

In our next lesson, we will learn how to configure container health checks using the HEALTHCHECK instruction. This tells Docker how to verify that your application inside the container is not just running, but is actually working correctly—a vital feature for building reliable, orchestrated systems.