Docker Build Args: How to Use Build Arguments in Docker and Docker Compose

When building Docker images, you often need to pass in the values that would customize the image without hardcoding them into the Dockerfile. For example, you might want to specify which package version to install, define the build-time variables, or control various features. 

This is where the Docker Build ARGs come in. 

Docker build arguments allow you to supply the dynamic values at build home, making your images more flexible and more reusable. Unlike environment variables, build ARGs are only required during the image build process and do not persist at runtime. 

In this guide, we will explore the build args, how to define them in a Dockerfile, and how to use them with Docker Compose.

Why Use Build Args in Docker?

Using Docker build ARGs has the following benefits: 

• Flexibility in builds; using build arguments allows you to pass variables at build time, making your Dockerfile reusable across multiple different environments. For example, the same Dockerfile can be utilized for development, testing, and production without changing the file. 
• Dynamic Configuration; with dynamic configurations, you can set versions, URLs, or feature flags. For example, ARG NODE_VERSION=18 lets you choose which Node.js version to install during the build.
• Safer Handling of Sensitive Data; Unlike other ARG values do not persist in the final image, so temporary secrets are only used during builds. 
• Integration with CI/CD; Build ARGs make it simpler to pass variables from the pipelines without editing the Dockerfile, enabling automated and consistent builds. 

Docker Build Args vs ENV Variables

Both Docker Build ARGs and ENV variables enable you to define values in the Dockerfile, they both serve different purposes. Build ARGs only work during the build process and do not persist in the final image, which makes it ideal for temporary or dynamic configuration. ENV variables on the other hand makes them suitable for settings where the container needs it while running. 

For example:

ARG APP_VERSION=1.0

ENV APP_NAME=myapp

RUN echo “Building $APP_NAME version $APP_VERSION”

• APP_VERSION is build-time only, won’t be in the container.
• APP_NAME will be available inside the container when it runs.

How to Use Build Args in Docker

Docker Build ARGs enable you to pass variables to your Docker image during the build process. They are defined in the Dockerfile with the ARG instruction and can be overridden at build with –build-arg option. 

Using the Docker Build ARGs makes your Dockerfile even more flexible, allowing you to customize the builds for different environments, software versions, or configurations without changing the Dockerfile in itself. 

Defining ARG in Dockerfile

First, define a build argument in a Dockerfile. You can use the following command lines: 

ARG APP_VERSION=1.0

FROM alpine:latest

RUN echo “Building app version $APP_VERSION”

Here, APP_VERSION is a build-time variable that can be referenced in later instructions such as RUN or ENV.

Passing Args at Build Time

You can then override the default value of a ARG variable during the building phase with the flag: 

docker build –build-arg APP_VERSION=2.0 -t myapp:2.0 .

In this example, the build uses 2.0 instead of the default 1.0. This is useful for building multiple versions of an image from the same Dockerfile.

Setting Default Values for Args

Setting the default value ensures that your Dockerfile can build itself even if the build argument is not provided from before.

For example: 

ARG NODE_VERSION=18

FROM node:$NODE_VERSION

If no NODE_VERSION is passed at build time, Docker uses 18 by default.

Examples of Docker Build Args

Docker Build ARGs are very versatile and can be used for various scenarios. 

• Specifying software versions

ARG NODE_VERSION=18

FROM node:$NODE_VERSION

This command allows you to build images with multiple Node.js versions without making changes to the Dockerfile. 

• Passing build-time configuration

ARG APP_ENV=production

RUN echo “Building app for $APP_ENV environment”

You can build different images for development, testing, or production phases. 

• Downloading packages with temporary tokens

ARG API_KEY

RUN curl -H “Authorization: Bearer $API_KEY” https://example.com/package.tar.gz | tar -xz

Since ARG values do not persist in the final image, sensitive data remains safe.

Inspecting and Debugging Build Args

To verify that all the build arguments are applied in the right manner: 

• Check during build: Use RUN echo to print ARG values.

RUN echo “Using app version $APP_VERSION”

• Check built image: Since ARG values are not present in the final image, so docker inspect will not show them. Only ENV variables persist.
• Debugging tip: Ensure ARG is declared before it’s used in the Dockerfile. Otherwise, it won’t be recognized.

Using Build Args in Docker Compose

Docker Compose allows you to pass the build arguments for multi-service projects. For example: 

version: ‘3.8’

services:

  app:

    build:

      context: .

      dockerfile: Dockerfile

      args:

APP_VERSION: 2.0

Each service defined in the code has its own build ARGs, which makes the builds more flexible for different environments. Build ARGs in Docker Compose are passed at the build phase, similar to the docker build –build-arg.

Best Practices for Docker Build Args

To make the most out of Docker Build ARGs, make sure that follow these best practices: 

• Do not rely on the ARGs for runtime configurations, use ENV for values that containers might need while running. 
• Always clearly define default values to make the brands more solid and easy to share.
• For variables that are required both during the build and runtime, define the ARG first and then pass it onto the ENV.
• Keep secrets in the Docker Build ARGs if they are only needed once. 
• Clearly comment and document each Argument in the Dockerfile to make builds easy to maintain. 

Common Mistakes and How to Avoid Them

Mistake	Description	How to Avoid
Expecting ARG to persist	ARG values do not exist in the running container	Use ENV if the variable is needed at runtime
Using ARG before declaration	Docker will fail if ARG is used before being defined	Declare ARG before any instruction that uses it
Hardcoding sensitive info	Risk of exposing secrets in images	Use ARG for build-time secrets or Docker secrets for runtime secrets
Ignoring default values	Builds fail if ARG not passed	Always set reasonable default values for ARGs
Confusing ARG and ENV	Using ARG instead of ENV for runtime configuration	Understand scope differences: ARG = build-time, ENV = runtime

Conclusion

Docker Build ARGs is a powerful utility that can make the Dockerfile flexible, reusable, and easily maintainable. They offer dynamic configurations, which make it easily integrable with Docker Compose. 

FAQs