En esta lección aprenderás cómo etiquetar una imagen Docker para darle un nombre claro, preparar su subida a un registry o marcar una versión concreta de tu aplicación. Etiquetar no reconstruye la imagen: crea otra referencia hacia el mismo artefacto.
La idea es que puedas distinguir imagen, repositorio y tag antes de publicar nada. Así evitas errores típicos como depender siempre de latest o subir una imagen con un nombre que no corresponde al registry de destino.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Para qué sirve etiquetar una imagen
Problema: una imagen sin un tag claro puede ser difícil de identificar, automatizar o publicar. Además, un mismo contenido puede necesitar varios nombres según el entorno o registry.
Qué aporta Docker: docker tag crea una nueva referencia para una imagen existente. Esa referencia puede ser una versión, un alias estable o el nombre completo que espera un registry.
| Elemento | Ejemplo |
|---|---|
| Repositorio local | mi-app |
| Tag de versión | 1.0, 1.2.3 o 2026-08-14 |
| Alias de canal | stable, dev o staging |
| Nombre para registry | registry.example.com/equipo/mi-app:1.0 |
Crear una imagen con tag
Puedes asignar un tag desde el build. Este es el punto de partida más limpio cuando estás construyendo una imagen de laboratorio o una app propia.
docker build -t mi-app:1.0 .
docker image ls mi-app
docker image inspect mi-app:1.0 --format '{{.Id}}' Resultado esperado: Docker muestra la imagen mi-app con el tag 1.0. Si inspeccionas la imagen, verás que ese tag apunta a un identificador concreto.
Crear otro tag para la misma imagen
Ahora puedes crear referencias adicionales con docker tag. El contenido no cambia; solo aparece otro nombre apuntando a la misma imagen.
docker tag mi-app:1.0 mi-app:stable
docker tag mi-app:1.0 usuario/mi-app:1.0
docker image ls mi-app
docker image ls usuario/mi-app- Un tag no copia capas: normalmente es otra referencia al mismo ID de imagen.
- latest no significa más nuevo: solo es un tag más si alguien lo crea o lo mueve.
- Usa versiones explícitas: facilitan rollback, despliegues y auditoría.
- Verifica con image ls: comprueba qué nombres existen antes de hacer push o borrar.
Preparar el nombre para un registry
Para subir una imagen a un registry, el tag debe incluir el destino correcto. Si el nombre no contiene el registry o namespace esperado, docker push intentará publicar en otro lugar o fallará.
docker tag mi-app:1.0 registry.example.com/equipo/mi-app:1.0
docker image inspect registry.example.com/equipo/mi-app:1.0 --format '{{.RepoTags}}'
# Cuando el registry sea real y tengas permisos:
# docker push registry.example.com/equipo/mi-app:1.0En un entorno real, sustituye registry.example.com por tu registry y usa un namespace válido. No ejecutes push con credenciales reales hasta haber verificado el nombre completo de la imagen.
Errores comunes
- Pensar que docker tag modifica el contenido de la imagen.
- Usar latest como única referencia en producción.
- Etiquetar para el registry equivocado y descubrirlo al hacer push.
- Borrar una referencia pensando que elimina todas las demás tags.
- Confundir tag con digest: el tag puede moverse, el digest identifica contenido concreto.
- No documentar qué estrategia de versionado usa el equipo.
La regla práctica para cómo etiquetar una imagen Docker es simple: usa tags legibles para humanos, versiones estables para despliegues y nombres completos cuando prepares una imagen para un registry.
Lecciones relacionadas del curso
- Imagen de Docker: entiende qué estás etiquetando realmente.
- Qué significa latest: evita depender de un tag ambiguo.
- Qué es el digest de una imagen: diferencia tags mutables y referencias exactas.
- Qué es un Docker registry: conecta tags con publicación de imágenes.
Documentación oficial y recursos
- docker image tag: referencia oficial para etiquetar imágenes.
- docker image ls: verifica imágenes y tags locales.
- docker image inspect: consulta IDs, RepoTags y metadatos.
- docker image push: publica imágenes en un registry.
- docker image build: crea imágenes con nombre y tag desde el build.

