The Dockerfile ARG Instruction

The short answer

In Docker, the ARG property allows you to define arbitrary variables that will be passed to the Dockerfile at build-time:

ARG variable[=default]

Where:

• variable is the name of the user-defined variable.
• default is the default value of the variable if not specified.

Once defined, these variables can be used within the Dockerfile using the following syntax:

${variable}

And their value can be set using the --build-arg flag of the docker build command as follows:

$ docker build --build-arg variable=value .

For example, let's consider this minimal Dockerfile for building a Node.js application:

ARG NODE_VERSION=14
ARG APP_PORT=3000

FROM node:${NODE_VERSION}

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE ${APP_PORT}

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

The following command will set the NODE\_VERSION variable to 20 and the APP\_PORT variable to 3000, and build the Dockerfile while tagging it node-server:

$ docker build --build-arg NODE_VERSION=20 --build-arg APP_PORT=3000 -t node-server .

Easily retrieve this syntax using Warp's Agent Mode

If you’re using Warp as your terminal, you can easily retrieve this syntax using the Warp Agent Mode feature:

Entering docker build args in the Agent Mode question input will prompt a human-readable step by step guide including code snippets.