Docker Build Arguments vs Environment Variables — What’s the Difference and When to Use Them?

When working with Docker, understanding the difference between Build Arguments and Environment Variables is key to writing clean, efficient, and customizable Dockerfiles.

In this post, we’ll break them down in plain English:

• 💡 What they are
• 🔄 The difference between them
• ⚙️ How to use each with examples
• 📦 Best practices

Let’s get started!

📌 What Are Build Arguments (ARG)?

Build arguments are variables you can pass at build-time (when you build the image using docker build). They’re useful when you want to customize your image without hardcoding values.

✅ Use Cases:

• Setting versions of software (like Node.js, PHP, etc.)
• Toggling between dev and prod setup at build time
• Avoiding hardcoding values directly in the Dockerfile

🔧 Basic Syntax

In your Dockerfile:

ARG VERSION=16
FROM node:${VERSION}

When building the image:

docker build --build-arg VERSION=18 -t my-node-app .

If you don’t pass a --build-arg, Docker will use the default (16 in this case).

🌍 What Are Environment Variables (ENV)?

Environment variables are values that are available at runtime (when the container is running). You can set them in the Dockerfile or while running the container.

✅ Use Cases:

• Passing API keys, ports, or config settings to your app
• Setting environment like development or production
• Docker Compose service configuration

🔧 Basic Syntax

In your Dockerfile:

ENV PORT=3000
ENV NODE_ENV=production

These values will be accessible inside the container:

echo $PORT
# or
process.env.PORT // in Node.js

You can also override or set them using the docker run command:

docker run -e PORT=4000 -e NODE_ENV=development my-node-app

🔁 Build Args vs Env Vars: Key Differences

🧪 Full Example: Using Both

📁 Dockerfile:

# Build-time variable
ARG NODE_VERSION=18

# Use the build arg to pick a base image
FROM node:${NODE_VERSION}

# Set runtime environment variables
ENV APP_PORT=3000
ENV NODE_ENV=production

WORKDIR /app
COPY . .

RUN npm install

EXPOSE ${APP_PORT}

CMD ["node", "server.js"]

🛠️ Build the image:

docker build --build-arg NODE_VERSION=20 -t my-app .

▶️ Run the container:

docker run -e APP_PORT=8080 -e NODE_ENV=development -p 8080:8080 my-app

Your app will now run with Node.js v20, on port 8080, in development mode.

📦 Setting ENV in Docker Compose

You can also set environment variables in your docker-compose.yml:

services:
  app:
    build:
      context: .
      args:
        NODE_VERSION: 18
    environment:
      - NODE_ENV=production
      - APP_PORT=3000
    ports:
      - "3000:3000"

And optionally define them in a .env file:

NODE_ENV=production
APP_PORT=3000

Docker Compose will automatically read .env values.

🔒 A Note on Secrets

⚠️ Do not use ARG or ENV to store sensitive data like passwords or API keys.

These values can be seen using docker history or by inspecting containers.

Instead, use secure secrets managers (like Docker secrets, AWS Secrets Manager, Vault, etc.) when dealing with production secrets.

✅ Best Practices

• Use ARG for values needed only at build time.
• Use ENV for values used at runtime.
• Set defaults for both ARG and ENV in your Dockerfile.
• Avoid hardcoding — use .env or external config files when possible.
• Keep secrets out of Dockerfiles completely.

📚 Summary

🧠 Final Thoughts

Both ARG and ENV are powerful tools in Docker that help you:

• Write flexible and reusable Dockerfiles
• Keep config out of your app code
• Build images tailored for different environments

Mastering them will level up your Docker skills and help you build production-ready containers like a pro 🛠️