Port Killer

Gestor de puertos para Linux. Identifica y termina procesos que ocupan puertos de forma rápida y visual, especialmente útil durante el desarrollo de software.

Características

• Interfaz GTK4 + libadwaita con actualización diferencial (sin parpadeos), búsqueda instantánea (Ctrl+F), filtro Todos/Dev y avisos claros de cada acción.
• Filas expandibles: cada puerto despliega su ficha completa (comando completo seleccionable, direcciones, usuario, tiempo activo, memoria y conexiones establecidas).
• Icono de bandeja opcional (port-killer-tray): puertos dev en la barra superior, con terminación a un clic e instancia única.
• Visión completa del sistema: los puertos de otros usuarios (root, contenedores Docker...) también se muestran, marcados con un candado y un aviso, en lugar de ocultarse.
• Indicador de exposición: los puertos que escuchan en todas las interfaces (0.0.0.0, ::) se marcan como EXPUESTO.
• Terminación segura: SIGTERM con escalada automática a SIGKILL, verificación de reutilización de PID antes de enviar la señal y confirmación obligatoria para servicios protegidos (bases de datos, sshd...).
• CLI completa con colores, salida JSON para scripts y modo watch en vivo.
• Integración con Docker: los puertos publicados por contenedores se identifican por el nombre del contenedor (badge DOCKER), aunque el proceso docker-proxy pertenezca a root.
• Internacionalización: interfaz en español o inglés según el idioma del sistema (gettext; traducciones en po/).
• Configurable: rangos de puertos de desarrollo, procesos protegidos e intervalo de refresco en ~/.config/portkiller/config.toml.
• Descripciones humanizadas: node node_modules/.bin/vite se muestra como «Vite dev server»; los procesos crípticos de Electron/VSCode se identifican por su función.

Instalación

Instalación automática

git clone https://github.com/686f6c61/linux-port-killer
cd linux-port-killer
./install.sh

El instalador añade las dependencias del sistema (GTK4, libadwaita, PyGObject) con el gestor de paquetes de tu distribución (Ubuntu/Debian, Fedora, Arch), crea un entorno virtual aislado en ~/.local/share/port-killer/ y registra la aplicación en el menú. No instala nada con pip a nivel de sistema.

Instalación manual

Con las dependencias del sistema ya presentes (python3-gi, gir1.2-gtk-4.0, gir1.2-adw-1):

python3 -m venv --system-site-packages ~/.local/share/port-killer/venv
~/.local/share/port-killer/venv/bin/pip install .

Los ejecutables quedan en <venv>/bin/port-killer y <venv>/bin/port-killer-gui.

Uso

Interfaz gráfica

Busca «Port Killer» en el menú de aplicaciones o ejecuta port-killer-gui.

• Cada fila se despliega con la flecha para ver la ficha completa del proceso.
• Ctrl+F busca por puerto, proceso, comando o contenedor; Ctrl+R refresca; Ctrl+Q sale.
• Clic derecho en una fila: copiar puerto/PID/comando, terminar con SIGTERM o forzar con SIGKILL.
• El botón «Terminar puertos dev» finaliza todos los procesos en rangos de desarrollo, con confirmación y respetando los protegidos.

Icono de bandeja

port-killer-tray deja un indicador permanente en la barra superior con los puertos dev activos: un clic sobre un puerto lo termina, y «… y N más» o «Abrir Port Killer» abren la aplicación completa. También se lanza desde el menú de la GUI («Icono de bandeja») y permanece hasta que elijas «Salir».

Para que arranque automáticamente al iniciar sesión: ./install.sh --autostart.

Requiere la librería AppIndicator (en Ubuntu/Debian: gir1.2-ayatanaappindicator3-0.1; el instalador la añade si está disponible).

Línea de comandos

port-killer list              # todos los puertos en escucha
port-killer list --dev        # solo puertos de desarrollo
port-killer list --json       # salida JSON para scripts
port-killer info 3000         # detalle de un puerto
port-killer kill 3000         # terminar (SIGTERM, escala a SIGKILL)
port-killer kill 3000 -f -y   # SIGKILL sin confirmación
port-killer kill-dev          # terminar todos los puertos dev
port-killer watch             # vista en vivo

Los puertos de otros usuarios requieren privilegios: sudo port-killer list.

Configuración

Fichero opcional ~/.config/portkiller/config.toml:

# Rangos de puertos considerados "de desarrollo"
dev_ranges = [[3000, 3999], [5000, 5999], [8000, 8999]]

# Procesos que piden confirmación antes de terminarse
protected = ["postgres", "mysqld", "redis-server", "nginx", "sshd"]

# Segundos entre refrescos de la GUI
refresh_interval = 5

# Segundos de espera a SIGTERM antes de escalar a SIGKILL
kill_timeout = 3.0

Nota: los procesos protegidos nunca se marcan como DEV aunque su puerto caiga en un rango de desarrollo (por ejemplo PostgreSQL en 5432), y el kill masivo los excluye siempre.

Desarrollo

El proyecto usa uv:

uv sync --all-groups   # instalar dependencias
uv run pytest          # tests (cobertura mínima 80 %)
uv run ruff check .    # linter
uv run ruff format .   # formateador

La GUI necesita el PyGObject del sistema; para lanzarla en desarrollo:

PYTHONPATH=src python3 -m portkiller.gui.app

Traducciones

Los textos fuente están en inglés y las traducciones en po/. Para actualizar tras cambiar cadenas:

find src/portkiller -name "*.py" | sort | xargs xgettext -L Python --keyword=_ \
    --from-code=UTF-8 -o po/portkiller.pot
msgmerge -U po/es.po po/portkiller.pot
msgfmt po/es.po -o src/portkiller/locale/es/LC_MESSAGES/portkiller.mo

Arquitectura

src/portkiller/
├── core/            # lógica pura, sin GTK (testeable)
│   ├── scanner.py   # escaneo y deduplicación de sockets
│   ├── killer.py    # terminación segura con verificación de PID
│   ├── docker.py    # mapeo puerto → contenedor
│   ├── humanize.py  # descripciones legibles de procesos
│   ├── format.py    # formateo de duraciones y tamaños
│   └── config.py    # configuración de usuario
├── cli.py           # interfaz de terminal
├── gui/             # interfaz GTK4/libadwaita
├── tray.py          # icono de bandeja (GTK3 + AppIndicator, proceso aparte)
├── i18n.py          # gettext
└── locale/          # traducciones compiladas (.mo)

Historial de cambios

Consulta el CHANGELOG.

Licencia

MIT. Consulta el fichero LICENSE.