Know what you're killing.
Traditional port killers only show you a raw PID. portfind inspects the process to reveal which project it belongs to, its risk tier, command line, and whether a supervisor loop is keeping it alive.
Project Awareness
Scans package.json, Cargo.toml, go.mod, or Git roots so you immediately know which codebase started the service.
Risk Tiers
Categorizes processes as LOW, MEDIUM, or HIGH risk. Crucial system daemons and SSH sessions are strictly protected.
Port-Fight Radar
Detects when nodemon, pm2, or container supervisors respawn a process on the same port, warning you before entering an endless kill loop.
Docker & Containers
Distinguishes containerized services from host processes. Stops the Docker container safely rather than killing the Docker proxy PID.
Live Portfind Simulator
Try out Portfind directly in your browser. Switch between the interactive Terminal TUI, the raw CLI --json stream, and the Windows Notification Tray view:
| Port | PID | Process | Project Context | Uptime | Risk Tier | Action |
|---|---|---|---|---|---|---|
| :3000 | 14208 | node | ecommerce-web | 14m | LOW | |
| :5173 | 9812 | vite | dashboard-ui | 42m | LOW | |
| :5432 | 8216 | postgres | analytics-backend | 3d 4h | MEDIUM | |
| :6379 | 4104 | redisdocker: redis:7-alpine | cache-service | 5d 12h | LOW | |
| :22 | 924 | sshd | — | 18d | HIGH |
node server.js --env productionWhy portfind?
Tools like netstat, fuser, pik, or PortSlayer only answer one question: which process is on port 3000?Portfind answers: "What exactly am I about to kill, and is it safe?"
| Feature / Capability | Typical Port Killers | portfind |
|---|---|---|
| Port, PID, Process Name | ||
| Project Context (package.json, Cargo.toml, go.mod, Git) | ||
| Full Command Line inspection (node server.js vs just node.exe) | ||
| Process Uptime & Age calculation | ||
| Risk Tiers (LOW / MEDIUM / HIGH with safeguards) | ||
| Safe Pinning (pidfd / OS handles preventing recycled PID accidents) | ||
| Port-Fight Loop Detection (detects nodemon & supervisor respawns) | ||
| Docker container identification & graceful container stops | ||
| Persistent History (SQLite audit trail of freed ports) | ||
| Windows Notification Tray quick actions |
Installation Guide
Portfind is distributed as a single standalone binary with zero dependencies. Available for 64-bit Windows and Linux.
Windows Installation
Run this in PowerShell to install both the terminal UI (portfind) and the notification tray icon (portfind-tray):
irm https://raw.githubusercontent.com/rpratap2111/portfind/main/install.ps1 | iexmacOS Installation
Universal binary for Apple Silicon (M1/M2/M3/M4) and Intel (x86_64). Automatically configures ~/.zshrc:
curl -fsSL https://raw.githubusercontent.com/rpratap2111/portfind/main/install.sh | bashLinux Installation
Requires 64-bit Linux (x86_64 or arm64); works on any distro without root:
curl -fsSL https://raw.githubusercontent.com/rpratap2111/portfind/main/install.sh | bashGo Install (Cross-Platform)
If you have Go 1.22+ installed, you can build from the official module:
go install github.com/rpratap2111/portfind/cmd/portfind@latestUninstallation
To cleanly uninstall Portfind and remove PATH entries:
irm https://raw.githubusercontent.com/rpratap2111/portfind/main/uninstall.ps1 | iexcurl -fsSL https://raw.githubusercontent.com/rpratap2111/portfind/main/uninstall.sh | bashRisk Tiers Guide
Before stopping any process, Portfind assigns a risk rating to prevent accidental downtime and accidental machine lockouts:
Low Risk — Safe Dev Tools
Safe to stop anytime during typical dev work.
nodevitenextpythonuvicornflaskgocargo runrubyMedium Risk — Databases & Daemons
Local databases and background developer services.
postgresmysqldmongodredis-serverdocker-proxyCode / IDEHigh Risk — Core System & SSH
Critical system daemons and remote connectivity.
sshdsystemdsystemd-resolvedlsass.exewininit.execsrss.exeservices.exeProject Awareness (Provenance)
When node is listening on port 3000, is it your documentation server, your main API, or a colleague's background task?
Portfind climbs the process's working directory tree looking for project identity files:
package.json→ Reads the"name"field for Node / JavaScript / TypeScript appsCargo.toml→ Reads the[package].namefor Rust projectsgo.mod→ Resolves the Go module pathpyproject.toml/requirements.txt→ Resolves Python project directory.gitrepository root → Falls back to the enclosing repository folder name
Port-Fight Detection
Ever killed a process on port 3000 only to have another process immediately grab port 3000 one second later?
Portfind keeps an in-memory sliding window of port events. If a port is killed 3 times within 15 minutes, a warning badge appears next to the search box informing you that an auto-restarting supervisor (like nodemon, pm2, or docker-compose) is active.
Docker & Container Awareness
On systems running Docker, port forwarding often creates a docker-proxy process on the host. Killing that PID can leave Docker's daemon in an inconsistent state.
When Portfind inspects a listening port, it matches the port against the Docker socket. If the port is published by a container:
- It displays the Container Name and Image tag (e.g.
postgres:16). - Pressing kill invokes
docker stopdirectly on the container, gracefully letting the database or containerized service flush to disk.
Persistent History (SQLite)
Every port freed or terminated through Portfind (either via Terminal or Tray) is logged into an embedded SQLite database.
%LOCALAPPDATA%\portfind\history.db~/Library/Caches/portfind/history.db~/.cache/portfind/history.dbPress Tab inside the terminal UI to view your history log at any time.
Scripting with --json
portfind --json prints every listening port as JSON and exits immediately with code 0, without launching any UI or history store.
{
"ports": [
{
"port": 3000,
"pid": 14208,
"process": "node",
"project": "my-web-app",
"age_seconds": 840,
"risk": "LOW",
"command": "node server.js",
"parent_pid": 1204,
"parent_process": "cmd",
"container_id": null,
"image": null
}
],
"warnings": []
}PowerShell & jq Recipes
Copy-pasteable one-liners to integrate Portfind into build scripts and automated workflows.
PowerShell: Find all dev servers with a project name
(portfind --json | ConvertFrom-Json).ports | Where-Object project | Format-Table port, process, projectBash / jq: Filter ports by LOW risk tier
portfind --json | jq '.ports[] | select(.risk == "LOW") | {port, process, project}'PowerShell: Check if port 3000 is occupied
(portfind --json | ConvertFrom-Json).ports | Where-Object port -eq 3000TUI Keybindings
Every key you type goes into the live search box, so all controls live on non-typing keys:
| Key | Action |
|---|---|
↑ / ↓ | Navigate listening port entries |
Enter | Kill the highlighted process (with confirmation prompt) |
Tab | Switch between Active Ports and SQLite History view |
Ctrl + W | Open the Warnings view (permission issues / access denied details) |
Esc | Clear search box or close subviews |
Ctrl + C | Quit Portfind |
Platform & Limitations
portfind).On Windows, inspecting services owned by other users or elevated admins requires running Portfind as administrator. On macOS and Linux, run sudo portfind to inspect sockets owned by root or system daemons.
Port Troubleshooting Guides
Step-by-step fixes for "port already in use" errors, with and without portfind. All guides