Cómo nombrar contenedores con '--name' y etiquetar imágenes con 'docker tag'

Introducción

Al trabajar con Docker es común crear muchos contenedores e imágenes durante el desarrollo, las pruebas o el despliegue. Sin una convención clara para nombrar contenedores y etiquetar imágenes, pronto te vas a encontrar con nombres genéricos como 'compassionate_fermi' o 'thestupefying_wiles', lo que dificulta la identificación, la depuración y la automatización. En este artículo vas a aprender a asignar nombres significativos a tus contenedores usando la bandera '--name' de 'docker run', a renombrarlos cuando sea necesario y a aplicar etiquetas descriptivas a tus imágenes con el comando 'docker tag'. Además, verás ejemplos con la salida esperada para que puedas comprobar que todo funciona como esperás.

Este tutorial está dirigido a desarrolladores, administradores de sistemas y cualquier persona que use Docker en su día a día y quiera mejorar la organización y la trazabilidad de sus entornos containerizados. Al finalizar, sabrás:

• Cómo especificar un nombre legible al crear un contenedor.
• Cómo ver y filtrar contenedores por nombre.
• Cómo cambiar el nombre de un contenedor en ejecución o detenido.
• Cómo etiquetar imágenes para versionarlas, indicar su entorno o su destino.
• Buenas prácticas para evitar colisiones y confusiones.
• Errores frecuentes y cómo solucionarlos.

¿Por qué nombrar contenedores y etiquetar imágenes es importante

Cuando Docker crea un contenedor sin un nombre explícito, le asigna un identificador aleatorio compuesto por dos palabras (por ejemplo, 'happy_noether'). Ese nombre es útil para que Docker lo distinga internamente, pero no aporta información funcional para vos. Si tenés varios contenedores corriendo simultáneamente, resulta tedioso tener que recordar cuál corresponde a cada servicio. Lo mismo ocurre con las imágenes: si no les aplicás etiquetas claras, terminás con una lista de 'none' o con tags genéricos que no indican versión ni propósito.

Un buen nombre de contenedor te permite:

• Identificar rápidamente el servicio (por ejemplo, 'web_app', 'db_primary', 'cache_redis').
• Filtrar y gestionar contenedores con comandos como 'docker ps --filter name=web'.
• Facilitar la integración con scripts de orquestación o monitoreo.

Una etiqueta de imagen bien elegida te ayuda a:

• Indicar la versión de la aplicación (por ejemplo, 'miapp:1.4.0').
• Distinguir entre builds de desarrollo, staging y producción (por ejemplo, 'miapp:dev', 'miapp:prod').
• Evitar que se sobrescriban imágenes accidentalmente al volver a construir.
• Hacer que los registros de Docker (como Docker Hub o un registro privado) muestren información significativa.

Usando '--name' al crear un contenedor

La forma más simple de asignar un nombre a un contenedor es mediante la opción '--name' de 'docker run'. La sintaxis es:

docker run --name <nombre_del_contenedor> <imagen> [comando]

El nombre debe cumplir con las reglas de Docker: solo letras, números, guiones bajos, puntos y guiones. No puede comenzar con un punto o un guion y no puede contener espacios.

Ejemplo básico: contenedor de Nginx

Vamos a lanzar un contenedor basado en la imagen oficial de Nginx y darle el nombre 'mi_nginx'.

docker run --name mi_nginx -d -p 8080:80 nginx

Salida esperada (el ID del contenedor variará en cada ejecución):

Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
8a6bbf645b5a: Pull complete
... (más capas)
Digest: sha256:...
Status: Downloaded newer image for nginx:latest
Container ID: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

En este caso Docker descargó la imagen (si no la tenías localmente) y luego creó el contenedor. El ID que ves al final es el identificador interno; el nombre que viste en el comando es 'mi_nginx'.

Verificando que el nombre se aplicó

Para confirmar que el contenedor lleva el nombre que le asignaste, podés usar 'docker ps' o 'docker inspect'.

docker ps --filter name=mi_nginx

Salida esperada:

CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS                    NAMES
a1b2c3d4e5f6   nginx     "nginx -g daemon off"   2 minutes ago    Up 2 minutes    0.0.0.0:8080->80/tcp   mi_nginx

Observá que la columna 'NAMES' muestra exactamente 'mi_nginx'.

También podés inspeccionar el contenedor y ver el campo 'Name':

docker inspect --format='{{.Name}}' mi_nginx

Salida esperada:

/mi_nginx

El slash inicial es parte de la forma en que Docker almacena el nombre internamente, pero el nombre que vos usás es 'mi_nginx'.

Renombrar un contenedor existente

Si ya tenés un contenedor en ejecución o detenido y querés cambiar su nombre, Docker provee el comando 'docker rename'. La sintaxis es:

docker rename <nombre_actual> <nuevo_nombre>

Supongamos que querés cambiar 'mi_nginx' a 'frontend_web'.

docker rename mi_nginx frontend_web

No hay salida si el comando tiene éxito. Para verificar:

docker ps --filter name=frontend_web

Salida esperada:

CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS                    NAMES
a1b2c3d4e5f6   nginx     "nginx -g daemon off"   3 minutes ago    Up 3 minutes    0.0.0.0:8080->80/tcp   frontend_web

Si intentás renombrar a un nombre que ya está en uso, Docker devolverá un error:

docker rename frontend_web otro_nginx

Salida esperada en caso de conflicto:

Error response from daemon: Conflict. The container name "otro_nginx" is already in use by container "b2c3d4e5f6a7b8c9d0e1f2g3h4i5j6k7". You have to remove (or rename) that container to be able to reuse that name.

En ese caso, primero tenés que detener y eliminar (o renombrar) el contenedor que ocupa ese nombre.

Eliminando un contenedor por nombre

Cuando ya no necesitás un contenedor, podés eliminarlo referenciándolo por su nombre con 'docker rm'.

docker rm -f frontend_web

La opción '-f' fuerza la detención si el contenedor estaba en ejecución. Salida esperada:

frontend_web

Docker simplemente devuelve el nombre del contenedor eliminado.

Etiquetando imágenes con 'docker tag'

Mientras que '--name' se aplica a contenedores en tiempo de ejecución, las etiquetas (tags) son atributos de las imágenes. Una imagen puede tener múltiples tags, lo que permite apuntar la misma imagen a diferentes nombres o versiones. El comando 'docker tag' crea un nuevo tag que referencia a una imagen existente sin duplicar los datos.

La sintaxis básica es:

docker tag <imagen_origen> <imagen_destino>:<tag>

Donde puede ser el ID corto o largo de la imagen, o su nombre actual (por ejemplo, 'nginx:latest'). es el nuevo repositorio o nombre que querés darle, y es la etiqueta (por ejemplo, '1.0', 'dev', 'prod').

Etiquetar una imagen local

Imaginemos que construiste una imagen de tu aplicación con el comando 'docker build' y quedó con el nombre 'miapp' y sin tag (Docker le asigna '' si no se especifica). Vamos a darle una etiqueta de versión.

Primero, veamos la imagen sin tag:

docker images miapp

Salida esperada:

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
miapp        <none>    a1b2c3d4e5f6   2 minutes ago    150MB

Ahora le aplicamos el tag 'v1.0.0':

docker tag miapp miapp:v1.0.0

No hay salida si todo salió bien. Verifiquemos:

docker images miapp

Salida esperada:

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
miapp        latest    a1b2c3d4e5f6   2 minutes ago    150MB
miapp        v1.0.0    a1b2c3d4e5f6   2 minutes ago    150MB

Observá que ahora la misma IMAGE ID tiene dos tags: 'latest' (que Docker asignó automáticamente porque no especificaste tag en el build) y 'v1.0.0' que recién agregamos.

Etiquetando con un nombre de repositorio completo

Si querés subir tu imagen a un registro (por ejemplo, Docker Hub o un registro privado), necesitás incluir el nombre del repositorio en el tag. Supongamos que tu usuario en Docker Hub es 'juanperez' y querés llamar al repositorio 'miapp'.

docker tag miapp:v1.0.0 juanperez/miapp:v1.0.0

Verificación:

docker images juanperez/miapp

Salida esperada:

REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
juanperez/miapp     v1.0.0    a1b2c3d4e5f6   2 minutes ago    150MB

Ahora la imagen está lista para ser subida con 'docker push juanperez/miapp:v1.0.0'.

Reetiquetando una imagen existente

Podés aplicar múltiples tags a la misma imagen. Por ejemplo, además de 'v1.0.0', querés marcar la misma build como 'latest' para tu registro.

docker tag miapp:v1.0.0 juanperez/miapp:latest

Luego de ejecutar el comando, al listar las imágenes vas a ver:

docker images juanperez/miapp

Salida esperada:

REPOSITORY          TAG       IMAGE ID       CREATED          SIZE
juanperez/miapp     latest    a1b2c3d4e5f6   2 minutes ago    150MB
juanperez/miapp     v1.0.0    a1b2c3d4e5f6   2 minutes ago    150MB

Esto es útil porque muchos sistemas de despliegue asumen que el tag 'latest' apunta a la versión más reciente.

Etiquetando una imagen extraída de un registro

Supongamos que descargaste la imagen oficial de Redis y querés crear un tag que indique que la vas a usar como caché de sesión en tu entorno de staging.

Primero, bajemos la imagen:

docker pull redis:6-alpine

Salida esperada (resumida):

6-alpine: Pulling from library/redis
... (capas)
Status: Downloaded newer image for redis:6-alpine
docker.io/library/redis:6-alpine

Ahora le aplicamos un tag personalizado:

docker tag redis:6-alpine mi_redis_staging:session-cache

Verificación:

docker images mi_redis_staging

Salida esperada:

REPOSITORY           TAG               IMAGE ID       CREATED          SIZE
mi_redis_staging     session-cache     c3d4e5f6a7b8   5 days ago     30MB

Notá que el ID de la imagen coincide con el de 'redis:6-alpine', lo que confirma que no se duplicó la información.

Buenas prácticas para nombrar contenedores y etiquetar imágenes

A continuación tenés una lista de recomendaciones que te ayudarán a mantener tu entorno Docker ordenado y predecible.

1. Usá nombres descriptivos y cortos para contenedores

   • Ejemplos: 'web_frontend', 'api_gateway', 'db_master', 'cache_redis'.
   • Evitá nombres genéricos como 'container1' o 'test'.
   • Si el contenedor forma parte de un conjunto de servicios (por ejemplo, un docker‑compose), podés incluir el nombre del proyecto como prefijo: 'miapp_web', 'miapp_db'.

2. Evité caracteres especiales y mayúsculas

   • Docker solo permite letras, números, guiones bajos, puntos y guiones.
   • Los nombres en minúscula son más fáciles de leer y de escribir en la línea de comandos.
   • No uses espacios; si necesitás separar palabras, usá guiones bajos o guiones.

3. Renombrá sólo cuando sea realmente necesario

   • Cambiar el nombre de un contenedor en producción puede romper scripts que dependen de ese nombre.
   • Prefirá definir el nombre correcto en el momento de crear el contenedor (con '--name') y dejarlo así durante su vida útil.

4. Aplicá un esquema de versionado consistente a las imágenes

   • SemVer (por ejemplo, '1.2.3') es ampliamente entendido.
   • Para builds de desarrollo, podés usar etiquetas como 'dev', 'test', 'ci'.
   • Para producción, usá etiquetas que indiquen el entorno y la versión: 'prod-1.2.0', 'staging-1.2.0-rc1'.

5. No sobrescribas el tag 'latest' sin intención

   • Muchos sistemas de despliegue asumen que 'latest' es la versión más estable.
   • Si necesitás actualizar 'latest', aseguráte de que la nueva imagen haya pasado todas las pruebas de integración.

6. Documentá tus convenciones

   • Tener un archivo README o un wiki que explique cómo se nombran los contenedores y cómo se etiquetan las imágenes evita confusiones en equipos grandes.
   • Incluí ejemplos de comandos 'docker run --name' y 'docker tag' que se usen habitualmente en tu proyecto.

7. Utilizá filtros y formato para inspeccionar rápidamente

   • Comandos como 'docker ps --format "table {{.Names}} {{.Image}} {{.Status}}"', o 'docker images --format "table {{.Repository}} {{.Tag}} {{.Size}}"', te permiten ver solo la información que necesitás.

Errores comunes y cómo solucionarlos

A pesar de las mejores intenciones, es fácil tropezar con ciertos problemas al nombrar contenedores o etiquetar imágenes. Aquí tenés los más frecuentes y sus soluciones.

1. "Conflict. The container name ... is already in use"

• Causa: Intentás crear o renombrar un contenedor con un nombre que ya está asignado a otro contenedor (incluso si está detenido).
• Solución:
  • Detená y eliminá el contenedor existente: docker rm -f <nombre>
  • O bien, elegí un nombre diferente para el nuevo contenedor.

2. "No such image: :

• Causa: Intentás etiquetar una imagen que no existe localmente con ese nombre/tag.
• Solución:
  • Verificá la lista de imágenes con docker images.
  • Si la imagen está en un registro, puxela primero: docker pull <nombre>:<tag>.
  • Si acabás de construirla, aseguráte de que el build terminó sin errores y que usaste el nombre correcto.

3. El tag no aparece después de usar 'docker tag'

• Causa: Quizás escribiste mal el nombre de la imagen de origen o de destino, o usaste caracteres no permitidos.
• Solución:
  • Revisá la sintaxis: docker tag <origen> <destino>:<tag>.
  • Confirmá que ambas partes existen y que no haya espacios de más.
  • Usá docker images para ver si el nuevo tag apareció.

4. Confusión entre nombre de contenedor y nombre de imagen

• Causa: A veces se cree que el '--name' afecta a la imagen, cuando en realidad solo nombra el contenedor de ejecución.
• Solución: Recordá que '--name' es para contenedores; para cambiar el nombre o el tag de una imagen usá docker tag.

5. Intentando subir una imagen sin tag apropiado al registro

• Causa: Al hacer docker push, el comando falla porque no encontrás un repositorio válido o el tag no contiene el nombre de usuario.
• Solución:
  • Antes de empujar, aplicá un tag que incluya tu usuario o el nombre del registro: docker tag <imagen> <usuario>/<repositorio>:<tag>.
  • Luego ejecutá docker push <usuario>/<repositorio>:<tag>.

Flujos de trabajo típicos

A continuación se presentan dos escenarios comunes donde el uso correcto de '--name' y 'docker tag' marca la diferencia.

Escenario 1: Entorno de desarrollo con docker‑compose

En un archivo docker-compose.yml podés definir nombres explícitos para cada servicio, lo que evita que Docker genere nombres aleatorios.

version: '3.8'
services:
  web:
    image: miapp:dev
    container_name: miapp_web   # <-- nombre explícito
    ports:
      - "3000:3000"
  db:
    image: postgres:13
    container_name: miapp_db
    environment:
      POSTGRES_PASSWORD: secret

Al levantar el stack con docker-compose up -d, verás en docker ps los nombres miapp_web y miapp_db. Esto facilita los comandos de administración:

docker logs -f miapp_web
 docker exec -it miapp_db psql -U postgres

Escenario 2: CI/CD con versionado de imágenes

En una pipeline de integración continua, cada commit genera una nueva imagen cuyo tag incluye el SHA del commit y, cuando se aprueba, se le agrega un tag de versión semántica.

# Construir la imagen con tag temporal
 docker build -t miapp:ci-${GIT_SHA} .

# Ejecutar pruebas
 docker run --name test_ci-${GIT_SHA} miapp:ci-${GIT_SHA} npm test

# Si las pruebas pasan, aplicar tag de versión
 docker tag miapp:ci-${GIT_SHA} miapp:${SEMVER}

# También actualizar 'latest' para despliegues rápidos
 docker tag miapp:ci-${GIT_SHA} miapp:latest

# Subir al registro
 docker push miapp:${SEMVER}
 docker push miapp:latest

En este flujo, los contenedores de prueba reciben nombres únicos basados en el SHA, lo que evita colisiones cuando varios jobs se ejecutan en paralelo. Las imágenes, por su parte, quedan etiquetadas de forma que se pueda rastrear exactamente qué código está en cada tag.

Resumen de comandos clave

Para que tengás a mano una referencia rápida, aquí tenés los comandos más usados con su sintaxis y un breve recordatorio de qué hacen.

Conclusión

Nombrar contenedores con '--name' y etiquetar imágenes con 'docker tag' son acciones simples pero poderosas que mejoran significativamente la claridad, la trazabilidad y la automatización de tus flujos de trabajo con Docker. Al asignar nombres descriptivos a tus contenedores, evitás la confusión que genera la nomenclatura aleatoria y facilitás la inspección, el registro y la orquestación. Al aplicar etiquetas significativas a tus imágenes, podés versionar tus builds, distinguir entre entornos y subir con confianza a registros públicos o privados.

Recordá siempre:

• Definir el nombre del contenedor en el momento de crearlo; usar 'docker rename' solo cuando sea estrictamente necesario.
• Seguir un esquema de versionado coherente (SemVer, etiquetas de entorno, etc.) y documentarlo en tu equipo.
• Verificar que los nombres y tags cumplan con las restricciones de Docker antes de ejecutar los comandos.
• Aprovechar los filtros y el formato de salida de 'docker ps' y 'docker images' para obtener rápidamente la información que necesitás.

Con estas prácticas en tu caja de herramientas, estarás mejor preparado para gestionar entornos de desarrollo, testing y producción de forma ordenada y predecible. Ahora es tu turno: probá los ejemplos en tu máquina, adaptalos a tus proyectos y notá la diferencia que hace una buena nomenclatura.

¡Éxitos con tus contenedores y tus imágenes!