docker image build

Descripción

Important

Esta página se refiere a la implementación heredada (legacy) de docker build, que utiliza el motor de construcción heredado (anterior a BuildKit). Esta configuración solo es relevante si estás construyendo contenedores de Windows.

Para obtener información sobre el comando predeterminado docker build, que utiliza Buildx, consulta docker buildx build.

Cuando se construye con el constructor heredado, las imágenes se crean a partir de un Dockerfile ejecutando una secuencia de commits. Este proceso es ineficiente y lento en comparación con el uso de BuildKit, por lo que esta estrategia de construcción está obsoleta para todos los casos de uso excepto para la construcción de contenedores de Windows. Sigue siendo útil para construir contenedores de Windows porque BuildKit aún no tiene paridad completa de características para Windows.

Las construcciones invocadas con docker build utilizan Buildx (y BuildKit) por defecto, a menos que:

• Estés ejecutando Docker Engine en modo de contenedor de Windows
• Te excluyas explícitamente del uso de BuildKit estableciendo la variable de entorno DOCKER_BUILDKIT=0.

Las descripciones de esta página solo cubren información exclusiva del constructor heredado y casos en los que el comportamiento en el constructor heredado difiere del comportamiento en BuildKit. Para obtener información sobre las características y flags comunes entre el constructor heredado y BuildKit, como --tag y --target, consulta la documentación de docker buildx build.

Contexto de construcción con el constructor heredado

El contexto de construcción es el argumento posicional que pasas al invocar el comando de construcción. En el siguiente ejemplo, el contexto es ., que significa el directorio de trabajo actual.

$ docker build .

Cuando se utiliza el constructor heredado, el contexto de construcción se envía al demonio en su totalidad. Con BuildKit, solo se transmiten los archivos que utilizas en tus construcciones. El constructor heredado no calcula qué archivos necesita de antemano. Esto significa que para construcciones con un contexto grande, la transferencia del contexto puede llevar mucho tiempo, incluso si solo estás utilizando un subconjunto de los archivos incluidos en el contexto.

Al utilizar el constructor heredado, es por lo tanto sumamente importante que consideres detenidamente qué archivos incluyes en el contexto que especificas. Utiliza un archivo .dockerignore para evitar que los archivos y directorios que no requieres en tu construcción sean enviados como parte del contexto de construcción.

Acceder a rutas fuera del contexto de construcción

El constructor heredado generará un error si intentas acceder a archivos fuera del contexto de construcción utilizando rutas relativas en tu Dockerfile.

FROM alpine
COPY ../../some-dir .

$ docker build .
...
Step 2/2 : COPY ../../some-dir .
COPY failed: forbidden path outside the build context: ../../some-dir ()

BuildKit, por otro lado, elimina las rutas relativas principales que atraviesan fuera del contexto de construcción. Reutilizando el ejemplo anterior, la ruta COPY ../../some-dir . se evalúa como COPY some-dir . con BuildKit.

Opciones

Ejemplos

Especificar la tecnología de aislamiento para el contenedor (--isolation)

Esta opción es útil en situaciones en las que estás ejecutando contenedores Docker en Windows. La opción --isolation=<value> establece la tecnología de aislamiento de un contenedor. En Linux, la única opción admitida es default, que utiliza espacios de nombres de Linux. En Microsoft Windows, puedes especificar estos valores:

Opciones de seguridad opcionales (--security-opt)

Este flag solo es compatible con un demonio que se ejecute en Windows y solo admite la opción credentialspec. La opción credentialspec debe tener el formato file://spec.txt o registry://keyname.

Aplastar (squash) las capas de una imagen (--squash) (experimental)

Descripción general

Note

La opción --squash es una característica experimental y no debe considerarse estable.

Una vez construida la imagen, este flag aplasta las nuevas capas en una nueva imagen con una sola capa nueva. El aplastamiento no destruye ninguna imagen existente, sino que crea una nueva imagen con el contenido de las capas aplastadas. Esto hace que parezca que todos los comandos del Dockerfile se crearon con una sola capa. El flag --squash conserva la caché de construcción.

El aplastamiento de capas puede ser beneficioso si tu Dockerfile produce múltiples capas que modifican los mismos archivos. Por ejemplo, archivos creados en un paso y eliminados en otro paso. Para otros casos de uso, el aplastamiento de imágenes puede tener un impacto negativo en el rendimiento. Al descargar una imagen que consta de múltiples capas, el demonio puede descargar capas en paralelo y permite compartir capas entre imágenes (ahorrando espacio).

Para la mayoría de los casos de uso, las construcciones de múltiples etapas (multi-stage) son una mejor alternativa, ya que ofrecen un control más detallado sobre tu construcción y pueden aprovechar futuras optimizaciones en el constructor. Consulta la sección de Construcciones de múltiples etapas para obtener más información.

Limitaciones conocidas

La opción --squash tiene una serie de limitaciones conocidas:

• Al aplastar capas, la imagen resultante no puede aprovechar el uso compartido de capas con otras imágenes y puede utilizar significativamente más espacio. Sigue siendo compatible el uso compartido de la imagen base.
• Al utilizar esta opción, es posible que observes que se utiliza un espacio significativamente mayor debido a que se almacenan dos copias de la imagen, una para la caché de construcción con todas las capas de la caché intactas y otra para la versión aplastada.
• Aunque el aplastamiento de capas puede producir imágenes más pequeñas, puede tener un impacto negativo en el rendimiento, ya que una sola capa tarda más en extraerse y no se puede paralelizar la descarga de una sola capa.
• Al intentar aplastar una imagen que no realiza cambios en el sistema de archivos (por ejemplo, el Dockerfile solo contiene instrucciones ENV), el paso de aplastamiento fallará (ver el problema #33823).

Requisitos previos

El ejemplo de esta página utiliza el modo experimental en Docker 23.03.

Puedes habilitar el modo experimental utilizando el flag --experimental al iniciar el demonio de Docker o estableciendo experimental: true en el archivo de configuración daemon.json.

Por defecto, el modo experimental está desactivado. Para ver la configuración actual del demonio de Docker, utiliza el comando docker version y comprueba la línea Experimental en la sección Engine:

Client: Docker Engine - Community
 Version:           28.5.1
 API version:       1.51
 Go version:        go1.24.8
 Git commit:        e180ab8
 Built:             Wed Oct  8 12:16:17 2025
 OS/Arch:           darwin/arm64
 Context:           desktop-linux

Server: Docker Engine - Community
 Engine:
  Version:          28.5.1
  API version:      1.51 (minimum version 1.24)
  Go version:       go1.24.8
  Git commit:       f8215cc
  Built:            Wed Oct  8 12:18:25 2025
  OS/Arch:          linux/arm64
  Experimental:     true
 [...]

Construir una imagen con el flag --squash

A continuación se muestra un ejemplo de una construcción con el flag --squash. Debajo se presenta el Dockerfile:

FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me

A continuación, construye una imagen llamada test utilizando el flag --squash.

$ docker build --squash -t test .

Una vez completada la construcción, el historial se ve como el siguiente. El historial podría mostrar que el nombre de una capa es <missing> y que hay una nueva capa con el COMENTARIO merge.

$ docker history test

IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
4e10cb5b4cac        3 seconds ago                                                       12 B                merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing>           5 minutes ago       /bin/sh -c rm /remove_me                        0 B
<missing>           5 minutes ago       /bin/sh -c #(nop) ENV HELLO=world               0 B
<missing>           5 minutes ago       /bin/sh -c touch remove_me /remove_me           0 B
<missing>           5 minutes ago       /bin/sh -c echo world >> /hello                 0 B
<missing>           6 minutes ago       /bin/sh -c echo hello > /hello                  0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) CMD ["sh"]                    0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB

Prueba la imagen: comprueba que /remove_me haya desaparecido, asegúrate de que hello\nworld esté en /hello y asegúrate de que el valor de la variable de entorno HELLO sea world.