Docker Build Args: Explained with Practical Examples

Docker simplifies the process of packaging applications with all their dependencies, ensuring consistency across different environments. One of Docker’s powerful features is the ability to pass arguments to the Dockerfile during the build process using Build Args. These arguments allow developers to customize the build process without modifying the Dockerfile itself, making it more dynamic and reusable.

In this guide, we’ll break down Docker Build Args. You’ll learn what they are, how to use them, and see some real-world examples. 

How Build Args Differ from Environment Variables

• Build Args: Used during the Docker image build. They’re temporary and only exist during the build.
• Environment Variables: Set when the container runs. The running application can access them.

Simple Example:

Let’s look at a basic example. Here’s a Dockerfile using a Build Arg:

# Dockerfile
FROM ubuntu:latest

# Define a Build Arg
ARG USER_NAME

# Use the Build Arg
RUN echo "Hello, $USER_NAME!"

In this Dockerfile, USER_NAME is our Build Arg. We use it in a RUN command to customize the message.

To build the Docker image, run this command:

 # docker build --build-arg USER_NAME=JohnDoe -t hello-user .

Output.

Sending build context to Docker daemon  2.048kB
Step 1/3 : FROM ubuntu:latest
 ---> 5a81c4b8502e
Step 2/3 : ARG USER_NAME
 ---> Running in 836d9ef1ae67
Removing intermediate container 836d9ef1ae67
 ---> 9c6bcf36c4be
Step 3/3 : RUN echo "Hello, $USER_NAME!"
 ---> Running in 7b2c807b2d7c
Hello, JohnDoe!
Removing intermediate container 7b2c807b2d7c
 ---> 36a79b1ae786
Successfully built 36a79b1ae786
Successfully tagged hello-user:latest

Here, you can see the value of USER_NAME was passed during the build. The result is a custom message: “Hello, JohnDoe!”

Using Docker Build Args in a Dockerfile

Now that you know the basics, let’s explore using Docker Build Args.

• Use the ARG keyword in the Dockerfile to define your Build Arg.
• Use $ARG_NAME to reference the Build Arg anywhere in your Dockerfile.

Practical Example:

Let’s tweak our previous example. We’ll set the base image version using a Build Arg:

# Dockerfile
ARG BASE_IMAGE_VERSION=20.04
FROM ubuntu:$BASE_IMAGE_VERSION

ARG USER_NAME
RUN echo "Hello, $USER_NAME! Welcome to Ubuntu $BASE_IMAGE_VERSION."

In this Dockerfile:

• BASE_IMAGE_VERSION is a Build Arg. We’ve set a default value of 20.04.
• USER_NAME is another Build Arg. We use it to greet the user.

You can build the image using the below command:

 # docker build --build-arg BASE_IMAGE_VERSION=22.04 --build-arg USER_NAME=JaneDoe -t custom-ubuntu .

Output.

Sending build context to Docker daemon  2.048kB
Step 1/4 : ARG BASE_IMAGE_VERSION=20.04
 ---> 
Step 2/4 : FROM ubuntu:$BASE_IMAGE_VERSION
 ---> 3b417c00f7a4
Step 3/4 : ARG USER_NAME
 ---> Running in 9e26f7a1b13e
Removing intermediate container 9e26f7a1b13e
 ---> c196d2dcb53b
Step 4/4 : RUN echo "Hello, $USER_NAME! Welcome to Ubuntu $BASE_IMAGE_VERSION."
 ---> Running in 147f63420dc9
Hello, JaneDoe! Welcome to Ubuntu 22.04.
Removing intermediate container 147f63420dc9
 ---> 1fc3bcf7f21b
Successfully built 1fc3bcf7f21b
Successfully tagged custom-ubuntu:latest

Here, we specified Ubuntu 22.04 as the base image. We also greeted JaneDoe. The image is built with those settings, and the output shows the correct message.

Real-World Use Cases for Docker Build Args

Docker Build Args are super handy in real-world scenarios. You can create different versions of the same image by passing them through different Build Args.

Here is an example Dockerfile:

# Dockerfile
ARG ENV=development
FROM ubuntu:latest

ARG APP_PORT=8080
ENV APP_PORT=$APP_PORT

RUN echo "Environment: $ENV, Port: $APP_PORT"

To build a Docker image for production and tag the image as app-prod, pass the following Build Args.

 # docker build --build-arg ENV=production --build-arg APP_PORT=80 -t app-prod .

Output.

Environment: production, Port: 80

To build a Docker image for development and tag the image as app-dev, pass the following Build Args.

 # docker build --build-arg ENV=development --build-arg APP_PORT=8080 -t app-dev .

Output.

Environment: development, Port: 8080

Debugging and Troubleshooting Build Args

Sometimes things go wrong. Here’s how to debug and troubleshoot Build Args:

1. Verify Build Arg Values:

Use RUN commands to print the values of Build Args during the build.

RUN echo "Building with $APP_ENV environment"

2. Use Verbose Mode:

Enable verbose output during the build with the –progress=plain option.

 # docker build --progress=plain --build-arg APP_ENV=production -t app-prod .

3. Check Your Syntax:

Make sure your Dockerfile syntax is correct. Double-check that you’re referencing Build Args properly.

Conclusion

Docker Build Args are powerful features that make your Docker images more flexible and reusable. By passing values at build time, you can customize your images for different environments and use cases. Start using Docker Build Args in your projects today and see how they simplify your workflow.

Have you tried Docker Build Args? Share your experiences or ask questions in the comments! To learn more about Docker’s best practices, check out our other articles on Docker and containerization.

FAQs