Tutorial de docker build: opciones y ejemplos

docker build construye una imagen a partir de un Dockerfile. Para la sintaxis del Dockerfile, consulta Introducción a Dockerfile y la Guía completa de instrucciones de Dockerfile. Esta página trata las opciones del comando.

Sintaxis

docker build [OPCIONES] RUTA | URL | -

La forma más habitual es:

docker build -t myapp:1.0 .

-t da nombre a la imagen. El . final es el contexto de compilación: los archivos del directorio actual se envían al builder, y por defecto Docker también lee el Dockerfile de ahí. docker build, docker buildx build y docker image build son el mismo comando.

Opciones habituales

Ejecuta docker build --help para ver la lista completa.

Proyecto de ejemplo

Todos los ejemplos siguientes usan este Dockerfile multietapa:

FROM alpine:3.23 AS base
ARG GREETING=hello
RUN echo "$GREETING from build" > /greeting.txt

FROM base AS test
RUN cat /greeting.txt && echo "tests passed"

FROM base
CMD ["cat", "/greeting.txt"]

También hay un Dockerfile.dev que solo contiene FROM alpine:3.23 y CMD ["echo", "dev image"].

-t: construir y nombrar una imagen

$ docker build -t greet .

[+] Building 0.6s (6/6) FINISHED                                                                                                       docker:default
 => [internal] load build definition from Dockerfile                                                                                             0.0s
 => => transferring dockerfile: 235B                                                                                                             0.0s
 => [internal] load metadata for docker.io/library/alpine:3.23                                                                                   0.1s
 => [internal] load .dockerignore                                                                                                                0.0s
 => => transferring context: 2B                                                                                                                  0.0s
 => CACHED [base 1/2] FROM docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                 0.0s
 => => resolve docker.io/library/alpine:3.23@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0                             0.0s
 => [base 2/2] RUN echo "hello from build" > /greeting.txt                                                                                       0.3s
 => exporting to image                                                                                                                           0.1s
 => => exporting layers                                                                                                                          0.0s
 => => exporting manifest sha256:0d0e8696cb61970ffeebe21706f795d44bb7fdb22662a328bd83a22c9cb91d60                                                0.0s
 => => exporting config sha256:04f0467aef1baf360852e9f8633e676c7cbbcbe454d0827bbdd474dcda4a7d1f                                                  0.0s
 => => exporting attestation manifest sha256:186d1197793b26cefb32e3555067d8caaa7d626310efb2c1eeb6c42bfefb01a1                                    0.0s
 => => exporting manifest list sha256:2632bf33adbcb3cffc3697245d5e0ad0d239b58b46413d39f87e29cbbebfb3ef                                           0.0s
 => => naming to docker.io/library/greet:latest                                                                                                  0.0s
 => => unpacking to docker.io/library/greet:latest                                                                                               0.0s

$ docker run --rm greet
hello from build

[base 2/2] indica el segundo paso de la etapa base. La etapa test no se construyó: si no indicas --target, Docker construye solo la última etapa y las etapas de las que depende.

--build-arg: pasar un argumento de compilación

$ docker build -q --build-arg GREETING=hi -t greet:hi .
sha256:c6f108c2247535f2ee548ef5868bdf83911f06e7ecfeab0fb58eb47b19c79154

$ docker run --rm greet:hi
hi from build

El valor por defecto de GREETING es hello. Al sobrescribirlo con --build-arg GREETING=hi, el archivo generado contiene hi from build. ARG solo existe durante la compilación, así que no lo uses para pasar contraseñas (el motivo está en Buenas prácticas de seguridad).

-f: indicar el Dockerfile

$ docker build -q -f Dockerfile.dev -t greet:dev .
sha256:59849c87b388414a149e72c98ff88d30d9b575f5240625c0b8f58332ce5103fb

$ docker run --rm greet:dev
dev image

Un proyecto puede tener varios Dockerfiles, como Dockerfile.dev y Dockerfile.prod. Ten en cuenta que -f solo elige qué Dockerfile leer; el . final sigue siendo el contexto de compilación.

--target y --progress plain: construir solo la etapa de pruebas y ver la salida completa

$ docker build --target test --progress plain --no-cache . 2>&1 | grep -E "^#[0-9]+ [0-9.]+ |DONE|ERROR" | grep -v DONE
#6 0.210 hello from build
#6 0.210 tests passed

• --target test construye solo hasta la etapa test; se usa mucho para ejecutar pruebas en CI.
• --progress plain muestra la salida completa de los comandos RUN (hello from build, tests passed). El modo de salida por defecto la pliega cuando un paso termina bien.
• --no-cache garantiza que RUN se ejecute de verdad en lugar de usar la caché.
• Aquí grep deja solo las líneas de salida de RUN; #6 0.210 significa paso 6, 0,210 segundos después de empezar.

Resultados

$ docker build -q --target base -t greet:base .
sha256:b92f520e3598da9bcb7ceb2cf82977090316062325363faae1d65c3630423b8e

$ docker images greet
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
greet:base     b92f520e3598       12.9MB         3.85MB        
greet:dev      59849c87b388       12.9MB         3.85MB        
greet:hi       c6f108c22475       12.9MB         3.85MB        
greet:latest   2632bf33adbc       12.9MB         3.85MB

Las cuatro imágenes tienen el mismo tamaño porque cada una solo añade un archivo pequeño a Alpine.

Otros usos habituales

# Dar dos nombres a la vez
docker build -t myapp:1.2.0 -t myapp:latest .

# El contexto es un subdirectorio y el Dockerfile está en otro sitio
docker build -f docker/Dockerfile.prod -t myapp ./src

# Volver a descargar la imagen base y no usar la caché (reconstrucción completa)
docker build --pull --no-cache -t myapp .

# Construir para un servidor amd64 (desde un Mac con Apple Silicon)
docker build --platform linux/amd64 -t myapp .

# Usar un secreto durante la compilación
docker build --secret id=npm_token,env=NPM_TOKEN -t myapp .

Capítulos relacionados

• Introducción a Dockerfile, Guía completa de instrucciones de Dockerfile
• Caché de compilación y optimización: cómo funciona la caché
• Compilaciones multietapa: más usos de --target
• Imágenes multiplataforma: --platform
• Mensajes de error comunes: solucionar compilaciones fallidas

Ejercicios

Ejercicio: con el Dockerfile de esta página, construye una imagen con GREETING igual a hey y dale a la vez los nombres greet:hey y greet:latest.

docker build --build-arg GREETING=hey -t greet:hey -t greet:latest .
docker run --rm greet:latest

Actualizado 14 de octubre de 2026