Saltar al contenido principal

Diagnóstico · Puertos · Multiplataforma

Cómo averiguar qué proceso está usando un puerto en Windows, Linux y macOS

Identificá el proceso detrás de “address already in use” con PowerShell, ss, lsof o un solo comando QZX de sólo lectura que devuelve evidencia estructurada en las plataformas compatibles.

Por Alejandro Sánchez, creador de QZX9 min de lectura
Abrir inspectPort

Un conflicto de puerto aparece con frecuencia cuando un servidor de desarrollo, una base de datos, una API local, un contenedor o un proceso auxiliar ya está escuchando donde un segundo programa intenta enlazarse. La primera pregunta útil no es «¿qué mato?», sino «¿quién es dueño de este puerto ahora mismo?».

La diferencia importa porque el propietario puede ser precisamente el servicio que querías conservar. Un buen diagnóstico identifica evidencia primero y deja cualquier mutación de procesos como una decisión independiente.

Windows: encontrar al propietario con PowerShell

Windows expone el puerto local y el proceso propietario mediante Get-NetTCPConnection. Para un listener TCP en el puerto 3000:

Get-NetTCPConnection -LocalPort 3000 -State Listen |
  Select-Object LocalAddress, LocalPort, State, OwningProcess

Después inspeccioná el PID devuelto sin terminarlo:

Get-Process -Id <PID>

Para UDP, Windows expone endpoints vinculados mediante Get-NetUDPEndpoint. TCP y UDP son protocolos distintos; un diagnóstico robusto no debería tratarlos silenciosamente como si fueran lo mismo.

Linux: inspeccionar listeners con ss

En Linux, ss puede mostrar sockets en escucha, puertos numéricos e información del proceso. Una consulta TCP enfocada puede ser:

ss -lptn 'sport = :3000'

-l limita la salida a listeners, -p solicita información del proceso, -t selecciona TCP y -n conserva los puertos numéricos. Los detalles del proceso pueden depender de permisos: que falte metadata no demuestra que no exista propietario.

macOS: usar lsof para el proceso que escucha

Una consulta habitual para un listener TCP en macOS es:

lsof -nP -iTCP:3000 -sTCP:LISTEN

Para un endpoint UDP, usá una consulta específica de UDP en lugar de asumir que el comando anterior lo cubre:

lsof -nP -iUDP:3000

Un solo comando QZX en plataformas compatibles

QZX expone inspectPort como diagnóstico de sólo lectura:

qzx inspectPort 3000 --json

El comando informa si el puerto está ocupado y, cuando el sistema operativo expone la evidencia, devuelve PIDs observados y detalles como nombre, hora de creación, ejecutable, línea de comandos, usuario y memoria. También conserva limitaciones y errores no fatales en vez de inventar datos ausentes.

qzx inspectPort 5173 --json
qzx inspectPort 5432 --json
qzx inspectPort 8000 --json

Son ejemplos de puertos locales, no suposiciones sobre qué aplicación los posee en tu equipo.

Cómo leer el resultado de forma segura

  • status indica si la inspección resolvió free o in_use.
  • observed_pids contiene los PID observados como propietarios cuando están disponibles.
  • processes reúne evidencia que el host permitió leer.
  • limitations explica qué no pudo resolverse.
  • errors conserva fallos no fatales sin perder un diagnóstico que siguió siendo útil.

Que la inspección termine correctamente significa que QZX completó el diagnóstico. No significa que el propietario sea seguro de terminar ni que sea innecesario.

Sólo lectura no significa seguro para publicar sin revisar

La metadata de procesos puede contener más contexto del esperado. Los argumentos de línea de comandos pueden incluir rutas locales, usuarios, URLs, nombres de proyectos, tokens, credenciales o identificadores de clientes. Antes de pegar salida cruda en un issue público, foro, ticket, chat o conversación con una IA, retirá los campos que no sean necesarios.

El límite es importante: el comando no modifica el proceso, pero su salida puede contener información sensible.

Una secuencia más segura para conflictos de puerto

  1. Inspeccioná. Consultá el puerto exacto.
  2. Confirmá. Verificá que esté realmente ocupado y si hay propietario visible.
  3. Comprendé. Revisá nombre, PID, ejecutable, hora de creación y limitaciones.
  4. Decidí por separado. Determiná si el propietario es esperado antes de cambiar su estado.
  5. Volvé a inspeccionar inmediatamente antes de una mutación. Un PID puede reutilizarse después de que termina un proceso.
  6. Verificá después. Consultá otra vez en lugar de asumir que el puerto quedó libre.

inspectPort se detiene deliberadamente en el diagnóstico. Separar evidencia y mutación hace que el flujo sea más útil tanto para personas como para agentes de IA.

Un prompt compacto para un agente de IA

Ejecuté qzx inspectPort 3000 --json.
Revisá el PID, nombre del proceso, hora de creación, ejecutable,
limitaciones y errores que te proporcione. Explicá el propietario
más probable sin asumir que hay que matarlo. Proponé primero una
sola comprobación de sólo lectura. Tratá campos ausentes como desconocidos.

Preguntas frecuentes

¿Cómo sé qué proceso está usando el puerto 3000?

Usá las herramientas nativas de listeners o ejecutá qzx inspectPort 3000 --json. Revisá al propietario antes de decidir si algún proceso debe detenerse.

¿inspectPort mata el proceso?

No. inspectPort es de sólo lectura. Identifica ocupación y evidencia del proceso, pero no termina ni modifica al listener.

¿Por qué pueden faltar detalles del proceso?

Las APIs del sistema operativo, permisos, condiciones de carrera o la finalización del proceso durante la inspección pueden limitar lo que se lee. QZX informa esas limitaciones.

¿Puedo pegar el JSON en un issue público?

Revisalo primero. Líneas de comandos, rutas, usuarios y argumentos pueden revelar información sensible aunque la inspección sea de sólo lectura.

Fuentes primarias y lecturas adicionales