docker image pull

Descripción

La mayoría de tus imágenes se crearán sobre una imagen base del registro Docker Hub.

Docker Hub contiene muchas imágenes preconstruidas que puedes descargar (pull) y probar sin necesidad de definir y configurar la tuya propia.

Para descargar una imagen en particular, o un conjunto de imágenes (es decir, un repositorio), usa docker pull.

Configuración de proxy

Si estás detrás de un servidor proxy HTTP, por ejemplo en entornos corporativos, es posible que debas configurar el demonio de Docker para usar el servidor proxy en operaciones como la descarga (pull) y subida (push) de imágenes. Consulta la referencia de línea de comandos de dockerd para obtener más detalles.

Descargas simultáneas

Por defecto, el demonio de Docker descarga tres capas de una imagen a la vez. Si tienes una conexión de bajo ancho de banda, esto puede causar problemas de tiempo de espera y es posible que desees reducir este valor a través de la opción del demonio --max-concurrent-downloads. Consulta la documentación del demonio para obtener más detalles.

Opciones

Ejemplos

Descargar una imagen desde Docker Hub

Para descargar una imagen en particular, o un conjunto de imágenes (es decir, un repositorio), usa docker image pull (o el atajo docker pull). Si no se proporciona ninguna etiqueta, Docker Engine utiliza la etiqueta :latest por defecto. Este ejemplo descarga la imagen debian:latest:

$ docker image pull debian

Using default tag: latest
latest: Pulling from library/debian
e756f3fdd6a3: Pull complete
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:latest
docker.io/library/debian:latest

Las imágenes de Docker pueden constar de múltiples capas. En el ejemplo anterior, la imagen consta de una sola capa; e756f3fdd6a3.

Las capas pueden ser reutilizadas por otras imágenes. Por ejemplo, la imagen debian:bookworm comparte su capa con la de debian:latest. Por lo tanto, descargar la imagen debian:bookworm solo descarga sus metadatos, pero no sus capas, porque la capa ya está presente localmente:

$ docker image pull debian:bookworm

bookworm: Pulling from library/debian
Digest: sha256:3f1d6c17773a45c97bd8f158d665c9709d7b29ed7917ac934086ad96f92e4510
Status: Downloaded newer image for debian:bookworm
docker.io/library/debian:bookworm

Para ver qué imágenes están presentes localmente, usa el comando docker images:

$ docker images

REPOSITORY   TAG        IMAGE ID       CREATED        SIZE
debian       bookworm   4eacea30377a   8 days ago     124MB
debian       latest     4eacea30377a   8 days ago     124MB

Docker utiliza un almacenamiento de imágenes direccionable por contenido, y el ID de la imagen es un digest SHA256 que cubre la configuración y las capas de la imagen. En el ejemplo anterior, debian:bookworm y debian:latest tienen el mismo ID de imagen porque son la misma imagen etiquetada con nombres diferentes. Debido a que son la misma imagen, sus capas se almacenan solo una vez y no consumen espacio en disco adicional.

Para obtener más información sobre imágenes, capas y el almacenamiento direccionable por contenido, consulta entender las imágenes, contenedores y controladores de almacenamiento.

Descargar una imagen por digest (identificador inmutable)

Hasta ahora, has descargado imágenes por su nombre (y "etiqueta"). Usar nombres y etiquetas es una forma conveniente de trabajar con imágenes. Al usar etiquetas, puedes ejecutar docker pull en una imagen nuevamente para asegurarte de tener la versión más actualizada de esa imagen. Por ejemplo, docker pull ubuntu:24.04 descarga la última versión de la imagen de Ubuntu 24.04.

En algunos casos, no deseas que las imágenes se actualicen a versiones más recientes, sino que prefieres usar una versión fija de una imagen. Docker te permite descargar una imagen por su digest. Al descargar una imagen por digest, especificas exactamente qué versión de una imagen descargar. Hacerlo te permite "fijar" una imagen a esa versión y garantizar que la imagen que estás usando sea siempre la misma.

Para conocer el digest de una imagen, descarga la imagen primero. Descarguemos la última imagen ubuntu:24.04 de Docker Hub:

$ docker pull ubuntu:24.04

24.04: Pulling from library/ubuntu
125a6e411906: Pull complete
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Downloaded newer image for ubuntu:24.04
docker.io/library/ubuntu:24.04

Docker imprime el digest de la imagen una vez que ha finalizado la descarga. En el ejemplo anterior, el digest de la imagen es:

sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

Docker también imprime el digest de una imagen al subirla (push) a un registro. Esto puede ser útil si deseas fijar la versión de la imagen que acabas de subir.

El digest toma el lugar de la etiqueta al descargar una imagen, por ejemplo, para descargar la imagen anterior por digest, ejecuta el siguiente comando:

$ docker pull ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30: Pulling from library/ubuntu
Digest: sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
Status: Image is up to date for ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
docker.io/library/ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30

El digest también se puede utilizar en la instrucción FROM de un Dockerfile, por ejemplo:

FROM ubuntu@sha256:2e863c44b718727c860746568e1d54afd13b2fa71b160f5cd9058fc436217b30
LABEL org.opencontainers.image.authors="some maintainer <[email protected]>"

Note

El uso de esta característica "fija" una imagen a una versión específica en el tiempo. Por lo tanto, Docker no descargará versiones actualizadas de una imagen, que podrían incluir actualizaciones de seguridad. Si deseas descargar una imagen actualizada, debes cambiar el digest correspondiente.

Descargar desde un registro diferente

Por defecto, docker pull descarga imágenes desde Docker Hub. También es posible especificar manualmente la ruta de un registro desde el cual descargar. Por ejemplo, si has configurado un registro local, puedes especificar su ruta para descargar desde allí. La ruta de un registro es similar a una URL, pero no contiene un especificador de protocolo (https://).

El siguiente comando descarga la imagen testing/test-image desde un registro local que escucha en el puerto 5000 (myregistry.local:5000):

$ docker image pull myregistry.local:5000/testing/test-image

Las credenciales del registro se gestionan mediante docker login.

Docker utiliza el protocolo https:// para comunicarse con un registro, a menos que se permita acceder al registro a través de una conexión insegura. Consulta la sección de registros inseguros para obtener más información.

Descargar un repositorio con múltiples imágenes (-a, --all-tags)

Por defecto, docker pull descarga una única imagen desde el registro. Un repositorio puede contener múltiples imágenes. Para descargar todas las imágenes de un repositorio, proporciona la opción -a (o --all-tags) al usar docker pull.

Este comando descarga todas las imágenes del repositorio ubuntu:

$ docker image pull --all-tags ubuntu

Pulling repository ubuntu
ad57ef8d78d7: Download complete
105182bb5e8b: Download complete
511136ea3c5a: Download complete
73bd853d2ea5: Download complete
....

Status: Downloaded newer image for ubuntu

Una vez completada la descarga, usa el comando docker image ls (o el atajo docker images) para ver las imágenes que se descargaron. El siguiente ejemplo muestra todas las imágenes de ubuntu que están presentes localmente:

$ docker image ls --filter reference=ubuntu
REPOSITORY   TAG       IMAGE ID       CREATED        SIZE
ubuntu       22.04     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       jammy     8a3cdc4d1ad3   3 weeks ago    77.9MB
ubuntu       24.04     35a88802559d   6 weeks ago    78.1MB
ubuntu       latest    35a88802559d   6 weeks ago    78.1MB
ubuntu       noble     35a88802559d   6 weeks ago    78.1MB

Cancelar una descarga

Terminar abruptamente el proceso docker pull, por ejemplo, presionando CTRL-c mientras se está ejecutando en una terminal, finalizará la operación de descarga.

$ docker pull ubuntu

Using default tag: latest
latest: Pulling from library/ubuntu
a3ed95caeb02: Pulling fs layer
236608c7b546: Pulling fs layer
^C

El Engine finaliza una operación de descarga cuando la conexión entre el demonio y el cliente (que inició la descarga) se corta o se pierde por cualquier motivo, o si el comando se termina manualmente.