ARG define un argumento que el sistema de construcción puede recibir al crear una imagen Docker. Sirve para parametrizar el Dockerfile, por ejemplo para elegir una versión de una base o controlar una opción de compilación, sin editar el archivo para cada variante.
Su alcance se limita a la construcción: un argumento no queda disponible automáticamente como variable de entorno dentro del contenedor. También hay que respetar su ámbito entre etapas y recordar que los valores de ARG no son un lugar seguro para guardar contraseñas o tokens.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Sintaxis básica de ARG en Dockerfile
Puedes declarar un argumento sin valor predeterminado o asignarle uno. Después puedes pasarlo al builder con la opción correspondiente de Docker:
ARG NOMBRE
ARG NOMBRE=valor
docker build --build-arg NOMBRE=otro-valor -t mi-imagen:local .Explicación de la sintaxis
ARG declara el nombre del argumento. El valor después del signo igual es el predeterminado que se utilizará cuando el build no reciba una sustitución. La opción –build-arg permite reemplazarlo al construir la imagen; solo tiene efecto si el Dockerfile utiliza ese argumento en alguna instrucción.
La variable puede usarse en instrucciones posteriores a su declaración mediante la sintaxis de sustitución de Dockerfile. Si la declaras dentro de una etapa, no existe antes de esa línea. Si la declaras antes del primer FROM, puedes usarla en las instrucciones FROM, pero no queda automáticamente disponible dentro de la etapa.
Comportamiento y límites de ARG
| Aspecto | Comportamiento | Qué debes recordar |
|---|---|---|
| Valor predeterminado | ARG VERSION=24 proporciona un valor cuando no se envía otro. | El build puede sustituirlo con –build-arg. |
| Ámbito global | Un ARG antes del primer FROM puede participar en FROM. | No se hereda automáticamente dentro de la etapa. |
| Ámbito de etapa | Un ARG declarado después de FROM se usa en esa etapa. | En otras etapas independientes hay que declararlo de nuevo. |
| Imagen final | ARG no se convierte por sí mismo en variable de entorno del contenedor. | Usa ENV solo cuando el valor deba persistir en tiempo de ejecución. |
| Caché | Un cambio puede invalidar la caché desde la primera instrucción que use el argumento. | Declara y utiliza solo valores necesarios para ese build. |
| Información sensible | Un valor de ARG puede quedar visible en historial o metadatos de procedencia. | No pases contraseñas, tokens ni claves privadas por ARG. |
Usar ARG para elegir una versión de la imagen base
Un argumento global resulta útil cuando necesitas seleccionar una etiqueta de imagen base. Si quieres reutilizar ese valor dentro de una etapa, vuelve a declarar el nombre después de FROM:
ARG NODE_VERSION=24
FROM node:${NODE_VERSION}-alpine AS build
ARG NODE_VERSION
ARG BUILD_MODE=production
WORKDIR /src
COPY package*.json ./
RUN if [ "$BUILD_MODE" = "production" ]; then npm ci --omit=dev; else npm ci; fi
COPY . .
RUN npm run buildEl primer argumento permite que FROM seleccione la etiqueta de Node. La declaración que aparece después de FROM introduce ese valor en el ámbito de la etapa. BUILD_MODE es un argumento propio de esa etapa y cambia qué dependencias se instalan. El ejemplo requiere un archivo de bloqueo compatible, como package-lock.json, para que npm ci pueda reproducir la instalación.
Construye la variante con un valor concreto. Si no envías NODE_VERSION o BUILD_MODE, se aplican los valores definidos en el Dockerfile:
docker build \
--build-arg NODE_VERSION=24 \
--build-arg BUILD_MODE=production \
-t web:local .Alcance de ARG en etapas múltiples
Cada instrucción FROM inicia una etapa nueva. Los argumentos declarados globalmente se pueden usar para parametrizar las líneas FROM, pero no están dentro de los comandos de la etapa hasta que se declaran allí. Una etapa independiente tampoco hereda argumentos de otra; si ambas parten de una etapa común, pueden heredar los argumentos declarados en esa base.
ARG NODE_VERSION=24
FROM node:${NODE_VERSION}-alpine AS build
ARG NODE_VERSION
RUN node --version
FROM node:${NODE_VERSION}-alpine AS runtime
ARG NODE_VERSION
RUN node --versionEn este ejemplo, ambas instrucciones FROM consumen el valor global y cada etapa declara el argumento antes de usarlo en un comando. Repetir ARG NODE_VERSION no modifica el valor predeterminado: lo incorpora al ámbito local de esa etapa.
Diferencia entre ARG y ENV
ARG configura valores para construir la imagen; ENV establece variables que se conservan en la configuración de la imagen y se entregan a los procesos del contenedor. Si una aplicación necesita el valor al arrancar, puedes transferir un argumento a una variable de entorno de forma explícita, sabiendo que el valor pasará a formar parte de la configuración persistente:
ARG APP_MODE=production
ENV APP_MODE=${APP_MODE}Si solo necesitas elegir una opción durante el build y no quieres dejarla en el entorno final, no la copies a ENV. Para profundizar en esa diferencia, consulta la lección sobre la instrucción ENV.
ARG no es un mecanismo para secretos
No pases contraseñas, tokens o claves con ARG. Aunque el valor no aparezca como una variable de entorno en el contenedor final, puede quedar expuesto en el historial de construcción, metadatos o atestaciones de procedencia. Para entregar credenciales temporalmente a una instrucción de build, utiliza los mounts de secretos de BuildKit, que están diseñados para ese uso.
También evita asumir que cambiar un argumento siempre reconstruye toda la imagen o nunca afecta a la caché. El cambio repercute desde la primera instrucción que consume el valor; organiza el Dockerfile para que los parámetros variables no invaliden pasos costosos innecesariamente.
Errores frecuentes al usar ARG
- Declararlo antes de FROM y usarlo dentro de RUN sin declararlo otra vez: el valor global no se hereda automáticamente en la etapa.
- Esperar que ARG esté disponible al ejecutar el contenedor: si la aplicación necesita el valor en runtime, configura ENV conscientemente o proporciona la variable al iniciar el contenedor.
- Guardar credenciales en argumentos: usa los mounts de secretos de BuildKit en vez de valores que pueden quedar en metadatos.
- Pasar –build-arg sin declarar ni utilizar el nombre: el argumento no cambia el resultado si el Dockerfile no lo consume.
- Usar un ARG variable demasiado pronto: puedes invalidar pasos de caché posteriores desde la primera instrucción que depende de su valor.
Lecciones relacionadas del curso Docker
- Instrucción ENV, para configurar variables que persisten en la imagen y el contenedor.
- RUN –mount=type=secret, para entregar credenciales de forma temporal durante la construcción.
- Cómo funciona la caché de construcción, para entender cuándo un cambio invalida pasos posteriores.
- Qué es un Dockerfile, para repasar cómo se organiza una imagen.
