Tutorial de docker pull: descargar imágenes (--platform, -q y digest específico)

docker pull descarga imágenes de un repositorio de imágenes; consulta Imágenes para aprender sobre las imágenes y las etiquetas.

Sintaxis

docker pull [opciones] NOMBRE[:ETIQUETA|@DIGEST]

Opciones

Ejemplos

Descargar una imagen y volver a descargarla

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
5e9b4a97f639: Pulling fs layer
5e9b4a97f639: Download complete
97ab9557f126: Download complete
79dff55e92ba: Download complete
5e9b4a97f639: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Downloaded newer image for alpine:3.23
docker.io/library/alpine:3.23

$ docker pull alpine:3.23
3.23: Pulling from library/alpine
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

• La primera descarga muestra el progreso de las capas, el digest y el estado Downloaded newer image.
• Al descargarla de nuevo, el digest es el mismo y aparece Image is up to date; no se vuelve a mostrar el progreso de descarga de las capas.
• Si no especificas un registry, el nombre completo que aparece en la salida es docker.io/library/alpine:3.23.

Modo silencioso y etiqueta inexistente

$ docker pull -q redis:8-alpine
docker.io/library/redis:8-alpine

$ docker pull nginx:9.99
Error response from daemon: failed to resolve reference "docker.io/library/nginx:9.99": docker.io/library/nginx:9.99: not found

• -q oculta los detalles, como el progreso de descarga; en este ejemplo, solo muestra el nombre completo de la imagen.
• Si no encuentra la etiqueta 9.99, el daemon devuelve not found e indica la referencia completa de imagen que no pudo resolver.

Especificar una plataforma y consultar sus variantes

$ docker pull --platform linux/arm64 alpine:3.23
3.23: Pulling from library/alpine
197a036d7c64: Pulling fs layer
197a036d7c64: Download complete
4f0cdf9143b4: Download complete
8b7a0920489a: Download complete
197a036d7c64: Pull complete
Digest: sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63
Status: Image is up to date for alpine:3.23
docker.io/library/alpine:3.23

$ docker image inspect -f '{{.Os}}/{{.Architecture}}' alpine:3.23
linux/amd64

$ docker images --tree alpine:3.23
IMAGE                   ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23             ff7f0c727dd7       26.6MB         8.21MB        
├─ linux/amd64          3d67941fed5a       12.9MB         3.85MB        
├─ linux/arm/v6         806bbcf86639           0B             0B        
├─ linux/arm/v7         b43a13ac240c           0B             0B        
├─ linux/arm64/v8       8793abc47938       13.5MB         4.19MB        
├─ linux/386            7811c228ca81           0B             0B        
├─ linux/ppc64le        cc3ef1f3240a           0B             0B        
├─ linux/riscv64        1e12543f1917           0B             0B        
└─ linux/s390x          ac74ebe0c48b           0B             0B        

• --platform linux/arm64 descarga las capas de la versión arm64, pero el estado sigue siendo Image is up to date: alpine:3.23 es una imagen multiplataforma, así que el nombre y el digest no cambian; solo se añade contenido de otra plataforma en tu máquina.
• Por eso, docker image inspect sigue mostrando la plataforma local linux/amd64 de forma predeterminada. Para ver otras plataformas, usa docker images --tree.
• docker images --tree muestra variantes de plataforma como amd64 y arm64/v8; aquí, el uso de disco de arm64/v8 es 13.5MB.

Fijar la versión de una imagen mediante digest

$ docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0: Pulling from library/alpine
d0c1d894c237: Pulling fs layer
d0c1d894c237: Download complete
d836c7fd48f4: Download complete
047d62850641: Download complete
d0c1d894c237: Pull complete
Digest: sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
Status: Downloaded newer image for alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker.io/library/alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0

$ docker images alpine
IMAGE                                                                            ID             DISK USAGE   CONTENT SIZE   EXTRA
alpine:3.23                                                                      ff7f0c727dd7       26.6MB         8.21MB        
alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0   85fe1e81d675         13MB         3.94MB        

• Añade @sha256: y el digest al nombre de la imagen para especificarla mediante su digest en lugar de usar una etiqueta que puede cambiar.
• El Digest de la salida coincide con el digest especificado y el estado es Downloaded newer image.
• docker images alpine muestra tanto alpine:3.23 como la referencia con digest, y sus ID son distintos: este digest corresponde a una versión anterior de 3.23, mientras que la etiqueta 3.23 ya apunta a una compilación más reciente. Por eso conviene fijar la versión mediante digest: las etiquetas pueden cambiar, pero los digest no.

Capítulos relacionados

• Imágenes
• Imágenes multiplataforma
• Docker Hub
• docker push

Ejercicios

Ejercicio: descarga mediante digest la imagen Alpine del enunciado y consulta la lista de imágenes Alpine locales.

docker pull alpine@sha256:85fe1e81d6758c208f3e1eed4338a1997e19d4be002d4dd32d3100c9a8c010a0
docker images alpine

Actualizado 26 de octubre de 2026