portvac 0.1.0

See what's listening on a TCP port and free it - cross-platform, zero dependencies.

portvac

See what's listening on a TCP port - and free it. The "port already in use" error costs every developer a minute of lsof / netstat / taskkill archaeology. portvac lists who's on a port in one command, then vacates it on confirm. Cross-platform, zero dependencies.

pip install portvac
portvac             # list every listening TCP port
portvac 3000        # show what's on 3000, then kill it (asks first)
portvac 3000 -k     # kill without asking (scripts / CI)
portvac 3000 -s KILL   # SIGKILL instead of the default SIGTERM

Node shop? npx portvac 3000 -k works too - same tool, same behaviour.

Why

"Port 3000 is already in use" - and now you're pasting lsof -i :3000 into Stack Overflow for the fourth time this week.

lsof flags differ from netstat which differs from Windows taskkill. You remember none of them under pressure. portvac is the one command that works the same on macOS, Linux, and Windows: look first, kill second, never silent.

How it works

1. List - shells out to the platform's own tool (lsof / ss / netstat) to read listening sockets. No daemon, no network.
2. Show - prints a clean table: port, pid, process name, address, family.
3. Vacate - on a port argument, asks y/N, then sends a signal (default TERM) to the owning pid(s). -k skips the prompt.

Nothing is installed system-wide and no data leaves your machine.

Usage

portvac                       List every TCP port currently listening
portvac <port>                Show what's on <port>, then kill it (asks first)
portvac <port> --list         Show only, don't kill
portvac <port> -k             Kill without confirmation
portvac <port> -s KILL        Send KILL instead of TERM
portvac --json [<port>]       Machine-readable output (great for piping)

  -k, --force         Kill without confirmation
  -l, --list          List only; never kill
  -s, --signal <SIG>  TERM (default), KILL, INT, QUIT, HUP
      --json          Emit JSON; suppresses colors and prompts
  -v, --version

JSON

$ portvac --json 3000
{
  "port": 3000,
  "listeners": [
    { "port": 3000, "pid": 12345, "name": "node", "address": "0.0.0.0", "protocol": "tcp", "family": "ipv4" }
  ]
}

Platform notes

Platform	Lookup	Kill
macOS / BSD	lsof -iTCP -sTCP:LISTEN -P -n	os.kill(pid, sig)
Linux	ss -tlnp (falls back to netstat -tlnp)	os.kill(pid, sig)
Windows	netstat -ano + tasklist	taskkill /PID <pid> /F /T

On Windows there's no POSIX signal hierarchy, so portvac force-terminates (taskkill /F). To see another user's processes you may need elevated privileges, same as the underlying tools.

Exit codes

Code	Meaning
0	listed, or killed successfully
1	nothing listening / port not in use / aborted
2	error (bad args, tool missing, kill failed)

License

MIT