Error Docker container name is already in use: cómo solucionarlo

El error Conflict. The container name "/nombre_contenedor" is already in use ocurre cuando intentas crear o ejecutar un contenedor con un nombre que ya está asignado a otro en el motor de Docker. Esto sucede casi siempre porque el contenedor previo se detuvo pero no fue eliminado, por lo que el nombre sigue reservado en el registro local. La solución rápida pasa por eliminar el contenedor antiguo mediante docker rm o usar la bandera --rm en tus ejecuciones cotidianas.

Qué significa el error

Este mensaje de conflicto es generado directamente por el demonio de Docker (dockerd) durante la fase de creación de un contenedor. Docker exige que cada contenedor dentro de un mismo host posea un identificador de nombre único. Si ejecutas docker run --name mi_app nginx dos veces seguidas, la segunda ejecución fallará indicando el ID del contenedor que actualmente retiene dicho nombre.

El error afecta por igual a entornos de desarrollo en local, pipelines de CI/CD e infraestructuras de despliegue sobre Linux, macOS y Windows (Docker Desktop). No importa que el contenedor original esté parado, pausado o en estado exótico (created o dead); mientras figure en la lista global de recursos del sistema, el nombre no podrá reutilizarse.

Causas más habituales

Contenedor detenido pero persistente: El contenedor finalizó su proceso o se detuvo manualmente con docker stop, pero no se ejecutó su borrado del disco.
Falta de la bandera --rm: Lanzar contenedores de prueba o temporales sin la opción de automantenimiento deja el nombre bloqueado tras el cierre.
Reinicio abrupto del daemon o del sistema: Si el ordenador se apaga inesperadamente, Docker conserva el estado anterior de los contenedores sin haberlos limpiado.
Conflictos en scripts de despliegue o Docker Compose: Intentar recrear un servicio con docker-compose up sin haber bajado la pila anterior adecuadamente con docker compose down.
Procesos zombi o colgados: El contenedor ha fallado internamente y se encuentra en un estado inestable que impide que se sobrescriba.

Antes de empezar

Antes de proceder a eliminar cualquier contenedor, asegúrate de no perder información crítica alojada en su capa de escritura interna. Si el contenedor contenía datos que no estaban mapeados en un volumen persistente o en un bind mount, se borrarán de forma permanente al eliminar la instancia.

Verifica también que tu usuario tenga los permisos adecuados para comunicarse con el socket de Docker. En sistemas Linux, debes pertenecer al grupo docker o disponer de privilegios elevados. Si experimentas problemas de permisos en la consola, consulta cómo solucionar el error User is not in the sudoers file en Linux para configurar el acceso correctamente.

Solución 1: Identificar y eliminar el contenedor detenido (Método recomendado)

Esta es la vía más segura y habitual. Consiste en listar todos los contenedores registrados en el sistema, incluidos los que no están activos, y eliminar explícitamente el que causa la colisión.

Abre tu terminal o consola de comandos.
Filtra la lista de contenedores para localizar el nombre en conflicto y obtener su ID exacto mediante el flag -a (all):
```
docker ps -a --filter name=nombre_contenedor
```
Verifica el estado del contenedor en la columna STATUS (por ejemplo, Exited (0) o Created). Por qué funciona: comprobar el estado te asegura que no vas a detener un servicio activo por error.
Detén el contenedor si sigue en ejecución:
```
docker stop nombre_contenedor
```
Por qué funciona: el comando envía una señal SIGTERM al proceso principal para cerrar las conexiones y guardar datos correctamente antes de permitir su borrado.
Elimina el contenedor conflictivo:
```
docker rm nombre_contenedor
```
Por qué funciona: docker rm libera el registro del nombre en el demonio de Docker y elimina su capa rw del sistema de archivos local, permitiendo que la etiqueta sea asignada a un nuevo contenedor.
Vuelve a ejecutar tu comando docker run original.

Solución 2: Forzar la eliminación del contenedor en ejecución

Si necesitas reemplazar inmediatamente una instancia sin importar su estado o si el proceso no responde a la orden de parada estándar, puedes combinar la detención y el borrado en un único comando.

Ejecuta la eliminación forzada especificando la bandera -f o --force:
```
docker rm -f nombre_contenedor
```
Por qué funciona: esta orden envía inmediatamente una señal SIGKILL (KILL) al proceso principal del contenedor en lugar de SIGTERM, deteniendo su ejecución de manera instantánea y eliminando la entrada del contenedor de la base de datos de Docker en el mismo paso.
Verifica que la salida por consola devuelva el nombre del contenedor eliminado.
Lanza de nuevo la orden de creación o despliegue.

Solución 3: Usar la bandera --rm para contenedores temporales

Para evitar que este error vuelva a producirse en entornos de prueba, herramientas CLI puntuales o tareas batch, se debe delegar la limpieza del contenedor al propio ciclo de vida de Docker.

Añade el parámetro --rm al comando de ejecución:
```
docker run --rm --name mi_app nginx
```
Cuando el proceso principal del contenedor finaliza (o cuando lo detienes con Ctrl+C), Docker destruye automáticamente el contenedor y libera el nombre asignado.
Por qué funciona: la bandera --rm le indica al demonio que elimine de forma permanente la capa de contenedor anónima y su identificador tan pronto como el estado cambie a parado, impidiendo que queden registros huérfanos.

Solución 4: Limpieza de la pila con Docker Compose

Si el error ocurre al trabajar con proyectos orquestados mediante un archivo docker-compose.yml, ejecutar un nuevo up puede colisionar con recursos creados en sesiones anteriores.

Accede al directorio donde se encuentra tu archivo docker-compose.yml.
Detén y elimina todos los contenedores, redes y volúmenes anónimos asociados a la pila:
```
docker compose down
```
Por qué funciona: a diferencia de detener individualmente los servicios, docker compose down elimina las instancias creadas respetando el orden de dependencias y libera los nombres mapeados en el espacio de nombres del proyecto.
Si persisten nombres bloqueados debido a cambios en el archivo de configuración, elimina también los contenedores huérfanos:
```
docker compose down --remove-orphans
```
Vuelve a levantar los servicios de forma limpia:
```
docker compose up -d
```

Solución 5: Realizar una limpieza masiva de contenedores parados (Prune)

Si el entorno acumula múltiples contenedores antiguos y resulta tedioso borrarlos uno a uno por su nombre, puedes recurrir al comando de purga de recursos.

Ejecuta la orden de limpieza de contenedores inactivos:
```
docker container prune
```
Confirma la acción introduciendo y cuando el sistema lo solicite.
Por qué funciona: este comando analiza el estado de todos los contenedores y elimina globalmente aquellos que se encuentren en estado exited o created, liberando de un solo paso múltiples nombres y espacio en disco.

Cómo comprobar que el problema se ha resuelto

Para confirmar que el conflicto de nombres se ha resuelto correctamente y tu entorno está listo para nuevos despliegues, realiza estas comprobaciones en la terminal:

Lista de contenedores activos e inactivos: Ejecuta docker ps -a --filter name=nombre_contenedor. La salida debe estar vacía o mostrar únicamente la nueva instancia en estado Up.
Prueba de ejecución: Lanza tu comando original docker run --name nombre_contenedor .... El proceso debe iniciarse sin devolver el mensaje Conflict. The container name....
Verificación de logs: Revisa el estado de salud de la nueva instancia con docker logs nombre_contenedor para confirmar que el nuevo servicio está respondiendo correctamente.

Preguntas frecuentes

¿Puedo renombrar un contenedor existente para liberar el nombre?

Sí. Si no quieres eliminar el contenedor antiguo pero necesitas liberar su nombre para una nueva instancia, utiliza el comando docker rename nombre_antiguo nuevo_nombre. Esto libera inmediatamente nombre_antiguo para su reutilización.

¿Por qué aparece el error si el contenedor está en estado Exited?

Porque Docker distingue entre el estado del proceso (en ejecución o detenido) y la existencia del recurso en el sistema de archivos. Aunque el proceso se haya detenido, la estructura de carpetas, configuraciones y el nombre asignado siguen registrados en la base de datos de Docker hasta que se ejecute docker rm.

¿Eliminar el contenedor borra también los datos de los volúmenes?

No. Los volúmenes administrados (docker volume) y los montajes de tipo bind mount son independientes del ciclo de vida del contenedor. Al hacer docker rm, solo se pierde la información escrita en la capa RW interna del propio contenedor; los datos persistidos en volúmenes externos permanecen intactos.

¿Qué hago si el comando docker rm se queda colgado?

Si docker rm o docker rm -f no responde, suele deberse a un problema en el motor de almacenamiento o a un punto de montaje bloqueado en el sistema operativo. En estos casos, reinicia el servicio de Docker mediante sudo systemctl restart docker en Linux o reinicia Docker Desktop en Windows y macOS antes de reintentar el borrado.