Comprehensive Guide to Docker Build Arguments: Using ARG and --build-arg for Flexible Image Building

Fundamental Concepts of Docker Build Arguments

In the Docker image building process, build arguments serve as a powerful parameterization mechanism that allows dynamic value passing to Dockerfiles during build time. This mechanism is particularly useful for scenarios requiring adjustments to build configurations based on different environments or requirements.

Basic Usage of ARG Instruction

The ARG instruction is used to declare build arguments in Dockerfiles. Its basic syntax is as follows:

ARG parameter_name=default_value

In practical usage, we can define and use build arguments in the following manner:

# Define build argument
ARG package_version="2.3"

# Use build argument in RUN instruction
RUN yum -y install samplerpm-${package_version}

Passing Arguments During Build

When building images, you can override default values defined in Dockerfiles using the --build-arg flag:

docker build --build-arg package_version="2.5" .

This approach enables flexible adjustment of build parameters without modifying the Dockerfile itself.

Differences Between Build Arguments and Environment Variables

Although both build arguments and environment variables can parameterize the build process, they have fundamental differences:

Build Arguments (ARG):

• Available only during the build process
• Not persisted in the final image
• Primarily used for parameterizing Dockerfile instructions
• Can be overridden during build using --build-arg

Environment Variables (ENV):

• Available during both build process and container runtime
• Persisted in the final image
• Mainly used for configuring application runtime environment
• Cannot be directly overridden during build

Scope Rules for Build Arguments

Scope management is a crucial consideration when using build arguments:

Global Scope:

# Build argument defined in global scope
ARG GLOBAL_ARG="default"

FROM alpine
# GLOBAL_ARG is not accessible here
RUN echo "Value: ${GLOBAL_ARG}"

Stage Scope:

FROM alpine
# Declare build argument within build stage
ARG STAGE_ARG="stage_default"
RUN echo "Stage value: ${STAGE_ARG}"

Inheritance Scope:

FROM alpine AS base
ARG BASE_ARG="base_value"

FROM base AS final
# Can access build arguments defined in parent stage
RUN echo "Inherited: ${BASE_ARG}"

Practical Application Examples

Let's demonstrate practical applications of build arguments through a complete example:

# syntax=docker/dockerfile:1

# Define version-related build arguments
ARG NODE_VERSION="20"
ARG ALPINE_VERSION="3.21"

# Use build arguments to specify base image
FROM node:${NODE_VERSION}-alpine${ALPINE_VERSION} AS base
WORKDIR /app

# Redeclare in stage to inherit to subsequent instructions
ARG NODE_VERSION
ARG ALPINE_VERSION

FROM base AS dependencies
COPY package*.json ./
RUN npm ci

FROM base AS production
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
CMD ["node", "server.js"]

During build, you can specify different versions as needed:

docker build --build-arg NODE_VERSION=18 --build-arg ALPINE_VERSION=3.20 .

Combining Build Arguments with Environment Variables

In certain scenarios, we need to pass build argument values to environment variables:

FROM node:20

# Define build argument
ARG NODE_ENV=production

# Assign build argument to environment variable
ENV NODE_ENV=${NODE_ENV}

WORKDIR /app
COPY package*.json ./
RUN npm ci && npm cache clean --force
COPY . .
CMD ["node", "app.js"]

This allows flexible configuration of environment variables during build:

docker build --build-arg NODE_ENV=development .

Security Considerations

When using build arguments, special attention must be paid to security aspects:

• Sensitive Information Protection: Build arguments are not suitable for passing sensitive information like passwords or API keys, as this information may remain in image history
• Alternative Solutions: For sensitive information, it's recommended to use Docker's secret mounts or SSH mounts mechanisms
• History Records: Build argument values may be visible in the output of docker history command

Predefined Build Arguments

Docker provides several predefined build arguments, mainly for multi-platform builds:

# Using predefined multi-platform build arguments
FROM --platform=${BUILDPLATFORM} golang

# Declare in stage to use target platform arguments
ARG TARGETOS
ARG TARGETARCH

RUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /app .

Best Practice Recommendations

Based on real-world project experience, we summarize the following best practices:

1. Meaningful Naming: Use descriptive parameter names like APP_VERSION, DEPENDENCY_VERSION, etc.
2. Provide Default Values: Supply reasonable default values for all build arguments to ensure basic functionality
3. Centralized Definition: Define all build arguments at the beginning of Dockerfile for easier maintenance
4. Scope Management: Redeclare build arguments in different build stages as needed
5. Documentation: Add comments in Dockerfile explaining the purpose and value ranges of each build argument

Conclusion

Docker build arguments provide powerful flexibility and configurability for the image building process. By properly utilizing ARG instructions and --build-arg parameters, developers can create more versatile and maintainable Dockerfiles that adapt to different build requirements and environment configurations. Understanding scope rules, security limitations, and differences from environment variables is crucial for building efficient and secure Docker images.