Contenido

Tutorial de docker push: enviar imágenes a un Registry con --all-tags y docker login

Q: ¿Por qué hay que añadir una etiqueta de Registry antes de enviar una imagen?

docker tag crea un nombre de destino que apunta a la imagen de origen; en el ejemplo, alpine:3.23 se etiqueta como localhost:5000/tools/alpine:3.23 y luego se envía con ese nombre.

docker push carga imágenes a un Registry. Normalmente, primero configuras el nombre de destino con docker tag; consulta Docker Hub para saber cómo usar Docker Hub.

Sintaxis

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
docker push [OPTIONS] NAME[:TAG]
docker login [OPTIONS] [SERVER]

Parámetros

Parámetro	Descripción
`-a, --all-tags`	Envía todas las etiquetas de la imagen
`--platform cadena`	Envía el manifest de la plataforma especificada como una imagen de plataforma única; no envía el image index, por lo que no se conservan los demás manifest (incluidas las attestations). El formato es `os[/arch[/variant]]`, por ejemplo, `linux/amd64`
`-q, --quiet`	Oculta la salida detallada
`-p, --password cadena`	Contraseña o Personal Access Token (PAT); usa `-` para leer desde stdin
`--password-stdin`	Lee la contraseña o Personal Access Token (PAT) desde stdin
`-u, --username cadena`	Nombre de usuario

Si no especificas un servidor en docker login, se usa Docker Hub de forma predeterminada. El formato del nombre de destino de docker tag es TARGET_IMAGE[:TAG].

Ejemplo

El siguiente ejemplo usa el Registry local localhost:5000 y etiqueta alpine:3.23 en el Repository tools/alpine.

Crear etiquetas de destino

$ docker tag alpine:3.23 localhost:5000/tools/alpine:3.23

$ docker tag alpine:3.23 localhost:5000/tools/alpine:latest

$ docker images localhost:5000/tools/alpine
IMAGE                                ID             DISK USAGE   CONTENT SIZE   EXTRA
localhost:5000/tools/alpine:3.23     ff7f0c727dd7       26.6MB         8.21MB        
localhost:5000/tools/alpine:latest   ff7f0c727dd7       26.6MB         8.21MB

Ambas etiquetas apuntan al mismo ID de imagen.
El nombre de destino incluye el host y el puerto del Registry, el Repository y su etiqueta.

Enviar una etiqueta y todas las etiquetas

$ docker push localhost:5000/tools/alpine:3.23
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Pushed
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push localhost:5000/tools/alpine:latest
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

$ docker push --all-tags localhost:5000/tools/alpine
The push refers to repository [localhost:5000/tools/alpine]
5e9b4a97f639: Layer already exists
3.23: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022
5e9b4a97f639: Layer already exists
latest: digest: sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306 size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:ff7f0c727dd796aa36787bfcd9a64bf35a6ce72a73451b3359fde849b6703d63 -> sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306

Al enviar una sola etiqueta, se muestra el digest; al enviar después la misma capa, aparece Layer already exists.
--all-tags envía 3.23 y latest de tools/alpine en una sola operación.
Aviso Info: alpine:3.23 es una imagen multiplataforma, pero solo hay contenido disponible para algunas plataformas en el equipo local, por lo que se envía únicamente la imagen disponible de una plataforma (el digest cambia de ff7f0c… al digest de plataforma única 3d6794…). El envío se completó correctamente, pero esta etiqueta del Registry solo tiene una plataforma. Consulta Imágenes multiplataforma para enviar imágenes multiplataforma.

Consultar las etiquetas del Registry y reconocer errores

$ wget -qO- http://localhost:5000/v2/tools/alpine/tags/list
{"name":"tools/alpine","tags":["3.23","latest"]}

$ docker push localhost:5000/tools/missing:1.0
The push refers to repository [localhost:5000/tools/missing]
tag does not exist: localhost:5000/tools/missing:1.0

$ docker push docker.io/library/alpine:3.23
The push refers to repository [docker.io/library/alpine]
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Unavailable
5e9b4a97f639: Layer already exists
failed commit on ref "manifest-sha256:3d67941fed5ae436b2bb9791cb3f50a252441c7706bbc5b4e738936df8ff8306": server message: insufficient_scope: authorization failed

La lista de etiquetas del Registry confirma que existen 3.23 y latest; si intentas enviar una etiqueta local inexistente, aparece tag does not exist.
Al enviar docker.io/library/alpine a Docker Hub, aparece al final insufficient_scope: authorization failed: library/ es el espacio de nombres de las imágenes oficiales y nadie puede enviar contenido allí.
Para enviar a Docker Hub, primero ejecuta docker login (consulta los parámetros en la tabla anterior) y etiqueta la imagen con un nombre de tu cuenta, por ejemplo, tu_usuario/alpine:3.23.

Secciones relacionadas

Docker Hub: imágenes y Repository de Docker Hub
Imágenes: consultar las imágenes locales
Imágenes multiplataforma: plataformas y manifest
Liberar espacio en disco: eliminar imágenes que no se usan

Ejercicios

Ejercicio: etiqueta la imagen local alpine:3.23 como localhost:5000/tools/alpine:latest y luego envía todas las etiquetas de tools/alpine.

Respuesta

docker tag alpine:3.23 localhost:5000/tools/alpine:latest
docker push --all-tags localhost:5000/tools/alpine

Preguntas frecuentes

¿Por qué hay que añadir una etiqueta de Registry antes de enviar una imagen?

docker tag crea un nombre de destino que apunta a la imagen de origen; en el ejemplo, alpine:3.23 se etiqueta como localhost:5000/tools/alpine:3.23 y luego se envía con ese nombre.

¿Qué etiquetas envía `docker push --all-tags`?

Envía todas las etiquetas del Repository especificado. En el ejemplo, se envían 3.23 y latest de tools/alpine.

¿Qué hago si aparece insufficient_scope al enviar a Docker Hub?

Significa que no tienes permiso para enviar contenido a ese Repository. docker.io/library/alpine, usado en el ejemplo, pertenece al espacio de nombres de las imágenes oficiales de Docker; ninguna cuenta personal puede enviar contenido allí. Para enviar a Docker Hub, ejecuta primero docker login y luego etiqueta la imagen como tu_usuario/nombre:etiqueta. Consulta [Enviar a Docker Hub](/es/docker/docker-hub/).

¿Es un error que aparezca Info de plataforma única después de enviar correctamente?

El ejemplo ya muestra el digest de la etiqueta y luego indica que solo se envió la imagen disponible de una plataforma; es un aviso Info y no significa que el envío haya fallado.

Actualizado 26 de octubre de 2026