LuisLlamas Logo
dockerfile-arg-env

ARG y ENV en Dockerfile

  • 5 min
  • Avanzado

ARG y ENV en Dockerfile son dos formas distintas de definir variables dentro del proceso de construcción.

Parecen casi lo mismo, porque ambas usan nombres y valores. Pero no lo son.

  • ARG vive durante el build de la imagen
  • Mientras que ENV queda guardado en la imagen final y estará disponible cuando arranque el contenedor.

Esta diferencia es importante. Porque si mezclamos los conceptos, acabamos con Dockerfiles raros, imágenes difíciles de configurar o, peor todavía, secretos y contraseñas metidos dentro de la imagen.

Variables de build y variables de runtime

Lo primero es separar dos momentos distintos:

  1. Build time: cuando Docker construye la imagen con docker build.
  2. Runtime: cuando Docker arranca un contenedor con docker run o docker compose up.

ARG pertenece principalmente al primer momento. Sirve para parametrizar la construcción.

ENV pertenece al segundo momento. Sirve para definir variables disponibles dentro del contenedor.

Podemos resumirlo así:

InstrucciónMomentoQueda en la imagenDisponible en el contenedor
ARGBuildNo como variable finalNo, salvo que la copies a ENV
ENVBuild y runtimeSíSí

Vamos a verlo despacio 👇.

ENV

La instrucción ENV define una variable de entorno dentro de la imagen. Por ejemplo:

ENV NODE_ENV=production
ENV APP_PORT=3000
Copied!

Cuando un contenedor arranque desde esa imagen, tendrá esas variables disponibles.

En una aplicación Node.js, por ejemplo, podríamos leer:

console.log(process.env.NODE_ENV)
console.log(process.env.APP_PORT)
Copied!

Esto es útil para valores que forman parte del comportamiento normal de la imagen:

  1. NODE_ENV=production
  2. ASPNETCORE_URLS=http://+:8080
  3. TZ=Europe/Madrid
  4. rutas como PATH

Es decir, cosas que tienen sentido como valores por defecto de la imagen.

Sobrescribir ENV al arrancar

Que un valor esté definido con ENV no significa que sea inmutable. Podemos sobrescribirlo al arrancar el contenedor:

docker run -e APP_PORT=8080 mi-app
Copied!

El contenedor arrancará con APP_PORT=8080, aunque la imagen tuviera APP_PORT=3000.

Esto está muy bien porque el Dockerfile puede definir un valo :::::r razonable por defecto, y luego cada entorno puede cambiarlo si lo necesita.

Usad ENV para valores por defecto de la imagen, no para valores específicos de vuestro servidor.

Si cambia entre desarrollo, staging y producción, probablemente debería venir desde docker run, Docker Compose o vuestro sistema de despliegue.

ARG

La instrucción ARG define una variable disponible durante la construcción de la imagen. Por ejemplo:

ARG NODE_VERSION=22

FROM node:${NODE_VERSION}-alpine
Copied!

Al construir la imagen, podemos cambiar ese valor:

docker build --build-arg NODE_VERSION=20 -t mi-app .
Copied!

Esto permite construir imágenes parecidas cambiando alguna pieza del proceso.

Por ejemplo:

  1. La versión de Node, Python o .NET.
  2. Una URL desde la que descargar un binario.
  3. Un modo de build.
  4. Un flag para activar o desactivar una parte del proceso.

ARG es como decirle al Dockerfile: “para construir esta imagen, usa este valor”.

ARG no queda disponible al arrancar

Este punto es importante. Si hacemos esto:

ARG APP_VERSION=1.0.0

FROM alpine

RUN echo "Construyendo versión ${APP_VERSION}"
Copied!

APP_VERSION existe durante el build. Pero cuando arranque el contenedor, no existirá como variable de entorno.

Para comprobarlo:

docker build --build-arg APP_VERSION=2.0.0 -t prueba-arg .
docker run --rm prueba-arg env
Copied!

No veréis APP_VERSION en la salida.

Si queréis que un valor de build quede también como variable en el contenedor, tenéis que pasarlo explícitamente a ENV:

ARG APP_VERSION=1.0.0
ENV APP_VERSION=${APP_VERSION}
Copied!

Ahora sí quedará dentro de la imagen final.

## ARG antes y después de FROM|t024626

ARG tiene una pequeña particularidad con FROM. Si queréis usar un argumento dentro de FROM, tenéis que declararlo antes:

ARG NODE_VERSION=22

FROM node:${NODE_VERSION}-alpine
Copied!

Después de FROM, podéis declarar otros ARG para usarlos en las siguientes instrucciones:

FROM node:22-alpine

ARG BUILD_MODE=production

RUN echo "Modo de build: ${BUILD_MODE}"
Copied!

Además, si queréis usar otra vez un ARG declarado antes de FROM dentro de la etapa, conviene redeclararlo después:

ARG NODE_VERSION=22

FROM node:${NODE_VERSION}-alpine

ARG NODE_VERSION
RUN node --version
Copied!

No es lo más bonito del mundo, pero Dockerfile tiene estas pequeñas alegrías.

Ejemplo completo

Vamos a juntar las dos cosas en un Dockerfile sencillo:

ARG NODE_VERSION=22

FROM node:${NODE_VERSION}-alpine

WORKDIR /app

ARG BUILD_MODE=production
ENV NODE_ENV=${BUILD_MODE}
ENV PORT=3000

COPY package*.json ./
RUN npm ci

COPY . .

EXPOSE 3000
CMD ["npm", "start"]
Copied!

Y lo construimos así:

docker build \
  --build-arg NODE_VERSION=20 \
  --build-arg BUILD_MODE=production \
  -t mi-app .
Copied!

Aquí pasan varias cosas:

  1. NODE_VERSION decide qué imagen base usamos.
  2. BUILD_MODE existe durante el build.
  3. NODE_ENV queda guardado en la imagen como variable de entorno.
  4. PORT queda como valor por defecto para el contenedor.

Es un patrón bastante habitual.

No uséis ARG ni ENV para secretos

Ni ARG ni ENV son un buen sitio para contraseñas, tokens o claves privadas.

Con ENV, el problema es evidente: el valor queda dentro de la imagen y puede verse con herramientas como docker inspect.

Con ARG, la cosa es un poco más traicionera. Aunque no quede como variable final del contenedor, puede aparecer en el historial de la imagen o en metadatos del build.

Por tanto, esto está mal:

ARG API_TOKEN=supersecreto
ENV DB_PASSWORD=otraclave
Copied!

Y esto también:

docker build --build-arg API_TOKEN=supersecreto .
Copied!

Si necesitáis secretos durante el build, mirad mecanismos como BuildKit secrets. Si necesitáis secretos al arrancar el contenedor, pasadlos desde el entorno, Docker Compose, un gestor de secretos o la plataforma donde despleguéis.

En esta página