PortInspector

PortInspector is a lightweight, cross-platform developer utility for inspecting local network ports and the processes using them.

Built with pure Python standard library primitives, PortInspector requires zero runtime dependencies, installs instantly, and works across Windows, Linux, and macOS.

---

Key Features

• Instant Visibility: See all active and listening ports, addresses, PIDs, and process names in milliseconds.
• Port Inspection: Quickly check if a specific port is ACTIVE/LISTENING or AVAILABLE.
• Port Finder: Find the next available local port for web servers and microservices.
• Fast Range Scanning: Scan thousands of ports in milliseconds using OS connection caching.
• Process Inspection: View detailed process metadata (PID, executable path, command line, parent PID).
• Safe Process Termination: Kill hung processes with mandatory interactive confirmation and --yes automation support.
• Continuous Watch Mode: Real-time port monitoring that alerts when ports open or close.
• Structured JSON Output: Full --json support across commands for CI/CD pipelines, dev tooling, and scripts.
• Zero Dependencies: Pure Python with native platform integrations. No heavy C extensions or compilation required.

---

Installation

pip install portinspector

Or using uv:

uv tool install portinspector

---

Quick Reference

Command	Description
portinspector	Show all active/listening local ports with process details
portinspector 8000	Inspect port 8000 (status, process, PID, protocol, address)
portinspector --active	Show only active/listening ports
portinspector --scan 3000-9000	Scan a port range and summarize active vs available ports
portinspector --find	Find an available local port (defaults to starting at 8000)
portinspector --find 8000	Start at port 8000 and find the next available port
portinspector --process 8000	Show detailed process information for the process on port 8000
portinspector --kill 8000	Terminate the process using port 8000 (interactive confirmation)
portinspector --kill 8000 --yes	Terminate the process using port 8000 without prompting
portinspector --watch	Continuously monitor ports and report opened/closed events
portinspector --watch --interval 2	Monitor ports with a custom polling interval in seconds
portinspector --json	Output structured JSON suitable for scripts and automation
portinspector --version	Display version number
portinspector --help	Display help and usage manual

---

Usage Examples

1. List Active & Listening Ports

$ portinspector
PORT   PROTO  ADDRESS                    STATUS  PID    PROCESS
-----  -----  -------------------------  ------  -----  ---------------
22     TCP    0.0.0.0                    LISTEN  7104   sshd.exe
80     TCP    0.0.0.0                    LISTEN  1234   nginx
3000   TCP    127.0.0.1                  LISTEN  9821   node.exe
8000   TCP    127.0.0.1                  LISTEN  4218   python.exe

2. Inspect a Specific Port

$ portinspector 8000
Port 8000:
  Status:      ACTIVE/LISTENING
  Protocol:    TCP
  Address:     127.0.0.1
  Process:     python.exe
  PID:         4218

If the port is free:

$ portinspector 8001
Port 8001:
  Status:      AVAILABLE
  Message:     Port 8001 is available for use.

3. Find Next Available Port

Useful for configuring dev servers or automated tests:

$ portinspector --find 8000
Port 8000 is ACTIVE/LISTENING. Next available port is 8001.

$ portinspector --find 8000 --json
{
  "start_port": 8000,
  "available_port": 8001,
  "is_available": true
}

4. Scan a Port Range

$ portinspector --scan 3000-3005
Port Scan Summary (3000-3005):
  Total Scanned:    6
  Active Ports:     2
  Available Ports:  4

Active Ports:
PORT   PROTO  ADDRESS    STATUS  PID    PROCESS
-----  -----  ---------  ------  -----  -------
3000   TCP    127.0.0.1  LISTEN  9821   node.exe
3001   TCP    127.0.0.1  LISTEN  9822   vite.exe

Available Ports:
  3002, 3003, 3004, 3005

5. Detailed Process Information

$ portinspector --process 8000
Process Details (Port 8000):
  PID:         4218
  Name:        python.exe
  Status:      running
  Executable:  C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
  Command:     python -m http.server 8000
  Parent PID:  1024
  Ports Used:  8000

6. Terminate a Process Using a Port

PortInspector prioritizes safety. Process termination always prompts for explicit confirmation unless --yes is passed:

$ portinspector --kill 8000
============================================================
WARNING: DANGEROUS OPERATION - PROCESS TERMINATION
============================================================
Terminating this process will immediately close its network sockets
and may cause unsaved data loss or crash dependent applications.

  Port:         8000
  PID:          4218
  Process Name: python.exe
  Path:         C:\Users\developer\AppData\Local\Programs\Python\Python310\python.exe
  Command:      python -m http.server 8000
============================================================
Are you sure you want to terminate process 4218 (python.exe)? [y/N]: y
Successfully terminated process 4218 (python.exe) on port 8000.

For non-interactive scripts:

portinspector --kill 8000 --yes

7. Real-Time Watch Mode

Monitor ports dynamically as services spin up or shut down:

$ portinspector --watch --interval 1.5
[13:30:00] Monitoring listening ports every 1.5s (Press Ctrl+C to stop)...
[13:30:00] Initial state: 18 listening ports detected.
[13:30:04] [OPENED] Port 5173 (TCP) on 127.0.0.1 by vite (PID: 14205)
[13:30:22] [CLOSED] Port 5173 (TCP) (was vite (PID: 14205))
^C
[13:30:30] Monitoring stopped.

---

Platform Support & Architecture

PortInspector implements isolated, native OS providers:

• Windows (src/portinspector/platform/windows.py):
  • Leverages the Windows IP Helper API (iphlpapi.dll) via ctypes (GetExtendedTcpTable, GetExtendedUdpTable).
  • Fetches complete TCP and UDP connection tables directly in-memory without spawning slow subprocesses.
  • Fallback parser for netstat -ano.
  • Process queries via kernel32 (QueryFullProcessImageNameW) and WMI.
• Linux (src/portinspector/platform/linux.py):
  • Reads /proc/net/tcp, /proc/net/tcp6, /proc/net/udp, /proc/net/udp6.
  • Resolves socket inodes to PIDs via /proc/<pid>/fd/*.
  • Fallback parser for ss or netstat.
  • Reads /proc/<pid>/comm, cmdline, status, and exe.
• macOS (src/portinspector/platform/macos.py):
  • Built-in lsof parser with fallback to BSD netstat -anv.
  • Process metadata via ps.

Permissions

• Read-Only Inspection: Administrator/root privileges are never required for normal scanning.
• Permission Handling: When a process is owned by another user or system account, PortInspector still reports the active port, protocol, and address gracefully while noting when PID details are restricted by OS security boundaries.
• Process Termination: Terminating processes owned by other users or system services requires elevated privileges.

---

License

This project is licensed under the terms of the MIT License.