Cómo solucionar el error 'Port Already in Use' y liberar puertos en Linux

✨ Respuesta Rápida

El error EADDRINUSE: address already in use ocurre cuando un servicio de red, servidor web (Nginx, Apache), contenedor Docker o script (Node.js, Python) intenta vincularse (bind) a un puerto TCP/UDP que ya está siendo utilizado por otro proceso activo en el sistema operativo.

El error EADDRINUSE: address already in use ocurre cuando un servicio de red, servidor web (Nginx, Apache), contenedor Docker o script (Node.js, Python) intenta vincularse (bind) a un puerto TCP/UDP que ya está siendo utilizado por otro proceso activo en el sistema operativo.

El Diagnóstico Rápido

Causa

Error EADDRINUSE :::3000 o bind: address already in use al iniciar un servidor: Un proceso en segundo plano (Node, Python, Docker) no se cerró correctamente

Solución

Identificar el PID con lsof o ss y finalizar la ejecución

Causa

El puerto vuelve a quedar ocupado inmediatamente tras matar el proceso: Un servicio de systemd o un contenedor Docker con política de reinicio automático

Solución

Detener el servicio supervisor (systemctl stop o docker stop)

Causa

El puerto se muestra en estado TIME_WAIT y rechaza conexiones nuevas: El socket no se cerró de forma limpia por falta de SO_REUSEADDR en el servidor

Solución

Esperar el timeout TCP o configurar SO_REUSEADDR en el código fuente

La Solución Paso a Paso

1. 1

   Paso 1: Identificar el proceso y PID que ocupa el puerto

   Utiliza herramientas estándar de red en la terminal para encontrar el identificador de proceso (PID) vinculado al puerto conflictivo (por ejemplo, el puerto 3000 o 8080):

   BASH Copiar

   # Método 1: Usando lsof (LiSt Open Files)
   sudo lsof -i :3000
   
   # Ejemplo de salida:
   # COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
   # node    14205 user   23u  IPv6 128941      0t0  TCP *:3000 (LISTEN)
   
   # Método 2: Usando ss (Socket Statistics)
   sudo ss -tulpn | grep :3000
   
   # Método 3: Usando fuser
   sudo fuser 3000/tcp
   

2. 2

   Paso 2: Finalizar el proceso ocupante de forma segura

   Una vez obtenido el PID (por ejemplo, 14205), envía una señal de terminación respetuosa (SIGTERM) para permitir que el proceso libere los recursos limpiamente. Si no responde, fuerza el cierre con SIGKILL:

   BASH Copiar

   # Terminar de forma limpia (SIGTERM)
   kill 14205
   
   # Forzar el cierre inmediato si el proceso se congeló (SIGKILL)
   kill -9 14205
   
   # O liberar directamente el puerto en un solo comando con fuser:
   sudo fuser -k 3000/tcp
   

3. 3

   Paso 3: Gestionar servicios persistentes (systemd o Docker)

   Si el proceso vuelve a revivir inmediatamente, significa que está gestionado por un demonio supervisor.

   Para servicios de systemd:

   BASH Copiar

   # Identificar qué servicio administra el puerto
   sudo systemctl status <nombre-del-servicio>
   
   # Detener el servicio
   sudo systemctl stop <nombre-del-servicio>
   

   Para contenedores Docker:

   BASH Copiar

   # Listar contenedores usando puertos específicos
   docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}"
   
   # Detener el contenedor conflictivo
   docker stop <nombre-del-contenedor>