# docker image build **Descripción:** Construye una imagen a partir de un Dockerfile **Uso:** `docker image build [OPTIONS] PATH | URL | -` **Alias:** `docker build`, `docker builder 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`](/reference/cli/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](/reference/cli/docker/container/commit/). 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`](/reference/cli/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. ```console $ 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`](/build/concepts/context/#dockerignore-files) 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. ```dockerfile FROM alpine COPY ../../some-dir . ``` ```console $ 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 | Opción | Predeterminado | Descripción | | ------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | `--add-host` | | Añade una asignación personalizada de host a IP (`host:ip`) | | `--build-arg` | | Establece variables en tiempo de construcción | | `--cache-from` | | Imágenes a considerar como fuentes de caché | | `--cgroup-parent` | | Establece el cgroup primario para las instrucciones `RUN` durante la construcción | | `--compress` | | Comprime el contexto de construcción utilizando gzip | | `--cpu-period` | | Limita el período del programador completamente justo (CFS) de la CPU | | `--cpu-quota` | | Limita la cuota del programador completamente justo (CFS) de la CPU | | `-c`, `--cpu-shares` | | Cuotas de CPU (peso relativo) | | `--cpuset-cpus` | | CPUs en las que se permite la ejecución (0-3, 0,1) | | `--cpuset-mems` | | Memoria (MEMs) en las que se permite la ejecución (0-3, 0,1) | | `-f`, `--file` | | Nombre del Dockerfile (el valor predeterminado es `PATH/Dockerfile`) | | `--force-rm` | | Elimina siempre los contenedores intermedios | | `--iidfile` | | Escribe el ID de la imagen en el archivo | | `--isolation` | | Tecnología de aislamiento del contenedor | | `--label` | | Establece metadatos para una imagen | | `-m`, `--memory` | | Límite de memoria | | `--memory-swap` | | Límite de intercambio (swap) igual a la memoria más el intercambio: -1 para habilitar intercambio ilimitado | | `--network` | | API 1.25+ Establece el modo de red para las instrucciones RUN durante la construcción | | `--no-cache` | | No utiliza la caché al construir la imagen | | `--platform` | | API 1.38+ Establece la plataforma si el servidor tiene capacidad multiplataforma | | `--pull` | | Intenta siempre descargar (pull) una versión más reciente de la imagen | | `-q`, `--quiet` | | Suprime la salida de la construcción e imprime el ID de la imagen en caso de éxito | | `--rm` | `true` | Elimina los contenedores intermedios después de una construcción exitosa | | `--security-opt` | | Opciones de seguridad | | `--shm-size` | | Tamaño de `/dev/shm` | | `--squash` | | API 1.25+ **experimental (demonio)** Aplana (squash) las capas recién construidas en una sola capa nueva | | `-t`, `--tag` | | Nombre y opcionalmente una etiqueta en el formato `nombre:etiqueta` | | `--target` | | Establece la etapa de construcción de destino a construir. | | `--ulimit` | | Opciones de ulimit | ## Ejemplos ### Especificar la tecnología de aislamiento para el contenedor (--isolation) {#isolation} Esta opción es útil en situaciones en las que estás ejecutando contenedores Docker en Windows. La opción `--isolation=` 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: | Valor | Descripción | |:----------|:-------------------------------------------------------------------------------------------| | `default` | Utiliza el valor especificado por la opción `--exec-opt` del demonio de Docker o el valor predeterminado del sistema. Si el demonio no especifica una tecnología de aislamiento, Windows utiliza `process` como su valor predeterminado. | | `process` | Únicamente aislamiento de espacios de nombres. | | `hyperv` | Aislamiento basado en particiones del hipervisor Hyper-V. | ### Opciones de seguridad opcionales (--security-opt) {#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) {#squash} #### 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](/build/building/multi-stage/) 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](https://github.com/moby/moby/issues/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`: ```console 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`: ```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`. ```console $ 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 `` y que hay una nueva capa con el COMENTARIO `merge`. ```console $ docker history test IMAGE CREATED CREATED BY SIZE COMMENT 4e10cb5b4cac 3 seconds ago 12 B merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb 5 minutes ago /bin/sh -c rm /remove_me 0 B 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B 5 minutes ago /bin/sh -c touch remove_me /remove_me 0 B 5 minutes ago /bin/sh -c echo world >> /hello 0 B 6 minutes ago /bin/sh -c echo hello > /hello 0 B 7 weeks ago /bin/sh -c #(nop) CMD ["sh"] 0 B 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`.